DreamService
open class DreamService : Service, Window.Callback
kotlin.Any | ||||
↳ | android.content.Context | |||
↳ | android.content.ContextWrapper | |||
↳ | android.app.Service | |||
↳ | android.service.dreams.DreamService |
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:
onAttachedToWindow
Use this for initial setup, such as calling #setContentView.
onDreamingStarted
Your dream has started, so you should begin animations or other behaviors here.
onDreamingStopped
Use this to stop the things you started in
onDreamingStarted
.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 additional 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, 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); } }
When targeting api level 21 and above, you must declare the service in your manifest file with the android.Manifest.permission#BIND_DREAM_SERVICE
permission. For example:
<service android:name=".MyDream" android:exported="true" android:icon="@drawable/my_icon" android:label="@string/my_dream_label" android:permission="android.permission.BIND_DREAM_SERVICE"> <intent-filter> <action android:name=”android.service.dreams.DreamService” /> <category android:name=”android.intent.category.DEFAULT” /> </intent-filter> </service>
Summary
Constants | |
---|---|
static String |
Name under which a Dream publishes information about itself. |
static String |
The |
Inherited constants | |
---|---|
Public constructors | |
---|---|
Public methods | |
---|---|
open Unit |
addContentView(view: View!, params: ViewGroup.LayoutParams!) Adds a view to the Dream's window, leaving other content views in place. |
open Boolean |
dispatchGenericMotionEvent(event: MotionEvent!) Called to process generic motion events. |
open Boolean |
dispatchKeyEvent(event: KeyEvent!) Called to process key events. |
open Boolean |
dispatchKeyShortcutEvent(event: KeyEvent!) Called to process a key shortcut event. |
open Boolean |
Called to process population of |
open Boolean |
dispatchTouchEvent(event: MotionEvent!) Called to process touch screen events. |
open Boolean |
dispatchTrackballEvent(event: MotionEvent!) Called to process trackball events. |
open T |
findViewById(id: Int) Finds a view that was identified by the id attribute from the XML that was processed in |
Unit |
finish() Stops the dream and detaches from the window. |
open Window! |
Retrieves the current |
open WindowManager! |
Retrieves the current |
open Boolean |
Returns whether this dream is in fullscreen mode. |
open Boolean |
Returns whether this dream is interactive. |
open Boolean |
Returns whether this dream keeps the screen bright while dreaming. |
open Unit |
onActionModeFinished(mode: ActionMode!) Called when an action mode has been finished. |
open Unit |
onActionModeStarted(mode: ActionMode!) Called when an action mode has been started. |
open Unit |
Called when the window has been attached to the window manager. |
IBinder? |
Return the communication channel to the service. |
open Unit |
This hook is called whenever the content view of the screen changes (due to a call to |
open Unit |
onCreate() Called when this Dream is constructed. |
open Boolean |
onCreatePanelMenu(featureId: Int, : Menu) Initialize the contents of the menu for panel 'featureId'. |
open View? |
onCreatePanelView(featureId: Int) Instantiate the view to display in the panel for 'featureId'. |
open Unit |
Called by the system to notify a Service that it is no longer used and is being removed. |
open Unit |
Called when the window has been detached from the window manager. |
open Unit |
Called when the dream's window has been created and is visible and animation may now begin. |
open Unit |
Called when this Dream is stopped, either by external request or by calling finish(), before the window has been removed. |
open Boolean |
onMenuItemSelected(featureId: Int, item: MenuItem) Called when a panel's menu item has been selected by the user. |
open Boolean |
onMenuOpened(featureId: Int, : Menu) Called when a panel's menu is opened by the user. |
open Unit |
onPanelClosed(featureId: Int, : Menu) Called when a panel is being closed. |
open Boolean |
onPreparePanel(featureId: Int, view: View?, : Menu) Prepare a panel to be displayed. |
open Boolean |
onSearchRequested(event: SearchEvent!) Called when the user signals the desire to start a search. |
open Boolean |
Called when the user signals the desire to start a search. |
open Boolean | |
open Unit |
onWakeUp() Called when the dream is being asked to stop itself and wake. |
open Unit |
This is called whenever the current window attributes change. |
open Unit |
onWindowFocusChanged(hasFocus: Boolean) This hook is called whenever the window focus changes. |
open ActionMode? |
onWindowStartingActionMode(callback: ActionMode.Callback!) Called when an action mode is being started for this window. |
open ActionMode? |
onWindowStartingActionMode(callback: ActionMode.Callback!, type: Int) Called when an action mode is being started for this window. |
T |
requireViewById(id: Int) Finds a view that was identified by the id attribute from the XML that was processed in |
open Unit |
setContentView(layoutResID: Int) Inflates a layout resource and set it to be the content view for this Dream. |
open Unit |
setContentView(view: View!) Sets a view to be the content view for this Dream. |
open Unit |
setContentView(view: View!, params: ViewGroup.LayoutParams!) Sets a view to be the content view for this Dream. |
open Unit |
setFullscreen(fullscreen: Boolean) Controls |
open Unit |
setInteractive(interactive: Boolean) Marks this dream as interactive to receive input events. |
open Unit |
setScreenBright(screenBright: Boolean) Marks this dream as keeping the screen bright while dreaming. |
Unit |
wakeUp() Wakes the dream up gently. |
Protected methods | |
---|---|
open Unit |
dump(fd: FileDescriptor!, pw: PrintWriter!, args: Array<String!>!) |
Inherited functions | |
---|---|
Constants
DREAM_META_DATA
static val DREAM_META_DATA: String
Name under which a Dream publishes information about itself. This meta-data must reference an XML resource containing a <
tag.dream
>
Value: "android.service.dream"
SERVICE_INTERFACE
static val SERVICE_INTERFACE: String
The Intent
that must be declared as handled by the service.
Value: "android.service.dreams.DreamService"
Public constructors
Public methods
addContentView
open fun addContentView(
view: View!,
params: ViewGroup.LayoutParams!
): Unit
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 |
View!: The desired content to display. |
params |
ViewGroup.LayoutParams!: Layout parameters for the view. |
dispatchGenericMotionEvent
open fun dispatchGenericMotionEvent(event: MotionEvent!): Boolean
Called to process generic motion events. At the very least your implementation must call android.view.Window#superDispatchGenericMotionEvent
to do the standard processing.
Parameters | |
---|---|
event |
MotionEvent!: The generic motion event. |
Return | |
---|---|
Boolean |
boolean Return true if this event was consumed. |
dispatchKeyEvent
open fun dispatchKeyEvent(event: KeyEvent!): Boolean
Called to process key events. At the very least your implementation must call android.view.Window#superDispatchKeyEvent
to do the standard key processing.
Parameters | |
---|---|
event |
KeyEvent!: The key event. |
Return | |
---|---|
Boolean |
boolean Return true if this event was consumed. |
dispatchKeyShortcutEvent
open fun dispatchKeyShortcutEvent(event: KeyEvent!): Boolean
Called to process a key shortcut event. At the very least your implementation must call android.view.Window#superDispatchKeyShortcutEvent
to do the standard key shortcut processing.
Parameters | |
---|---|
event |
KeyEvent!: The key shortcut event. |
Return | |
---|---|
Boolean |
True if this event was consumed. |
dispatchPopulateAccessibilityEvent
open fun dispatchPopulateAccessibilityEvent(event: AccessibilityEvent!): Boolean
Called to process population of AccessibilityEvent
s.
Parameters | |
---|---|
event |
AccessibilityEvent!: The event. |
Return | |
---|---|
Boolean |
boolean Return true if event population was completed. |
dispatchTouchEvent
open fun dispatchTouchEvent(event: MotionEvent!): Boolean
Called to process touch screen events. At the very least your implementation must call android.view.Window#superDispatchTouchEvent
to do the standard touch screen processing.
Parameters | |
---|---|
event |
MotionEvent!: The touch screen event. |
Return | |
---|---|
Boolean |
boolean Return true if this event was consumed. |
dispatchTrackballEvent
open fun dispatchTrackballEvent(event: MotionEvent!): Boolean
Called to process trackball events. At the very least your implementation must call android.view.Window#superDispatchTrackballEvent
to do the standard trackball processing.
Parameters | |
---|---|
event |
MotionEvent!: The trackball event. |
Return | |
---|---|
Boolean |
boolean Return true if this event was consumed. |
findViewById
open fun <T : View!> findViewById(id: Int): T
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()
Note: In most cases -- depending on compiler support -- the resulting view is automatically cast to the target class type. If the target class type is unconstrained, an explicit cast may be necessary.
Parameters | |
---|---|
id |
Int: the ID to search for |
Return | |
---|---|
T |
The view if found or null otherwise. |
finish
fun finish(): Unit
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.
getWindow
open fun getWindow(): Window!
Retrieves the current android.view.Window
for the dream. Behaves similarly to android.app.Activity#getWindow()
.
Return | |
---|---|
Window! |
The current window, or null if the dream is not started. |
getWindowManager
open fun getWindowManager(): WindowManager!
Retrieves the current android.view.WindowManager
for the dream. Behaves similarly to android.app.Activity#getWindowManager()
.
Return | |
---|---|
WindowManager! |
The current window manager, or null if the dream is not started. |
isFullscreen
open fun isFullscreen(): Boolean
Returns whether this dream is in fullscreen mode. Defaults to false.
See Also
isInteractive
open fun isInteractive(): Boolean
Returns whether this dream is interactive. Defaults to false.
See Also
isScreenBright
open fun isScreenBright(): Boolean
Returns whether this dream keeps the screen bright while dreaming. Defaults to true, preventing the screen from dimming.
See Also
onActionModeFinished
open fun onActionModeFinished(mode: ActionMode!): Unit
Called when an action mode has been finished. The appropriate mode callback method will have already been invoked.
Parameters | |
---|---|
mode |
ActionMode!: The mode that was just finished. |
onActionModeStarted
open fun onActionModeStarted(mode: ActionMode!): Unit
Called when an action mode has been started. The appropriate mode callback method will have already been invoked.
Parameters | |
---|---|
mode |
ActionMode!: The new mode that has just been started. |
onAttachedToWindow
open fun onAttachedToWindow(): Unit
Called when the window has been attached to the window manager. See View.onAttachedToWindow()
for more information.
onBind
fun onBind(intent: Intent!): IBinder?
Return the communication channel to the service. May return null if clients can not bind to the service. The returned android.os.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 |
Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here. |
Return | |
---|---|
IBinder? |
Return an IBinder through which clients can call on to the service. |
onContentChanged
open fun onContentChanged(): Unit
This hook is called whenever the content view of the screen changes (due to a call to Window.setContentView
or Window.addContentView
).
onCreatePanelMenu
open fun onCreatePanelMenu(
featureId: Int,
: Menu
): Boolean
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 |
Int: The panel being created. |
menu |
Menu: The menu inside the panel. This value cannot be null . |
Return | |
---|---|
Boolean |
boolean You must return true for the panel to be displayed; if you return false it will not be shown. |
onCreatePanelView
open fun onCreatePanelView(featureId: Int): View?
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 |
Int: Which panel is being created. |
Return | |
---|---|
View? |
view The top-level view to place in the panel. |
onDestroy
open fun onDestroy(): Unit
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.
onDetachedFromWindow
open fun onDetachedFromWindow(): Unit
Called when the window has been detached from the window manager. See View.onDetachedFromWindow()
for more information.
onDreamingStarted
open fun onDreamingStarted(): Unit
Called when the dream's window has been created and is visible and animation may now begin.
onDreamingStopped
open fun onDreamingStopped(): Unit
Called when this Dream is stopped, either by external request or by calling finish(), before the window has been removed.
onMenuItemSelected
open fun onMenuItemSelected(
featureId: Int,
item: MenuItem
): Boolean
Called when a panel's menu item has been selected by the user.
Parameters | |
---|---|
featureId |
Int: The panel that the menu is in. |
item |
MenuItem: The menu item that was selected. This value cannot be null . |
Return | |
---|---|
Boolean |
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). |
onMenuOpened
open fun onMenuOpened(
featureId: Int,
: Menu
): Boolean
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 |
Int: The panel that the menu is in. |
menu |
Menu: The menu that is opened. This value cannot be null . |
Return | |
---|---|
Boolean |
Return true to allow the menu to open, or false to prevent the menu from opening. |
onPanelClosed
open fun onPanelClosed(
featureId: Int,
: Menu
): Unit
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 |
Int: The panel that is being displayed. |
menu |
Menu: If onCreatePanelView() returned null, this is the Menu being displayed in the panel. |
onPreparePanel
open fun onPreparePanel(
featureId: Int,
view: View?,
: Menu
): Boolean
Prepare a panel to be displayed. This is called right before the panel window is shown, every time it is shown.
Parameters | |
---|---|
featureId |
Int: The panel that is being displayed. |
view |
View?: The View that was returned by onCreatePanelView(). This value may be null . |
menu |
Menu: If onCreatePanelView() returned null, this is the Menu being displayed in the panel. |
Return | |
---|---|
Boolean |
boolean You must return true for the panel to be displayed; if you return false it will not be shown. |
onSearchRequested
open fun onSearchRequested(event: SearchEvent!): Boolean
Called when the user signals the desire to start a search.
Parameters | |
---|---|
searchEvent |
A SearchEvent describing the signal to start a search. |
Return | |
---|---|
Boolean |
true if search launched, false if activity refuses (blocks) |
onSearchRequested
open fun onSearchRequested(): Boolean
Called when the user signals the desire to start a search.
Return | |
---|---|
Boolean |
true if search launched, false if activity refuses (blocks) |
onUnbind
open fun onUnbind(intent: Intent!): Boolean
Parameters | |
---|---|
intent |
Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here. |
Return | |
---|---|
Boolean |
Return true if you would like to have the service's onRebind method later called when new clients bind to it. |
onWakeUp
open fun onWakeUp(): Unit
Called when the dream is being asked to stop itself and wake.
The default implementation simply calls finish
which ends the dream immediately. Subclasses may override this function to perform a smooth exit transition then call finish
afterwards.
Note that the dream will only be given a short period of time (currently about five seconds) to wake up. If the dream does not finish itself in a timely manner then the system will forcibly finish it once the time allowance is up.
onWindowAttributesChanged
open fun onWindowAttributesChanged(attrs: WindowManager.LayoutParams!): Unit
This is called whenever the current window attributes change.
onWindowFocusChanged
open fun onWindowFocusChanged(hasFocus: Boolean): Unit
This hook is called whenever the window focus changes. See View.onWindowFocusChangedNotLocked(boolean)
for more information.
Parameters | |
---|---|
hasFocus |
Boolean: Whether the window now has focus. |
onWindowStartingActionMode
open fun onWindowStartingActionMode(callback: ActionMode.Callback!): ActionMode?
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. This is equivalent to onWindowStartingActionMode(android.view.ActionMode.Callback,int)
with type ActionMode#TYPE_PRIMARY
.
Parameters | |
---|---|
callback |
ActionMode.Callback!: Callback to control the lifecycle of this action mode |
Return | |
---|---|
ActionMode? |
The ActionMode that was started, or null if the system should present it |
onWindowStartingActionMode
open fun onWindowStartingActionMode(
callback: ActionMode.Callback!,
type: Int
): ActionMode?
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 |
ActionMode.Callback!: Callback to control the lifecycle of this action mode |
type |
Int: One of ActionMode#TYPE_PRIMARY or ActionMode#TYPE_FLOATING . |
Return | |
---|---|
ActionMode? |
The ActionMode that was started, or null if the system should present it |
requireViewById
fun <T : View!> requireViewById(id: Int): T
Finds a view that was identified by the id attribute from the XML that was processed in onCreate
, or throws an IllegalArgumentException if the ID is invalid or there is no matching view in the hierarchy.
Note: Requires a window, do not call before onAttachedToWindow()
Note: In most cases -- depending on compiler support -- the resulting view is automatically cast to the target class type. If the target class type is unconstrained, an explicit cast may be necessary.
Parameters | |
---|---|
id |
Int: the ID to search for |
Return | |
---|---|
T |
a view with given ID This value cannot be null . |
setContentView
open fun setContentView(layoutResID: Int): Unit
Inflates a layout resource and set it to be the content view for this Dream. Behaves similarly to android.app.Activity#setContentView(int)
.
Note: Requires a window, do not call before onAttachedToWindow()
Parameters | |
---|---|
layoutResID |
Int: Resource ID to be inflated. |
setContentView
open fun setContentView(view: View!): Unit
Sets a view to be the content view for this Dream. Behaves similarly to android.app.Activity#setContentView(android.view.View)
in an activity, including using ViewGroup.LayoutParams#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
).
setContentView
open fun setContentView(
view: View!,
params: ViewGroup.LayoutParams!
): Unit
Sets a view to be the content view for this Dream. Behaves similarly to android.app.Activity#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 |
View!: The desired content to display. |
params |
ViewGroup.LayoutParams!: Layout parameters for the view. |
setFullscreen
open fun setFullscreen(fullscreen: Boolean): Unit
Controls android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN
on the dream's window.
Parameters | |
---|---|
fullscreen |
Boolean: If true, the fullscreen flag will be set; else it will be cleared. |
setInteractive
open fun setInteractive(interactive: Boolean): Unit
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 |
Boolean: True if this dream will handle input events. |
setScreenBright
open fun setScreenBright(screenBright: Boolean): Unit
Marks this dream as keeping the screen bright while dreaming. In preview mode, the screen is always allowed to dim and overrides the value specified here.
Parameters | |
---|---|
screenBright |
Boolean: True to keep the screen bright while dreaming. |
wakeUp
fun wakeUp(): Unit
Wakes the dream up gently.
Calls onWakeUp
to give the dream a chance to perform an exit transition. When the transition is over, the dream should call finish
.
Protected methods
dump
protected open fun dump(
fd: FileDescriptor!,
pw: PrintWriter!,
args: Array<String!>!
): Unit
Parameters | |
---|---|
fd |
FileDescriptor!: The raw file descriptor that the dump is being sent to. |
writer |
The PrintWriter to which you should dump your state. This will be closed for you after you return. |
args |
Array<String!>!: additional arguments to the dump request. |