DreamService

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 {@code DreamService} lifecycle is as follows:

1. {@link #onAttachedToWindow}

   Use this for initial setup, such as calling {@link #setContentView setContentView()}.

2. {@link #onDreamingStarted}

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

3. {@link #onDreamingStopped}

   Use this to stop the things you started in {@link #onDreamingStarted}.

4. {@link #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 {@code 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 {@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:

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 {@link #setContentView}, typically during the {@link #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 {@link 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=â