com.google.android.apps.dashclock.api
Class DashClockExtension

java.lang.Object
  extended by android.content.Context
      extended by android.content.ContextWrapper
          extended by android.app.Service
              extended by com.google.android.apps.dashclock.api.DashClockExtension
All Implemented Interfaces:
ComponentCallbacks, ComponentCallbacks2
public abstract class DashClockExtension
extends Service

Base class for a DashClock extension. Extensions are a way for other apps to show additional status information within DashClock widgets that the user may add to the lockscreen or home screen. A limited amount of status information is supported. See the ExtensionData class for the types of information that can be displayed.

Subclassing DashClockExtension

Subclasses must implement at least the onUpdateData(int) method, which will be called when DashClock requests updated data to show for this extension. Once the extension has new data to show, call publishUpdate(ExtensionData) to pass the data to the main DashClock process. onUpdateData(int) will by default be called roughly once per hour, but extensions can use methods such as setUpdateWhenScreenOn(boolean) and addWatchContentUris(String[]) to request more frequent updates.

Subclasses can also override the onInitialize(boolean) method to perform basic initialization each time a connection to DashClock is established or re-established.

Registering extensions

An extension is simply a service that the DashClock process binds to. Subclasses of this base DashClockExtension class should thus be declared as <service> components in the application's AndroidManifest.xml file.

The main DashClock app discovers available extensions using Android's Intent mechanism. Ensure that your service definition includes an <intent-filter> with an action of ACTION_EXTENSION. Also make sure to require the PERMISSION_READ_EXTENSION_DATA permission so that only DashClock can bind to your service and request updates. Lastly, there are a few <meta-data> elements that you should add to your service definition:

Example

Below is an example extension declaration in the manifest: 
 <service android:name=".ExampleExtension"
     android:icon="@drawable/ic_extension_example"
     android:label="@string/extension_title"
     android:permission="com.google.android.apps.dashclock.permission.READ_EXTENSION_DATA">
     <intent-filter>
         <action android:name="com.google.android.apps.dashclock.Extension" />
     </intent-filter>
     <meta-data android:name="protocolVersion" android:value="2" />
     <meta-data android:name="worldReadable" android:value="true" />
     <meta-data android:name="description"
         android:value="@string/extension_description" />
     <!-- A settings activity is optional -->
     <meta-data android:name="settingsActivity"
         android:value=".ExampleSettingsActivity" />
 </service>
If a settingsActivity meta-data element is present, an activity with the given component name should be defined and exported in the application's manifest as well. DashClock will set the EXTRA_FROM_DASHCLOCK_SETTINGS extra to true in the launch intent for this activity. An example is shown below: 
 <activity android:name=".ExampleSettingsActivity"
     android:label="@string/title_settings"
     android:exported="true" />
Finally, below is a simple example DashClockExtension subclass that shows static data in DashClock: 
 public class ExampleExtension extends DashClockExtension {
     protected void onUpdateData(int reason) {
         publishUpdate(new ExtensionData()
                 .visible(true)
                 .icon(R.drawable.ic_extension_example)
                 .status("Hello")
                 .expandedTitle("Hello, world!")
                 .expandedBody("This is an example.")
                 .clickIntent(new Intent(Intent.ACTION_VIEW,
                         Uri.parse("http://www.google.com"))));
     }
 }

Field Summary
static String ACTION_EXTENSION
          The Intent action representing a DashClock extension.
static String EXTRA_FROM_DASHCLOCK_SETTINGS
          Boolean extra that will be set to true when DashClock starts extension settings activities.
static String PERMISSION_READ_EXTENSION_DATA
          The permission that DashClock extensions should require callers to have before providing any status updates.
static int UPDATE_REASON_CONTENT_CHANGED
          Indicates that onUpdateData(int) was triggered because content changed on a content URI previously registered with addWatchContentUris(String[]).
static int UPDATE_REASON_INITIAL
          Indicates that this is the first call to onUpdateData(int) since the connection to the main DashClock app was established.
