public class DreamService extends Service implements Window.Callback
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 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(int)
, 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>
Service.StartArgFlags, Service.StartResult, Service.StopForegroundFlags
Context.BindServiceFlags, Context.CreatePackageOptions, Context.ServiceName
Modifier and Type | Field and Description |
---|---|
static String |
DREAM_META_DATA
Name under which a Dream publishes information about itself.
|
static String |
DREAM_SERVICE
The name of the dream manager service.
|
static String |
SERVICE_INTERFACE
The
Intent that must be declared as handled by the service. |
START_CONTINUATION_MASK, START_FLAG_REDELIVERY, START_FLAG_RETRY, START_NOT_STICKY, START_REDELIVER_INTENT, START_STICKY, START_STICKY_COMPATIBILITY, START_TASK_REMOVED_COMPLETE, STOP_FOREGROUND_DETACH, STOP_FOREGROUND_REMOVE
ACCESSIBILITY_SERVICE, ACCOUNT_SERVICE, ACTIVITY_SERVICE, ALARM_SERVICE, APP_OPS_SERVICE, APPWIDGET_SERVICE, AUDIO_SERVICE, BACKUP_SERVICE, BATTERY_SERVICE, BIND_ABOVE_CLIENT, BIND_ADJUST_WITH_ACTIVITY, BIND_ALLOW_OOM_MANAGEMENT, BIND_ALLOW_WHITELIST_MANAGEMENT, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, BIND_EXTERNAL_SERVICE, BIND_FOREGROUND_SERVICE, BIND_FOREGROUND_SERVICE_WHILE_AWAKE, BIND_IMPORTANT, BIND_NOT_FOREGROUND, BIND_NOT_VISIBLE, BIND_SHOWING_UI, BIND_TREAT_LIKE_ACTIVITY, BIND_VISIBLE, BIND_WAIVE_PRIORITY, BLUETOOTH_SERVICE, CAMERA_SERVICE, CAPTIONING_SERVICE, CARRIER_CONFIG_SERVICE, CLIPBOARD_SERVICE, CONNECTIVITY_SERVICE, CONSUMER_IR_SERVICE, CONTEXT_CREDENTIAL_PROTECTED_STORAGE, CONTEXT_DEVICE_PROTECTED_STORAGE, CONTEXT_IGNORE_SECURITY, CONTEXT_INCLUDE_CODE, CONTEXT_REGISTER_PACKAGE, CONTEXT_RESTRICTED, CONTEXTHUB_SERVICE, COUNTRY_DETECTOR, DEVICE_IDLE_CONTROLLER, DEVICE_POLICY_SERVICE, DISPLAY_SERVICE, DOWNLOAD_SERVICE, DROPBOX_SERVICE, ETHERNET_SERVICE, FINGERPRINT_SERVICE, GATEKEEPER_SERVICE, HARDWARE_PROPERTIES_SERVICE, HDMI_CONTROL_SERVICE, INPUT_METHOD_SERVICE, INPUT_SERVICE, JOB_SCHEDULER_SERVICE, KEYGUARD_SERVICE, LAUNCHER_APPS_SERVICE, LAYOUT_INFLATER_SERVICE, LOCATION_SERVICE, MEDIA_PROJECTION_SERVICE, MEDIA_ROUTER_SERVICE, MEDIA_SESSION_SERVICE, MIDI_SERVICE, MODE_APPEND, MODE_ENABLE_WRITE_AHEAD_LOGGING, MODE_MULTI_PROCESS, MODE_NO_LOCALIZED_COLLATORS, MODE_PRIVATE, MODE_WORLD_READABLE, MODE_WORLD_WRITEABLE, NETWORK_POLICY_SERVICE, NETWORK_SCORE_SERVICE, NETWORK_STATS_SERVICE, NETWORKMANAGEMENT_SERVICE, NFC_SERVICE, NOTIFICATION_SERVICE, NSD_SERVICE, PERSISTENT_DATA_BLOCK_SERVICE, POWER_SERVICE, PRINT_SERVICE, RADIO_SERVICE, RECOVERY_SERVICE, RESTRICTIONS_SERVICE, SEARCH_SERVICE, SENSOR_SERVICE, SERIAL_SERVICE, SHORTCUT_SERVICE, SIP_SERVICE, SOUND_TRIGGER_SERVICE, STATUS_BAR_SERVICE, STORAGE_SERVICE, SYSTEM_HEALTH_SERVICE, TELECOM_SERVICE, TELEPHONY_SERVICE, TELEPHONY_SUBSCRIPTION_SERVICE, TEXT_SERVICES_MANAGER_SERVICE, TRUST_SERVICE, TV_INPUT_SERVICE, UI_MODE_SERVICE, UPDATE_LOCK_SERVICE, USAGE_STATS_SERVICE, USB_SERVICE, USER_SERVICE, VIBRATOR_SERVICE, VOICE_INTERACTION_MANAGER_SERVICE, WALLPAPER_SERVICE, WIFI_NAN_SERVICE, WIFI_P2P_SERVICE, WIFI_RTT_SERVICE, WIFI_SCANNING_SERVICE, WIFI_SERVICE, WINDOW_SERVICE
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 and Description |
---|
DreamService() |
Modifier and Type | Method and Description |
---|---|
void |
addContentView(View view,
ViewGroup.LayoutParams params)
Adds a view to the Dream's window, leaving other content views in place.
|
boolean |
canDoze()
Returns true if this dream is allowed to doze.
|
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
AccessibilityEvent s. |
boolean |
dispatchTouchEvent(MotionEvent event)
Called to process touch screen events.
|
boolean |
dispatchTrackballEvent(MotionEvent event)
Called to process trackball events.
|
protected void |
dump(FileDescriptor fd,
PrintWriter pw,
String[] args)
Print the Service's state into the given stream.
|
protected void |
dumpOnHandler(FileDescriptor fd,
PrintWriter pw,
String[] args) |
View |
findViewById(int id)
Finds a view that was identified by the id attribute from the XML that
was processed in
onCreate() . |
void |
finish()
Stops the dream and detaches from the window.
|
int |
getDozeScreenBrightness()
Gets the screen brightness to use while dozing.
|
int |
getDozeScreenState()
Gets the screen state to use while dozing.
|
Window |
getWindow()
Retrieves the current
Window for the dream. |
WindowManager |
getWindowManager()
Retrieves the current
WindowManager for the dream. |
boolean |
isDozing()
Returns true if the dream will allow the system to enter a low-power state while
it is running without actually turning off the screen.
|
boolean |
isFullscreen()
Returns whether or not this dream is in fullscreen mode.
|
boolean |
isInteractive()
Returns whether or not this dream is interactive.
|
boolean |
isLowProfile()
Returns whether or not this dream is in low profile mode.
|
boolean |
isScreenBright()
Returns whether or not this dream keeps the screen bright while dreaming.
|
boolean |
isWindowless()
Returns whether or not this dream is windowless.
|
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.
|
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.
|
boolean |
onSearchRequested(SearchEvent event)
Called when the user signals the desire to start a search.
|
void |
onWakeUp()
Called when the dream is being asked to stop itself and wake.
|
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.
|
ActionMode |
onWindowStartingActionMode(ActionMode.Callback callback,
int type)
Called when an action mode is being started for this window.
|
void |
setContentView(int layoutResID)
Inflates a layout resource and set it to be the content view for this Dream.
|
void |
setContentView(View view)
Sets a view 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 |
setDebug(boolean dbg) |
void |
setDozeScreenBrightness(int brightness)
Sets the screen brightness to use while dozing.
|
void |
setDozeScreenState(int state)
Sets the screen state to use while dozing.
|
void |
setFullscreen(boolean fullscreen)
Controls
WindowManager.LayoutParams.FLAG_FULLSCREEN
on the dream's window. |
void |
setInteractive(boolean interactive)
Marks this dream as interactive to receive input events.
|
void |
setLowProfile(boolean lowProfile)
Sets View.SYSTEM_UI_FLAG_LOW_PROFILE on the content view.
|
void |
setScreenBright(boolean screenBright)
Marks this dream as keeping the screen bright while dreaming.
|
void |
setWindowless(boolean windowless)
Marks this dream as windowless.
|
void |
startDozing()
Starts dozing, entering a deep dreamy sleep.
|
void |
stopDozing()
Stops dozing, returns to active dreaming.
|
void |
wakeUp()
Wakes the dream up gently.
|
attach, getApplication, onConfigurationChanged, onLowMemory, onRebind, onStart, onStartCommand, onTaskRemoved, onTrimMemory, onUnbind, setForeground, startForeground, stopForeground, stopForeground, stopSelf, stopSelf, stopSelfResult
attachBaseContext, bindService, bindServiceAsUser, canStartActivityForResult, checkCallingOrSelfPermission, checkCallingOrSelfUriPermission, checkCallingPermission, checkCallingUriPermission, checkPermission, checkPermission, checkSelfPermission, checkUriPermission, checkUriPermission, checkUriPermission, clearWallpaper, createApplicationContext, createConfigurationContext, createCredentialProtectedStorageContext, createDeviceProtectedStorageContext, createDisplayContext, createPackageContext, createPackageContextAsUser, databaseList, deleteDatabase, deleteFile, deleteSharedPreferences, enforceCallingOrSelfPermission, enforceCallingOrSelfUriPermission, enforceCallingPermission, enforceCallingUriPermission, enforcePermission, enforceUriPermission, enforceUriPermission, fileList, getApplicationContext, getApplicationInfo, getAssets, getBaseContext, getBasePackageName, getCacheDir, getClassLoader, getCodeCacheDir, getContentResolver, getDatabasePath, getDataDir, getDir, getDisplay, getDisplayAdjustments, getExternalCacheDir, getExternalCacheDirs, getExternalFilesDir, getExternalFilesDirs, getExternalMediaDirs, getFilesDir, getFileStreamPath, getMainLooper, getNoBackupFilesDir, getObbDir, getObbDirs, getOpPackageName, getPackageCodePath, getPackageManager, getPackageName, getPackageResourcePath, getResources, getSharedPreferences, getSharedPreferences, getSharedPreferencesPath, getSystemService, getSystemServiceName, getTheme, getThemeResId, getUserId, getWallpaper, getWallpaperDesiredMinimumHeight, getWallpaperDesiredMinimumWidth, grantUriPermission, isCredentialProtectedStorage, isDeviceProtectedStorage, isRestricted, moveDatabaseFrom, moveSharedPreferencesFrom, openFileInput, openFileOutput, openOrCreateDatabase, openOrCreateDatabase, peekWallpaper, registerReceiver, registerReceiver, registerReceiverAsUser, removeStickyBroadcast, removeStickyBroadcastAsUser, revokeUriPermission, sendBroadcast, sendBroadcast, sendBroadcast, sendBroadcast, sendBroadcastAsUser, sendBroadcastAsUser, sendBroadcastAsUser, sendBroadcastMultiplePermissions, sendOrderedBroadcast, sendOrderedBroadcast, sendOrderedBroadcast, sendOrderedBroadcast, sendOrderedBroadcastAsUser, sendOrderedBroadcastAsUser, sendOrderedBroadcastAsUser, sendStickyBroadcast, sendStickyBroadcastAsUser, sendStickyBroadcastAsUser, sendStickyOrderedBroadcast, sendStickyOrderedBroadcastAsUser, setTheme, setWallpaper, setWallpaper, startActivities, startActivities, startActivitiesAsUser, startActivity, startActivity, startActivityAsUser, startActivityAsUser, startActivityForResult, startInstrumentation, startIntentSender, startIntentSender, startService, startServiceAsUser, stopService, stopServiceAsUser, unbindService, unregisterReceiver
bindServiceAsUser, createCredentialEncryptedStorageContext, createDeviceEncryptedStorageContext, getColor, getColorStateList, getDrawable, getSharedPrefsFile, getString, getString, getSystemService, getText, isCredentialEncryptedStorage, isDeviceEncryptedStorage, migrateDatabaseFrom, migrateSharedPreferencesFrom, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, registerComponentCallbacks, unregisterComponentCallbacks
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
onProvideKeyboardShortcuts
public static final String DREAM_SERVICE
public static final String SERVICE_INTERFACE
Intent
that must be declared as handled by the service.public static final String DREAM_META_DATA
<dream
>
tag.public void setDebug(boolean dbg)
public boolean dispatchKeyEvent(KeyEvent event)
Window.superDispatchKeyEvent(android.view.KeyEvent)
to do the
standard key processing.dispatchKeyEvent
in interface Window.Callback
event
- The key event.public boolean dispatchKeyShortcutEvent(KeyEvent event)
Window.superDispatchKeyShortcutEvent(android.view.KeyEvent)
to do the
standard key shortcut processing.dispatchKeyShortcutEvent
in interface Window.Callback
event
- The key shortcut event.public boolean dispatchTouchEvent(MotionEvent event)
Window.superDispatchTouchEvent(android.view.MotionEvent)
to do the
standard touch screen processing.dispatchTouchEvent
in interface Window.Callback
event
- The touch screen event.public boolean dispatchTrackballEvent(MotionEvent event)
Window.superDispatchTrackballEvent(android.view.MotionEvent)
to do the
standard trackball processing.dispatchTrackballEvent
in interface Window.Callback
event
- The trackball event.public boolean dispatchGenericMotionEvent(MotionEvent event)
Window.superDispatchGenericMotionEvent(android.view.MotionEvent)
to do the
standard processing.dispatchGenericMotionEvent
in interface Window.Callback
event
- The generic motion event.public boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event)
AccessibilityEvent
s.dispatchPopulateAccessibilityEvent
in interface Window.Callback
event
- The event.public View onCreatePanelView(int featureId)
onCreatePanelView
in interface Window.Callback
featureId
- Which panel is being created.Window.Callback.onPreparePanel(int, android.view.View, android.view.Menu)
public boolean onCreatePanelMenu(int featureId, Menu menu)
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.
onCreatePanelMenu
in interface Window.Callback
featureId
- The panel being created.menu
- The menu inside the panel.public boolean onPreparePanel(int featureId, View view, Menu menu)
onPreparePanel
in interface Window.Callback
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.Window.Callback.onCreatePanelView(int)
public boolean onMenuOpened(int featureId, Menu menu)
onMenuOpened
in interface Window.Callback
featureId
- The panel that the menu is in.menu
- The menu that is opened.public boolean onMenuItemSelected(int featureId, MenuItem item)
onMenuItemSelected
in interface Window.Callback
featureId
- The panel that the menu is in.item
- The menu item that was selected.public void onWindowAttributesChanged(WindowManager.LayoutParams attrs)
onWindowAttributesChanged
in interface Window.Callback
public void onContentChanged()
Window.setContentView
or
Window.addContentView
).onContentChanged
in interface Window.Callback
public void onWindowFocusChanged(boolean hasFocus)
View.onWindowFocusChangedNotLocked(boolean)
for more information.onWindowFocusChanged
in interface Window.Callback
hasFocus
- Whether the window now has focus.public void onAttachedToWindow()
View.onAttachedToWindow()
for more information.onAttachedToWindow
in interface Window.Callback
public void onDetachedFromWindow()
View.onDetachedFromWindow()
for more information.onDetachedFromWindow
in interface Window.Callback
public void onPanelClosed(int featureId, Menu menu)
onPanelClosed
in interface Window.Callback
featureId
- The panel that is being displayed.menu
- If onCreatePanelView() returned null, this is the Menu
being displayed in the panel.public boolean onSearchRequested(SearchEvent event)
onSearchRequested
in interface Window.Callback
event
- A SearchEvent
describing the signal to
start a search.public boolean onSearchRequested()
onSearchRequested
in interface Window.Callback
Activity.onSearchRequested()
public ActionMode onWindowStartingActionMode(ActionMode.Callback callback)
Window.Callback.onWindowStartingActionMode(android.view.ActionMode.Callback, int)
with type ActionMode.TYPE_PRIMARY
.onWindowStartingActionMode
in interface Window.Callback
callback
- Callback to control the lifecycle of this action modepublic ActionMode onWindowStartingActionMode(ActionMode.Callback callback, int type)
onWindowStartingActionMode
in interface Window.Callback
callback
- Callback to control the lifecycle of this action modetype
- One of ActionMode.TYPE_PRIMARY
or ActionMode.TYPE_FLOATING
.public void onActionModeStarted(ActionMode mode)
onActionModeStarted
in interface Window.Callback
mode
- The new mode that has just been started.public void onActionModeFinished(ActionMode mode)
onActionModeFinished
in interface Window.Callback
mode
- The mode that was just finished.public WindowManager getWindowManager()
WindowManager
for the dream.
Behaves similarly to Activity.getWindowManager()
.public Window getWindow()
Window
for the dream.
Behaves similarly to Activity.getWindow()
.public void setContentView(@LayoutRes int layoutResID)
Activity.setContentView(int)
.
Note: Requires a window, do not call before onAttachedToWindow()
layoutResID
- Resource ID to be inflated.setContentView(android.view.View)
,
setContentView(android.view.View, android.view.ViewGroup.LayoutParams)
public void setContentView(View view)
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()
).
public void setContentView(View view, ViewGroup.LayoutParams params)
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()
).
view
- The desired content to display.params
- Layout parameters for the view.setContentView(android.view.View)
,
setContentView(int)
public void addContentView(View view, ViewGroup.LayoutParams params)
Note: Requires a window, do not call before onAttachedToWindow()
view
- The desired content to display.params
- Layout parameters for the view.public View findViewById(@IdRes int id)
onCreate()
.
Note: Requires a window, do not call before onAttachedToWindow()
public void setInteractive(boolean interactive)
Non-interactive dreams (default) will dismiss on the first input event.
Interactive dreams should call finish()
to dismiss themselves.
interactive
- True if this dream will handle input events.public boolean isInteractive()
setInteractive(boolean)
public void setLowProfile(boolean lowProfile)
lowProfile
- True to set View.SYSTEM_UI_FLAG_LOW_PROFILEpublic boolean isLowProfile()
setLowProfile(boolean)
public void setFullscreen(boolean fullscreen)
WindowManager.LayoutParams.FLAG_FULLSCREEN
on the dream's window.fullscreen
- If true, the fullscreen flag will be set; else it
will be cleared.public boolean isFullscreen()
setFullscreen(boolean)
public void setScreenBright(boolean screenBright)
screenBright
- True to keep the screen bright while dreaming.public boolean isScreenBright()
setScreenBright(boolean)
public void setWindowless(boolean windowless)
public boolean isWindowless()
public boolean canDoze()
The value returned by this method is only meaningful when the dream has started.
startDozing()
public void startDozing()
Dozing enables the system to conserve power while the user is not actively interacting with the device. While dozing, the display will remain on in a low-power state and will continue to show its previous contents but the application processor and other system components will be allowed to suspend when possible.
While the application processor is suspended, the dream may stop executing code
for long periods of time. Prior to being suspended, the dream may schedule periodic
wake-ups to render new content by scheduling an alarm with the AlarmManager
.
The dream may also keep the CPU awake by acquiring a
partial wake lock
when necessary.
Note that since the purpose of doze mode is to conserve power (especially when
running on battery), the dream should not wake the CPU very often or keep it
awake for very long.
It is a good idea to call this method some time after the dream's entry animation has completed and the dream is ready to doze. It is important to completely finish all of the work needed before dozing since the application processor may be suspended at any moment once this method is called unless other wake locks are being held.
Call stopDozing()
or finish()
to stop dozing.
stopDozing()
public void stopDozing()
This method reverses the effect of startDozing()
. From this moment onward,
the application processor will be kept awake as long as the dream is running
or until the dream starts dozing again.
startDozing()
public boolean isDozing()
#setDozing(boolean)
public int getDozeScreenState()
Display.STATE_ON
,
Display.STATE_DOZE
, Display.STATE_DOZE_SUSPEND
,
or Display.STATE_OFF
, or Display.STATE_UNKNOWN
for the default
behavior.setDozeScreenState(int)
public void setDozeScreenState(int state)
The value of this property determines the power state of the primary display
once startDozing()
has been called. The default value is
Display.STATE_UNKNOWN
which lets the system decide.
The dream may set a different state before starting to doze and may
perform transitions between states while dozing to conserve power and
achieve various effects.
It is recommended that the state be set to Display.STATE_DOZE_SUSPEND
once the dream has completely finished drawing and before it releases its wakelock
to allow the display hardware to be fully suspended. While suspended, the
display will preserve its on-screen contents or hand off control to dedicated
doze hardware if the devices supports it. If the doze suspend state is
used, the dream must make sure to set the mode back
to Display.STATE_DOZE
or Display.STATE_ON
before drawing again
since the display updates may be ignored and not seen by the user otherwise.
The set of available display power states and their behavior while dozing is hardware dependent and may vary across devices. The dream may therefore need to be modified or configured to correctly support the hardware.
state
- The screen state to use while dozing, such as Display.STATE_ON
,
Display.STATE_DOZE
, Display.STATE_DOZE_SUSPEND
,
or Display.STATE_OFF
, or Display.STATE_UNKNOWN
for the default
behavior.public int getDozeScreenBrightness()
PowerManager.BRIGHTNESS_OFF
(0) and PowerManager.BRIGHTNESS_ON
(255),
or PowerManager.BRIGHTNESS_DEFAULT
(-1) to ask the system to apply
its default policy based on the screen state.setDozeScreenBrightness(int)
public void setDozeScreenBrightness(int brightness)
The value of this property determines the power state of the primary display
once startDozing()
has been called. The default value is
PowerManager.BRIGHTNESS_DEFAULT
which lets the system decide.
The dream may set a different brightness before starting to doze and may adjust
the brightness while dozing to conserve power and achieve various effects.
Note that dream may specify any brightness in the full 0-255 range, including values that are less than the minimum value for manual screen brightness adjustments by the user. In particular, the value may be set to 0 which may turn off the backlight entirely while still leaving the screen on although this behavior is device dependent and not guaranteed.
The available range of display brightness values and their behavior while dozing is hardware dependent and may vary across devices. The dream may therefore need to be modified or configured to correctly support the hardware.
brightness
- The screen brightness while dozing as a value between
PowerManager.BRIGHTNESS_OFF
(0) and PowerManager.BRIGHTNESS_ON
(255),
or PowerManager.BRIGHTNESS_DEFAULT
(-1) to ask the system to apply
its default policy based on the screen state.public void onCreate()
public void onDreamingStarted()
public void onDreamingStopped()
public void onWakeUp()
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.
public final IBinder onBind(Intent intent)
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.
onBind
in class Service
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.public final void finish()
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 final void wakeUp()
Calls onWakeUp()
to give the dream a chance to perform an exit transition.
When the transition is over, the dream should call finish()
.
public void onDestroy()
protected void dump(FileDescriptor fd, PrintWriter pw, String[] args)
Service
IBinder.dump(java.io.FileDescriptor, java.lang.String[])
method
on the IBinder
interface registered with ServiceManager.protected void dumpOnHandler(FileDescriptor fd, PrintWriter pw, String[] args)