Android APIs
public class

DreamService

extends Service
implements Window.Callback
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.service.dreams.DreamService

Class Overview

Extend this class to implement a custom dream (available to the user as a "Daydream").

Dreams are interactive screensavers launched when a charging device is idle, or docked in a desk dock. Dreams provide another modality for apps to express themselves, tailored for an exhibition/lean-back experience.

The DreamService lifecycle is as follows:

  1. onAttachedToWindow()

    Use this for initial setup, such as calling setContentView().

  2. onDreamingStarted()

    Your dream has started, so you should begin animations or other behaviors here.

  3. onDreamingStopped()

    Use this to stop the things you started in onDreamingStarted().

  4. onDetachedFromWindow()

    Use this to dismantle resources (for example, detach from handlers and listeners).

In addition, onCreate and onDestroy (from the Service interface) will also be called, but initialization and teardown should be done by overriding the hooks above.

To be available to the system, your DreamService should be declared in the manifest as follows:

 <service
     android:name=".MyDream"
     android:exported="true"
     android:icon="@drawable/my_icon"
     android:label="@string/my_dream_label" >

     <intent-filter>
         <action android:name="android.service.dreams.DreamService" />
         <category android:name="android.intent.category.DEFAULT" />
     </intent-filter>

     <!-- Point to additional information for this dream (optional) -->
     <meta-data
         android:name="android.service.dream"
         android:resource="@xml/my_dream" />
 </service>

If specified with the <meta-data> element, additional information for the dream is defined using the <dream> element in a separate XML file. Currently, the only addtional information you can provide is for a settings activity that allows the user to configure the dream behavior. For example:

res/xml/my_dream.xml

 <dream xmlns:android="http://schemas.android.com/apk/res/android"
     android:settingsActivity="com.example.app/.MyDreamSettingsActivity" />

This makes a Settings button available alongside your dream's listing in the system settings, which when pressed opens the specified activity.

To specify your dream layout, call setContentView(View), typically during the onAttachedToWindow() callback. For example:

 public class MyDream extends DreamService {

     @Override
     public void onAttachedToWindow() {
         super.onAttachedToWindow();

         // Exit dream upon user touch
         setInteractive(false);
         // Hide system UI
         setFullscreen(true);
         // Set the dream layout
         setContentView(R.layout.dream);
     }
 }

Summary