static int UPDATE_REASON_MANUAL
          Indicates that onUpdateData(int) was triggered because the user explicitly requested that the extension be updated.
static int UPDATE_REASON_PERIODIC
          Indicates that onUpdateData(int) was triggered due to a normal perioidic refresh of extension data.
static int UPDATE_REASON_SCREEN_ON
          Indicates that onUpdateData(int) was triggered because the device screen turned on and the extension has called setUpdateWhenScreenOn(true).
static int UPDATE_REASON_SETTINGS_CHANGED
          Indicates that onUpdateData(int) was triggered because settings for this extension may have changed.
static int UPDATE_REASON_UNKNOWN
          Indicates that onUpdateData(int) was triggered for an unknown reason.
 
Fields inherited from class android.app.Service
START_CONTINUATION_MASK, START_FLAG_REDELIVERY, START_FLAG_RETRY, START_NOT_STICKY, START_REDELIVER_INTENT, START_STICKY, START_STICKY_COMPATIBILITY
 
Fields inherited from class android.content.Context
ACCESSIBILITY_SERVICE, ACCOUNT_SERVICE, ACTIVITY_SERVICE, ALARM_SERVICE, AUDIO_SERVICE, BIND_ABOVE_CLIENT, BIND_ADJUST_WITH_ACTIVITY, BIND_ALLOW_OOM_MANAGEMENT, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, BIND_IMPORTANT, BIND_NOT_FOREGROUND, BIND_WAIVE_PRIORITY, CLIPBOARD_SERVICE, CONNECTIVITY_SERVICE, CONTEXT_IGNORE_SECURITY, CONTEXT_INCLUDE_CODE, CONTEXT_RESTRICTED, DEVICE_POLICY_SERVICE, DISPLAY_SERVICE, DOWNLOAD_SERVICE, DROPBOX_SERVICE, INPUT_METHOD_SERVICE, INPUT_SERVICE, KEYGUARD_SERVICE, LAYOUT_INFLATER_SERVICE, LOCATION_SERVICE, MEDIA_ROUTER_SERVICE, MODE_APPEND, MODE_ENABLE_WRITE_AHEAD_LOGGING, MODE_MULTI_PROCESS, MODE_PRIVATE, MODE_WORLD_READABLE, MODE_WORLD_WRITEABLE, NFC_SERVICE, NOTIFICATION_SERVICE, NSD_SERVICE, POWER_SERVICE, SEARCH_SERVICE, SENSOR_SERVICE, STORAGE_SERVICE, TELEPHONY_SERVICE, TEXT_SERVICES_MANAGER_SERVICE, UI_MODE_SERVICE, USB_SERVICE, USER_SERVICE, VIBRATOR_SERVICE, WALLPAPER_SERVICE, WIFI_P2P_SERVICE, WIFI_SERVICE, WINDOW_SERVICE
 
Fields inherited from interface android.content.ComponentCallbacks2
TRIM_MEMORY_BACKGROUND, TRIM_MEMORY_COMPLETE, TRIM_MEMORY_MODERATE, TRIM_MEMORY_RUNNING_CRITICAL, TRIM_MEMORY_RUNNING_LOW, TRIM_MEMORY_RUNNING_MODERATE, TRIM_MEMORY_UI_HIDDEN
 
Constructor Summary
protected DashClockExtension()
           
 
Method Summary
protected  void addWatchContentUris(String[] uris)
          Requests that the main DashClock app watch the given content URIs (using ContentResolver.registerContentObserver) and call this extension's onUpdateData(int) method when changes are observed.
 IBinder onBind(Intent intent)
           
 void onCreate()
           
 void onDestroy()
           
protected  void onInitialize(boolean isReconnect)
          Called when a connection with the main DashClock app has been established or re-established after a previous one was lost.
protected abstract  void onUpdateData(int reason)
          Called when the DashClock app process is requesting that the extension provide updated information to show to the user.
protected  void publishUpdate(ExtensionData data)
          Notifies the main DashClock app that new data is available for the extension and should potentially be shown to the user.
