Widget Howto

This is how to make a widget or add a widget to your existing app.

• Add the following action to your activity

<action android:name="com.android.dxtop.launcher.DXWIDGET" />

• Your activity class should implement this interface. It allows the activity class to construct the view and return it to dxTop. If you don't want the widget to be created, throw a ProviderException in the View's constructor or onFinishInflate method with the message to be given to the user as the exception's message.

import java.security.ProviderException;

import android.content.Context;
import android.view.View;

//dxTop Widget v.2
public interface DxWidgetFactory
{
    // Returns the widget view or 
    // throws a java.security.ProviderException with a message for dxTop to show as to why it wasn't created
    public View createDxWidgetView( Context context ) throws ProviderException;
}

• The class that implements the widget view should implement this interface.

import android.content.Context;
import android.os.Bundle;

// dxTop Widget v.5
public interface DxWidget
{
    public void onDxWidgetCreate( Context context, long uniqueId, Bundle bundle );  // Called when instance is created.  Bundle can contain saved instance state  
    public Bundle onDxWidgetPause(); // Called before dxTop destroys the widget to save memory.  Save instance state in the bundle
    public void onDxWidgetRemoved(); // Called when the user deletes the widget
    public void onDxWidgetDestroy(); // Called when instance of widget is being released by dxTop
    public String[] onDxWidgetGetContextItems(); // Items to add to the long-click context menu or null
    public void onDxWidgetContextClick(int index); // Item choosen ion the long-click context menu or -1 if none were selected
}

• The root class of the view must contain two static fields. This is the number of cells wide and tall your widget will be. These need to be 4 or less as the desktop is only 4 cells across and 4 cells high.

public static int dxtopWidgetWidth = 1;
public static int dxtopWidgetHeight = 1;

• Don't post to the market with copy protection enabled as dxTop will be unable to read the widget and it wont work.

• Order of execution.

** Please not that widgets are not destroyed and recreated on orientation change, they are detached from their parent view and then re-attached. Since dxTop's Activity, Context and View are destroyed and recreated, it's important to do you registrations and unregistrations in the onAttachedToWindow and onDetacheFromWindow events instead of the onDxCreate and onDxDestroy events.

1. Widget's view is inflated
   1. the view's construtor is called
   2. the view's onFinishInflate() is called
2. onDxWidgetCreate() is called on view
3. Widget's view is attached to screen
   1. the view's onAttachToWindow() is called
4. onDxWidgetRemoved() is called on the view if the widget is being trashed by the user. onDxWidgetDestory() will be called next
5. onDxWidgetPause() is called on view if widget is being paused to save memory. onDxWidgetDestory() will be called next
6. Widget's view is detached to screen
   1. the view's onDetachFromWindow() is called
7. onDxWidgetDestory() is called on the view

Memory Monitor Widget Example

This is a simple graph that monitors available memory.

Download the source for my Memory Monitor widget here