/**@class android.service.dreams.DreamService implements android.view.Window.Callback @extends android.app.Service Extend this class to implement a custom dream (available to the user as a "Daydream"). <p>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.</p> <p>The {@code DreamService} lifecycle is as follows:</p> <ol> <li>{@link #onAttachedToWindow} <p>Use this for initial setup, such as calling {@link #setContentView setContentView()}.</li> <li>{@link #onDreamingStarted} <p>Your dream has started, so you should begin animations or other behaviors here.</li> <li>{@link #onDreamingStopped} <p>Use this to stop the things you started in {@link #onDreamingStarted}.</li> <li>{@link #onDetachedFromWindow} <p>Use this to dismantle resources (for example, detach from handlers and listeners).</li> </ol> <p>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.</p> <p>To be available to the system, your {@code DreamService} should be declared in the manifest as follows:</p> <pre> <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> </pre> <p>If specified with the {@code <meta-data>} element, additional information for the dream is defined using the {@link android.R.styleable#Dream <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:</p> <p class="code-caption">res/xml/my_dream.xml</p> <pre> <dream xmlns:android="http://schemas.android.com/apk/res/android" android:settingsActivity="com.example.app/.MyDreamSettingsActivity" /> </pre> <p>This makes a Settings button available alongside your dream's listing in the system settings, which when pressed opens the specified activity.</p> <p>To specify your dream layout, call {@link #setContentView}, typically during the {@link #onAttachedToWindow} callback. For example:</p> <pre> 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); } } </pre> <p>When targeting api level 21 and above, you must declare the service in your manifest file with the {@link android.Manifest.permission#BIND_DREAM_SERVICE} permission. For example:</p> <pre> <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> </pre> */ var DreamService = { /** The name of the dream manager service. @hide */ DREAM_SERVICE : "dreams", /** The {@link Intent} that must be declared as handled by the service. */ SERVICE_INTERFACE : "android.service.dreams.DreamService", /** Name under which a Dream publishes information about itself. This meta-data must reference an XML resource containing a <code><{@link android.R.styleable#Dream dream}></code> tag. */ DREAM_META_DATA : "android.service.dream", /** @hide */ setDebug : function( ) {}, /**{@inheritDoc} */ dispatchKeyEvent : function( ) {}, /**{@inheritDoc} */ dispatchKeyShortcutEvent : function( ) {}, /**{@inheritDoc} */ dispatchTouchEvent : function( ) {}, /**{@inheritDoc} */ dispatchTrackballEvent : function( ) {}, /**{@inheritDoc} */ dispatchGenericMotionEvent : function( ) {}, /**{@inheritDoc} */ dispatchPopulateAccessibilityEvent : function( ) {}, /**{@inheritDoc} */ onCreatePanelView : function( ) {}, /**{@inheritDoc} */ onCreatePanelMenu : function( ) {}, /**{@inheritDoc} */ onPreparePanel : function( ) {}, /**{@inheritDoc} */ onMenuOpened : function( ) {}, /**{@inheritDoc} */ onMenuItemSelected : function( ) {}, /**{@inheritDoc} */ onWindowAttributesChanged : function( ) {}, /**{@inheritDoc} */ onContentChanged : function( ) {}, /**{@inheritDoc} */ onWindowFocusChanged : function( ) {}, /**{@inheritDoc} */ onAttachedToWindow : function( ) {}, /**{@inheritDoc} */ onDetachedFromWindow : function( ) {}, /**{@inheritDoc} */ onPanelClosed : function( ) {}, /**{@inheritDoc} */ onSearchRequested : function( ) {}, /**{@inheritDoc} */ onSearchRequested : function( ) {}, /**{@inheritDoc} */ onWindowStartingActionMode : function( ) {}, /**{@inheritDoc} */ onWindowStartingActionMode : function( ) {}, /**{@inheritDoc} */ onActionModeStarted : function( ) {}, /**{@inheritDoc} */ onActionModeFinished : function( ) {}, /**Retrieves the current {@link android.view.WindowManager} for the dream. Behaves similarly to {@link android.app.Activity#getWindowManager()}. @return {Object {android.view.WindowManager}} The current window manager, or null if the dream is not started. */ getWindowManager : function( ) {}, /**Retrieves the current {@link android.view.Window} for the dream. Behaves similarly to {@link android.app.Activity#getWindow()}. @return {Object {android.view.Window}} The current window, or null if the dream is not started. */ getWindow : function( ) {}, /**Inflates a layout resource and set it to be the content view for this Dream. Behaves similarly to {@link android.app.Activity#setContentView(int)}. <p>Note: Requires a window, do not call before {@link #onAttachedToWindow}()</p> @param {Number} layoutResID Resource ID to be inflated. @see #setContentView(android.view.View) @see #setContentView(android.view.View, android.view.ViewGroup.LayoutParams) */ setContentView : function( ) {}, /**Sets a view to be the content view for this Dream. Behaves similarly to {@link android.app.Activity#setContentView(android.view.View)} in an activity, including using {@link ViewGroup.LayoutParams#MATCH_PARENT} as the layout height and width of the view. <p>Note: This requires a window, so you should usually call it during {@link #onAttachedToWindow}() and never earlier (you <strong>cannot</strong> call it during {@link #onCreate}).</p> @see #setContentView(int) @see #setContentView(android.view.View, android.view.ViewGroup.LayoutParams) */ setContentView : function( ) {}, /**Sets a view to be the content view for this Dream. Behaves similarly to {@link android.app.Activity#setContentView(android.view.View, android.view.ViewGroup.LayoutParams)} in an activity. <p>Note: This requires a window, so you should usually call it during {@link #onAttachedToWindow}() and never earlier (you <strong>cannot</strong> call it during {@link #onCreate}).</p> @param {Object {View}} view The desired content to display. @param {Object {ViewGroup.LayoutParams}} params Layout parameters for the view. @see #setContentView(android.view.View) @see #setContentView(int) */ setContentView : function( ) {}, /**Adds a view to the Dream's window, leaving other content views in place. <p>Note: Requires a window, do not call before {@link #onAttachedToWindow}()</p> @param {Object {View}} view The desired content to display. @param {Object {ViewGroup.LayoutParams}} params Layout parameters for the view. */ addContentView : function( ) {}, /**Finds a view that was identified by the id attribute from the XML that was processed in {@link #onCreate}. <p>Note: Requires a window, do not call before {@link #onAttachedToWindow}()</p> <p> <strong>Note:</strong> 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. @param {Number} id the ID to search for @return {Object {android.view.View}} The view if found or null otherwise. @see View#findViewById(int) @see DreamService#requireViewById(int) */ findViewById : function( ) {}, /**Finds a view that was identified by the id attribute from the XML that was processed in {@link #onCreate}, or throws an IllegalArgumentException if the ID is invalid or there is no matching view in the hierarchy. <p>Note: Requires a window, do not call before {@link #onAttachedToWindow}()</p> <p> <strong>Note:</strong> 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. @param {Number} id the ID to search for @return {Object {android.view.View}} a view with given ID @see View#requireViewById(int) @see DreamService#findViewById(int) */ requireViewById : function( ) {}, /**Marks this dream as interactive to receive input events. <p>Non-interactive dreams (default) will dismiss on the first input event.</p> <p>Interactive dreams should call {@link #finish}() to dismiss themselves.</p> @param {Boolean} interactive True if this dream will handle input events. */ setInteractive : function( ) {}, /**Returns whether or not this dream is interactive. Defaults to false. @see #setInteractive(boolean) */ isInteractive : function( ) {}, /**Sets View.SYSTEM_UI_FLAG_LOW_PROFILE on the content view. @param {Boolean} lowProfile True to set View.SYSTEM_UI_FLAG_LOW_PROFILE @hide There is no reason to have this -- dreams can set this flag on their own content view, and from there can actually do the correct interactions with it (seeing when it is cleared etc). */ setLowProfile : function( ) {}, /**Returns whether or not this dream is in low profile mode. Defaults to true. @see #setLowProfile(boolean) @hide */ isLowProfile : function( ) {}, /**Controls {@link android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN} on the dream's window. @param {Boolean} fullscreen If true, the fullscreen flag will be set; else it will be cleared. */ setFullscreen : function( ) {}, /**Returns whether or not this dream is in fullscreen mode. Defaults to false. @see #setFullscreen(boolean) */ isFullscreen : function( ) {}, /**Marks this dream as keeping the screen bright while dreaming. @param {Boolean} screenBright True to keep the screen bright while dreaming. */ setScreenBright : function( ) {}, /**Returns whether or not this dream keeps the screen bright while dreaming. Defaults to false, allowing the screen to dim if necessary. @see #setScreenBright(boolean) */ isScreenBright : function( ) {}, /**Marks this dream as windowless. Only available to doze dreams. @hide */ setWindowless : function( ) {}, /**Returns whether or not this dream is windowless. Only available to doze dreams. @hide */ isWindowless : function( ) {}, /**Returns true if this dream is allowed to doze. <p> The value returned by this method is only meaningful when the dream has started. </p> @return {Boolean} True if this dream can doze. @see #startDozing @hide For use by system UI components only. */ canDoze : function( ) {}, /**Starts dozing, entering a deep dreamy sleep. <p> 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. </p><p> 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 {@link AlarmManager}. The dream may also keep the CPU awake by acquiring a {@link android.os.PowerManager#PARTIAL_WAKE_LOCK 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. </p><p> 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. </p><p> Call {@link #stopDozing} or {@link #finish} to stop dozing. </p> @see #stopDozing @hide For use by system UI components only. */ startDozing : function( ) {}, /**Stops dozing, returns to active dreaming. <p> This method reverses the effect of {@link #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. </p> @see #startDozing @hide For use by system UI components only. */ stopDozing : function( ) {}, /**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. Defaults to false, keeping the application processor awake while the dream is running. @return {Boolean} True if the dream is dozing. @see #setDozing(boolean) @hide For use by system UI components only. */ isDozing : function( ) {}, /**Gets the screen state to use while dozing. @return {Number} The screen state to use while dozing, such as {@link Display#STATE_ON}, {@link Display#STATE_DOZE}, {@link Display#STATE_DOZE_SUSPEND}, {@link Display#STATE_ON_SUSPEND}, {@link Display#STATE_OFF}, or {@link Display#STATE_UNKNOWN} for the default behavior. @see #setDozeScreenState @hide For use by system UI components only. */ getDozeScreenState : function( ) {}, /**Sets the screen state to use while dozing. <p> The value of this property determines the power state of the primary display once {@link #startDozing} has been called. The default value is {@link 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. </p><p> Some devices will have dedicated hardware ("Sidekick") to animate the display content while the CPU sleeps. If the dream and the hardware support this, {@link Display#STATE_ON_SUSPEND} or {@link Display#STATE_DOZE_SUSPEND} will switch control to the Sidekick. </p><p> If not using Sidekick, it is recommended that the state be set to {@link 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. </p><p> If the doze suspend state is used, the dream must make sure to set the mode back to {@link Display#STATE_DOZE} or {@link Display#STATE_ON} before drawing again since the display updates may be ignored and not seen by the user otherwise. </p><p> 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. </p> @param {Number} state The screen state to use while dozing, such as {@link Display#STATE_ON}, {@link Display#STATE_DOZE}, {@link Display#STATE_DOZE_SUSPEND}, {@link Display#STATE_ON_SUSPEND}, {@link Display#STATE_OFF}, or {@link Display#STATE_UNKNOWN} for the default behavior. @hide For use by system UI components only. */ setDozeScreenState : function( ) {}, /**Gets the screen brightness to use while dozing. @return {Number} The screen brightness while dozing as a value between {@link PowerManager#BRIGHTNESS_OFF} (0) and {@link PowerManager#BRIGHTNESS_ON} (255), or {@link PowerManager#BRIGHTNESS_DEFAULT} (-1) to ask the system to apply its default policy based on the screen state. @see #setDozeScreenBrightness @hide For use by system UI components only. */ getDozeScreenBrightness : function( ) {}, /**Sets the screen brightness to use while dozing. <p> The value of this property determines the power state of the primary display once {@link #startDozing} has been called. The default value is {@link 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. </p><p> 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. </p><p> 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. </p> @param {Number} brightness The screen brightness while dozing as a value between {@link PowerManager#BRIGHTNESS_OFF} (0) and {@link PowerManager#BRIGHTNESS_ON} (255), or {@link PowerManager#BRIGHTNESS_DEFAULT} (-1) to ask the system to apply its default policy based on the screen state. @hide For use by system UI components only. */ setDozeScreenBrightness : function( ) {}, /**Called when this Dream is constructed. */ onCreate : function( ) {}, /**Called when the dream's window has been created and is visible and animation may now begin. */ onDreamingStarted : function( ) {}, /**Called when this Dream is stopped, either by external request or by calling finish(), before the window has been removed. */ onDreamingStopped : function( ) {}, /**Called when the dream is being asked to stop itself and wake. <p> The default implementation simply calls {@link #finish} which ends the dream immediately. Subclasses may override this function to perform a smooth exit transition then call {@link #finish} afterwards. </p><p> 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. </p> */ onWakeUp : function( ) {}, /**{@inheritDoc} */ onBind : function( ) {}, /**Stops the dream and detaches from the window. <p> 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. </p> */ finish : function( ) {}, /**Wakes the dream up gently. <p> Calls {@link #onWakeUp} to give the dream a chance to perform an exit transition. When the transition is over, the dream should call {@link #finish}. </p> */ wakeUp : function( ) {}, /**{@inheritDoc} */ onDestroy : function( ) {}, };