protected  void removeAllWatchContentUris()
          Requests that the main DashClock app stop watching all content URIs previously registered with addWatchContentUris(String[]) for this extension.
protected  void setUpdateWhenScreenOn(boolean updateWhenScreenOn)
          Requests that the main DashClock app call (or not call) this extension's onUpdateData(int) method when the screen turns on (the phone resumes from idle).
 
Methods inherited from class android.app.Service
dump, getApplication, onConfigurationChanged, onLowMemory, onRebind, onStart, onStartCommand, onTaskRemoved, onTrimMemory, onUnbind, startForeground, stopForeground, stopSelf, stopSelf, stopSelfResult
 
Methods inherited from class android.content.ContextWrapper
attachBaseContext, bindService, checkCallingOrSelfPermission, checkCallingOrSelfUriPermission, checkCallingPermission, checkCallingUriPermission, checkPermission, checkUriPermission, checkUriPermission, clearWallpaper, createConfigurationContext, createDisplayContext, createPackageContext, databaseList, deleteDatabase, deleteFile, enforceCallingOrSelfPermission, enforceCallingOrSelfUriPermission, enforceCallingPermission, enforceCallingUriPermission, enforcePermission, enforceUriPermission, enforceUriPermission, fileList, getApplicationContext, getApplicationInfo, getAssets, getBaseContext, getCacheDir, getClassLoader, getContentResolver, getDatabasePath, getDir, getExternalCacheDir, getExternalFilesDir, getFilesDir, getFileStreamPath, getMainLooper, getObbDir, getPackageCodePath, getPackageManager, getPackageName, getPackageResourcePath, getResources, getSharedPreferences, getSystemService, getTheme, getWallpaper, getWallpaperDesiredMinimumHeight, getWallpaperDesiredMinimumWidth, grantUriPermission, isRestricted, openFileInput, openFileOutput, openOrCreateDatabase, openOrCreateDatabase, peekWallpaper, registerReceiver, registerReceiver, removeStickyBroadcast, removeStickyBroadcastAsUser, revokeUriPermission, sendBroadcast, sendBroadcast, sendBroadcastAsUser, sendBroadcastAsUser, sendOrderedBroadcast, sendOrderedBroadcast, sendOrderedBroadcastAsUser, sendStickyBroadcast, sendStickyBroadcastAsUser, sendStickyOrderedBroadcast, sendStickyOrderedBroadcastAsUser, setTheme, setWallpaper, setWallpaper, startActivities, startActivities, startActivity, startActivity, startInstrumentation, startIntentSender, startIntentSender, startService, stopService, unbindService, unregisterReceiver
 
Methods inherited from class android.content.Context
getString, getString, getText, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, registerComponentCallbacks, unregisterComponentCallbacks
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ACTION_EXTENSION

public static final String ACTION_EXTENSION
The Intent action representing a DashClock extension. This service should declare an <intent-filter> for this action in order to register with DashClock.

See Also:
Constant Field Values

EXTRA_FROM_DASHCLOCK_SETTINGS

public static final String EXTRA_FROM_DASHCLOCK_SETTINGS
Boolean extra that will be set to true when DashClock starts extension settings activities. Check for this extra in your settings activity if you need to adjust your UI depending on whether or not the user came from DashClock's settings screen.

Since:
Protocol Version 2 (API r2.x)
See Also:
Constant Field Values

PERMISSION_READ_EXTENSION_DATA

public static final String PERMISSION_READ_EXTENSION_DATA
The permission that DashClock extensions should require callers to have before providing any status updates. Permission checks are implemented automatically by the base class.

See Also:
Constant Field Values

UPDATE_REASON_CONTENT_CHANGED

public static final int UPDATE_REASON_CONTENT_CHANGED
Indicates that onUpdateData(int) was triggered because content changed on a content URI previously registered with addWatchContentUris(String[]).

See Also:
Constant Field Values

UPDATE_REASON_INITIAL

public static final int UPDATE_REASON_INITIAL
Indicates that this is the first call to onUpdateData(int) since the connection to the main DashClock app was established. Note that updates aren't requested in response to reconnections after a connection is lost.