Constants
String DREAM_META_DATA Name under which a Dream publishes information about itself.
String SERVICE_INTERFACE The Intent that must be declared as handled by the service.
[Expand]
Inherited Constants
From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2
Public Constructors
DreamService()
Public Methods
void addContentView(View view, ViewGroup.LayoutParams params)
Adds a view to the Dream's window, leaving other content views in place.
boolean dispatchGenericMotionEvent(MotionEvent event)
Called to process generic motion events.
boolean dispatchKeyEvent(KeyEvent event)
Called to process key events.
boolean dispatchKeyShortcutEvent(KeyEvent event)
Called to process a key shortcut event.
boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event)
Called to process population of AccessibilityEvents.
boolean dispatchTouchEvent(MotionEvent event)
Called to process touch screen events.
boolean dispatchTrackballEvent(MotionEvent event)
Called to process trackball events.
View findViewById(int id)
Finds a view that was identified by the id attribute from the XML that was processed in onCreate().
final void finish()
Stops the dream and detaches from the window.
Window getWindow()
Retrieves the current Window for the dream.
WindowManager getWindowManager()
Retrieves the current WindowManager for the dream.
boolean isFullscreen()
Returns whether or not this dream is in fullscreen mode.
boolean isInteractive()
Returns whether or not this dream is interactive.
boolean isScreenBright()
Returns whether or not this dream keeps the screen bright while dreaming.
void onActionModeFinished(ActionMode mode)
Called when an action mode has been finished.
void onActionModeStarted(ActionMode mode)
Called when an action mode has been started.
void onAttachedToWindow()
Called when the window has been attached to the window manager.
final IBinder onBind(Intent intent)
Return the communication channel to the service.
void onContentChanged()
This hook is called whenever the content view of the screen changes (due to a call to Window.setContentView or Window.addContentView).
void onCreate()
Called when this Dream is constructed.
boolean onCreatePanelMenu(int featureId, Menu menu)
Initialize the contents of the menu for panel 'featureId'.
View onCreatePanelView(int featureId)
Instantiate the view to display in the panel for 'featureId'.
void onDestroy()
Called by the system to notify a Service that it is no longer used and is being removed.
void onDetachedFromWindow()
Called when the window has been attached to the window manager.
void onDreamingStarted()
Called when the dream's window has been created and is visible and animation may now begin.
void onDreamingStopped()
Called when this Dream is stopped, either by external request or by calling finish(), before the window has been removed.
boolean onMenuItemSelected(int featureId, MenuItem item)
Called when a panel's menu item has been selected by the user.
boolean onMenuOpened(int featureId, Menu menu)
Called when a panel's menu is opened by the user.
void onPanelClosed(int featureId, Menu menu)
Called when a panel is being closed.
boolean onPreparePanel(int featureId, View view, Menu menu)
Prepare a panel to be displayed.
boolean onSearchRequested()
Called when the user signals the desire to start a search.
void onWindowAttributesChanged(WindowManager.LayoutParams attrs)
This is called whenever the current window attributes change.
void onWindowFocusChanged(boolean hasFocus)
This hook is called whenever the window focus changes.
ActionMode onWindowStartingActionMode(ActionMode.Callback callback)
Called when an action mode is being started for this window.
void setContentView(View view)
Sets a view to be the content view for this Dream.
void setContentView(int layoutResID)
Inflates a layout resource and set it to be the content view for this Dream.
void setContentView(View view, ViewGroup.LayoutParams params)
Sets a view to be the content view for this Dream.
void setFullscreen(boolean fullscreen)
Controls FLAG_FULLSCREEN on the dream's window.
void setInteractive(boolean interactive)
Marks this dream as interactive to receive input events.
void setScreenBright(boolean screenBright)
Marks this dream as keeping the screen bright while dreaming.
Protected Methods
void dump(FileDescriptor fd, PrintWriter pw, String[] args)
Print the Service's state into the given stream.
[Expand]
Inherited Methods
From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks
From interface android.content.ComponentCallbacks2
From interface android.view.Window.Callback

Constants

public static final String DREAM_META_DATA

Added in API level 17

Name under which a Dream publishes information about itself. This meta-data must reference an XML resource containing a <dream> tag.

Constant Value: "android.service.dream"

public static final String SERVICE_INTERFACE

Added in API level 17

The Intent that must be declared as handled by the service.

Constant Value: "android.service.dreams.DreamService"

Public Constructors

public DreamService ()

Added in API level 17

Public Methods

public void addContentView (View view, ViewGroup.LayoutParams params)

Added in API level 17

Adds a view to the Dream's window, leaving other content views in place.

Note: Requires a window, do not call before onAttachedToWindow()

Parameters
view The desired content to display.
params Layout parameters for the view.

public boolean dispatchGenericMotionEvent (MotionEvent event)

Added in API level 17

Called to process generic motion events. At the very least your implementation must call superDispatchGenericMotionEvent(MotionEvent) to do the standard processing.

Parameters
event The generic motion event.
Returns
  • boolean Return true if this event was consumed.

public boolean dispatchKeyEvent (KeyEvent event)

Added in API level 17

Called to process key events. At the very least your implementation must call superDispatchKeyEvent(KeyEvent) to do the standard key processing.

Parameters
event The key event.
Returns
  • boolean Return true if this event was consumed.

public boolean dispatchKeyShortcutEvent (KeyEvent event)

Added in API level 17

Called to process a key shortcut event. At the very least your implementation must call superDispatchKeyShortcutEvent(KeyEvent) to do the standard key shortcut processing.

Parameters
event The key shortcut event.
Returns
  • True if this event was consumed.

public boolean dispatchPopulateAccessibilityEvent (AccessibilityEvent event)

Added in API level 17

Called to process population of AccessibilityEvents.

Parameters
event The event.
Returns
  • boolean Return true if event population was completed.

public boolean dispatchTouchEvent (MotionEvent event)

Added in API level 17

Called to process touch screen events. At the very least your implementation must call superDispatchTouchEvent(MotionEvent) to do the standard touch screen processing.

Parameters
event The touch screen event.
Returns
  • boolean Return true if this event was consumed.

public boolean dispatchTrackballEvent (MotionEvent event)

Added in API level 17