See Also:
Constant Field Values

UPDATE_REASON_MANUAL

public static final int UPDATE_REASON_MANUAL
Indicates that onUpdateData(int) was triggered because the user explicitly requested that the extension be updated.

Since:
Protocol Version 2 (API r2.x)
See Also:
Constant Field Values

UPDATE_REASON_PERIODIC

public static final int UPDATE_REASON_PERIODIC
Indicates that onUpdateData(int) was triggered due to a normal perioidic refresh of extension data.

See Also:
Constant Field Values

UPDATE_REASON_SCREEN_ON

public static final int UPDATE_REASON_SCREEN_ON
Indicates that onUpdateData(int) was triggered because the device screen turned on and the extension has called setUpdateWhenScreenOn(true).

See Also:
Constant Field Values

UPDATE_REASON_SETTINGS_CHANGED

public static final int UPDATE_REASON_SETTINGS_CHANGED
Indicates that onUpdateData(int) was triggered because settings for this extension may have changed.

See Also:
Constant Field Values

UPDATE_REASON_UNKNOWN

public static final int UPDATE_REASON_UNKNOWN
Indicates that onUpdateData(int) was triggered for an unknown reason. This should be treated as a generic update (similar to UPDATE_REASON_PERIODIC.

See Also:
Constant Field Values
Constructor Detail

DashClockExtension

protected DashClockExtension()
Method Detail

addWatchContentUris

protected final void addWatchContentUris(String[] uris)
Requests that the main DashClock app watch the given content URIs (using ContentResolver.registerContentObserver) and call this extension's onUpdateData(int) method when changes are observed. This should generally be called in the onInitialize(boolean) method.

Parameters:
uris - The URIs to watch.

onBind

public final IBinder onBind(Intent intent)
Specified by:
onBind in class Service

onCreate

public void onCreate()
Overrides:
onCreate in class Service

onDestroy

public void onDestroy()
Overrides:
onDestroy in class Service

onInitialize

protected void onInitialize(boolean isReconnect)
Called when a connection with the main DashClock app has been established or re-established after a previous one was lost. In this latter case, the parameter isReconnect will be true. Override this method to perform basic extension initialization before calls to onUpdateData(int) are made.

Parameters:
isReconnect - Whether or not this call is being made after a connection was dropped and a new connection has been established.

onUpdateData

protected abstract void onUpdateData(int reason)
Called when the DashClock app process is requesting that the extension provide updated information to show to the user. Implementations can choose to do nothing, or more commonly, provide an update using the publishUpdate(ExtensionData) method. Note that doing nothing doesn't clear existing data. To clear any existing data, call publishUpdate(ExtensionData) with null data.

Parameters:
reason - The reason for the update. See UPDATE_REASON_PERIODIC and related constants for more details.

publishUpdate

protected final void publishUpdate(ExtensionData data)
Notifies the main DashClock app that new data is available for the extension and should potentially be shown to the user. Note that this call does not necessarily need to be made from inside the onUpdateData(int) method, but can be made only after onInitialize(boolean) has been called. If you only call this from within onUpdateData(int) this is already ensured.

Parameters:
data - The data to show, or null if existing data should be cleared (hiding the extension from view).

removeAllWatchContentUris

protected final void removeAllWatchContentUris()
Requests that the main DashClock app stop watching all content URIs previously registered with addWatchContentUris(String[]) for this extension.

Parameters:
uris - The URIs to watch.
Since:
Protocol Version 2 (API r2.x)

setUpdateWhenScreenOn

protected final void setUpdateWhenScreenOn(boolean updateWhenScreenOn)
Requests that the main DashClock app call (or not call) this extension's onUpdateData(int) method when the screen turns on (the phone resumes from idle). This should generally be called in the onInitialize(boolean) method. By default, extensions do not get updated when the screen turns on.

Parameters:
updateWhenScreenOn - Whether or not a call to onUpdateData(int) method when the screen turns on.
See Also:
Intent.ACTION_SCREEN_ON