Called to process trackball events. At the very least your implementation must call superDispatchTrackballEvent(MotionEvent) to do the standard trackball processing.

Parameters
event The trackball event.
Returns
  • boolean Return true if this event was consumed.

public View findViewById (int id)

Added in API level 17

Finds a view that was identified by the id attribute from the XML that was processed in onCreate().

Note: Requires a window, do not call before onAttachedToWindow()

Returns
  • The view if found or null otherwise.

public final void finish ()

Added in API level 17

Stops the dream and detaches from the window.

When the dream ends, the system will be allowed to go to sleep fully unless there is a reason for it to be awake such as recent user activity or wake locks being held.

public Window getWindow ()

Added in API level 17

Retrieves the current Window for the dream. Behaves similarly to getWindow().

Returns
  • The current window, or null if the dream is not started.

public WindowManager getWindowManager ()

Added in API level 17

Retrieves the current WindowManager for the dream. Behaves similarly to getWindowManager().

Returns
  • The current window manager, or null if the dream is not started.

public boolean isFullscreen ()

Added in API level 17

Returns whether or not this dream is in fullscreen mode. Defaults to false.

See Also

public boolean isInteractive ()

Added in API level 17

Returns whether or not this dream is interactive. Defaults to false.

See Also

public boolean isScreenBright ()

Added in API level 17

Returns whether or not this dream keeps the screen bright while dreaming. Defaults to false, allowing the screen to dim if necessary.

See Also

public void onActionModeFinished (ActionMode mode)

Added in API level 17

Called when an action mode has been finished. The appropriate mode callback method will have already been invoked.

Parameters
mode The mode that was just finished.

public void onActionModeStarted (ActionMode mode)

Added in API level 17

Called when an action mode has been started. The appropriate mode callback method will have already been invoked.

Parameters
mode The new mode that has just been started.

public void onAttachedToWindow ()

Added in API level 17

Called when the window has been attached to the window manager. See View.onAttachedToWindow() for more information.

public final IBinder onBind (Intent intent)

Added in API level 17

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Returns
  • Return an IBinder through which clients can call on to the service.

public void onContentChanged ()

Added in API level 17

This hook is called whenever the content view of the screen changes (due to a call to Window.setContentView or Window.addContentView).

public void onCreate ()

Added in API level 17

Called when this Dream is constructed.

public boolean onCreatePanelMenu (int featureId, Menu menu)

Added in API level 17

Initialize the contents of the menu for panel 'featureId'. This is called if onCreatePanelView() returns null, giving you a standard menu in which you can place your items. It is only called once for the panel, the first time it is shown.

You can safely hold on to menu (and any items created from it), making modifications to it as desired, until the next time onCreatePanelMenu() is called for this feature.

Parameters
featureId The panel being created.
menu The menu inside the panel.
Returns
  • boolean You must return true for the panel to be displayed; if you return false it will not be shown.

public View onCreatePanelView (int featureId)

Added in API level 17

Instantiate the view to display in the panel for 'featureId'. You can return null, in which case the default content (typically a menu) will be created for you.

Parameters
featureId Which panel is being created.
Returns
  • view The top-level view to place in the panel.

public void onDestroy ()

Added in API level 17

Called by the system to notify a Service that it is no longer used and is being removed. The service should clean up any resources it holds (threads, registered receivers, etc) at this point. Upon return, there will be no more calls in to this Service object and it is effectively dead. Do not call this method directly.

public void onDetachedFromWindow ()

Added in API level 17

Called when the window has been attached to the window manager. See View.onDetachedFromWindow() for more information.

public void onDreamingStarted ()

Added in API level 17

Called when the dream's window has been created and is visible and animation may now begin.

public void onDreamingStopped ()

Added in API level 17

Called when this Dream is stopped, either by external request or by calling finish(), before the window has been removed.

public boolean onMenuItemSelected (int featureId, MenuItem item)

Added in API level 17

Called when a panel's menu item has been selected by the user.

Parameters
featureId The panel that the menu is in.
item The menu item that was selected.
Returns
  • boolean Return true to finish processing of selection, or false to perform the normal menu handling (calling its Runnable or sending a Message to its target Handler).

public boolean onMenuOpened (int featureId, Menu menu)

Added in API level 17

Called when a panel's menu is opened by the user. This may also be called when the menu is changing from one type to another (for example, from the icon menu to the expanded menu).

Parameters
featureId The panel that the menu is in.
menu The menu that is opened.
Returns
  • Return true to allow the menu to open, or false to prevent the menu from opening.

public void onPanelClosed (int featureId, Menu menu)

Added in API level 17

Called when a panel is being closed. If another logical subsequent panel is being opened (and this panel is being closed to make room for the subsequent panel), this method will NOT be called.

Parameters
featureId The panel that is being displayed.
menu If onCreatePanelView() returned null, this is the Menu being displayed in the panel.

public boolean onPreparePanel (int featureId, View view, Menu menu)

Added in API level 17

Prepare a panel to be displayed. This is called right before the panel window is shown, every time it is shown.

Parameters
featureId The panel that is being displayed.
view The View that was returned by onCreatePanelView().
menu If onCreatePanelView() returned null, this is the Menu being displayed in the panel.
Returns
  • boolean You must return true for the panel to be displayed; if you return false it will not be shown.

public boolean onSearchRequested ()

Added in API level 17

Called when the user signals the desire to start a search.

Returns
  • true if search launched, false if activity refuses (blocks)

public void onWindowAttributesChanged (WindowManager.LayoutParams attrs)

Added in API level 17

This is called whenever the current window attributes change.

public void onWindowFocusChanged (boolean hasFocus)

Added in API level 17

This hook is called whenever the window focus changes. See View.onWindowFocusChanged(boolean) for more information.

Parameters
hasFocus Whether the window now has focus.

public ActionMode onWindowStartingActionMode (ActionMode.Callback callback)

Added in API level 17

Called when an action mode is being started for this window. Gives the callback an opportunity to handle the action mode in its own unique and beautiful way. If this method returns null the system can choose a way to present the mode or choose not to start the mode at all.

Parameters
callback Callback to control the lifecycle of this action mode
Returns
  • The ActionMode that was started, or null if the system should present it

public void setContentView (View view)

Added in API level 17

Sets a view to be the content view for this Dream. Behaves similarly to setContentView(android.view.View) in an activity, including using MATCH_PARENT as the layout height and width of the view.

Note: This requires a window, so you should usually call it during onAttachedToWindow() and never earlier (you cannot call it during onCreate()).

See Also

public void setContentView (int layoutResID)

Added in API level 17

Inflates a layout resource and set it to be the content view for this Dream. Behaves similarly to setContentView(int).

Note: Requires a window, do not call before onAttachedToWindow()

Parameters
layoutResID Resource ID to be inflated.
See Also

public void setContentView (View view, ViewGroup.LayoutParams params)

Added in API level 17

Sets a view to be the content view for this Dream. Behaves similarly to setContentView(android.view.View, android.view.ViewGroup.LayoutParams) in an activity.

Note: This requires a window, so you should usually call it during onAttachedToWindow() and never earlier (you cannot call it during onCreate()).

Parameters
view The desired content to display.
params Layout parameters for the view.
See Also

public void setFullscreen (boolean fullscreen)

Added in API level 17

Controls FLAG_FULLSCREEN on the dream's window.

Parameters
fullscreen If true, the fullscreen flag will be set; else it will be cleared.

public void setInteractive (boolean interactive)

Added in API level 17

Marks this dream as interactive to receive input events.

Non-interactive dreams (default) will dismiss on the first input event.

Interactive dreams should call finish() to dismiss themselves.

Parameters
interactive True if this dream will handle input events.

public void setScreenBright (boolean screenBright)

Added in API level 17

Marks this dream as keeping the screen bright while dreaming.

Parameters
screenBright True to keep the screen bright while dreaming.

Protected Methods

protected void dump (FileDescriptor fd, PrintWriter pw, String[] args)

Added in API level 17

Print the Service's state into the given stream. This gets invoked if you run "adb shell dumpsys activity service <yourservicename>" (note that for this command to work, the service must be running, and you must specify a fully-qualified service name). This is distinct from "dumpsys <servicename>", which only works for named system services and which invokes the dump(FileDescriptor, String[]) method on the IBinder interface registered with ServiceManager.

Parameters
fd The raw file descriptor that the dump is being sent to.
pw The PrintWriter to which you should dump your state. This will be closed for you after you return.
args additional arguments to the dump request.