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:
*Use this for initial setup, such as calling {@link #setContentView setContentView()}.
Your dream has started, so you should begin animations or other behaviors here.
Use this to stop the things you started in {@link #onDreamingStarted}.
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
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=”android.service.dreams.DreamService” /> * <category android:name=”android.intent.category.DEFAULT” /> * </intent-filter> * </service> **/ public class DreamService extends Service implements Window.Callback { private static final String TAG = DreamService.class.getSimpleName(); private final String mTag = TAG + "[" + getClass().getSimpleName() + "]"; private static final boolean DEBUG = Log.isLoggable(TAG, Log.DEBUG); /** * The name of the dream manager service. * @hide */ public static final String DREAM_SERVICE = "dreams"; /** * The {@link Intent} that must be declared as handled by the service. */ @SdkConstant(SdkConstantType.SERVICE_ACTION) public static final String SERVICE_INTERFACE = "android.service.dreams.DreamService"; /** * The name of the extra where the dream overlay component is stored. * @hide */ public static final String EXTRA_DREAM_OVERLAY_COMPONENT = "android.service.dream.DreamService.dream_overlay_component"; /** * Name under which a Dream publishes information about itself. * This meta-data must reference an XML resource containing * a
<{@link android.R.styleable#Dream dream}>
* tag.
*/
public static final String DREAM_META_DATA = "android.service.dream";
/**
* Name of the root tag under which a Dream defines its metadata in an XML file.
*/
private static final String DREAM_META_DATA_ROOT_TAG = "dream";
/**
* The default value for whether to show complications on the overlay.
*
* @hide
*/
public static final boolean DEFAULT_SHOW_COMPLICATIONS = false;
private final IDreamManager mDreamManager;
private final Handler mHandler = new Handler(Looper.getMainLooper());
private IBinder mDreamToken;
private Window mWindow;
private Activity mActivity;
private boolean mInteractive;
private boolean mFullscreen;
private boolean mScreenBright = true;
private boolean mStarted;
private boolean mWaking;
private boolean mFinished;
private boolean mCanDoze;
private boolean mDozing;
private boolean mWindowless;
private int mDozeScreenState = Display.STATE_UNKNOWN;
private int mDozeScreenBrightness = PowerManager.BRIGHTNESS_DEFAULT;
private boolean mDebug = false;
private ComponentName mDreamComponent;
private boolean mShouldShowComplications;
private DreamServiceWrapper mDreamServiceWrapper;
private Runnable mDispatchAfterOnAttachedToWindow;
private DreamOverlayConnectionHandler mOverlayConnection;
private IDreamOverlayCallback mOverlayCallback;
public DreamService() {
mDreamManager = IDreamManager.Stub.asInterface(ServiceManager.getService(DREAM_SERVICE));
}
/**
* @hide
*/
public void setDebug(boolean dbg) {
mDebug = dbg;
}
// begin Window.Callback methods
/** {@inheritDoc} */
@Override
public boolean dispatchKeyEvent(KeyEvent event) {
// TODO: create more flexible version of mInteractive that allows use of KEYCODE_BACK
if (!mInteractive) {
if (mDebug) Slog.v(mTag, "Waking up on keyEvent");
wakeUp();
return true;
} else if (event.getKeyCode() == KeyEvent.KEYCODE_BACK) {
if (mDebug) Slog.v(mTag, "Waking up on back key");
wakeUp();
return true;
}
return mWindow.superDispatchKeyEvent(event);
}
/** {@inheritDoc} */
@Override
public boolean dispatchKeyShortcutEvent(KeyEvent event) {
if (!mInteractive) {
if (mDebug) Slog.v(mTag, "Waking up on keyShortcutEvent");
wakeUp();
return true;
}
return mWindow.superDispatchKeyShortcutEvent(event);
}
/** {@inheritDoc} */
@Override
public boolean dispatchTouchEvent(MotionEvent event) {
// TODO: create more flexible version of mInteractive that allows clicks
// but finish()es on any other kind of activity
if (!mInteractive && event.getActionMasked() == MotionEvent.ACTION_UP) {
if (mDebug) Slog.v(mTag, "Waking up on touchEvent");
wakeUp();
return true;
}
return mWindow.superDispatchTouchEvent(event);
}
/** {@inheritDoc} */
@Override
public boolean dispatchTrackballEvent(MotionEvent event) {
if (!mInteractive) {
if (mDebug) Slog.v(mTag, "Waking up on trackballEvent");
wakeUp();
return true;
}
return mWindow.superDispatchTrackballEvent(event);
}
/** {@inheritDoc} */
@Override
public boolean dispatchGenericMotionEvent(MotionEvent event) {
if (!mInteractive) {
if (mDebug) Slog.v(mTag, "Waking up on genericMotionEvent");
wakeUp();
return true;
}
return mWindow.superDispatchGenericMotionEvent(event);
}
/** {@inheritDoc} */
@Override
public boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event) {
return false;
}
/** {@inheritDoc} */
@Override
public View onCreatePanelView(int featureId) {
return null;
}
/** {@inheritDoc} */
@Override
public boolean onCreatePanelMenu(int featureId, Menu menu) {
return false;
}
/** {@inheritDoc} */
@Override
public boolean onPreparePanel(int featureId, View view, Menu menu) {
return false;
}
/** {@inheritDoc} */
@Override
public boolean onMenuOpened(int featureId, Menu menu) {
return false;
}
/** {@inheritDoc} */
@Override
public boolean onMenuItemSelected(int featureId, MenuItem item) {
return false;
}
/** {@inheritDoc} */
@Override
public void onWindowAttributesChanged(LayoutParams attrs) {
}
/** {@inheritDoc} */
@Override
public void onContentChanged() {
}
/** {@inheritDoc} */
@Override
public void onWindowFocusChanged(boolean hasFocus) {
}
/** {@inheritDoc} */
@Override
public void onAttachedToWindow() {
}
/** {@inheritDoc} */
@Override
public void onDetachedFromWindow() {
}
/** {@inheritDoc} */
@Override
public void onPanelClosed(int featureId, Menu menu) {
}
/** {@inheritDoc} */
@Override
public boolean onSearchRequested(SearchEvent event) {
return onSearchRequested();
}
/** {@inheritDoc} */
@Override
public boolean onSearchRequested() {
return false;
}
/** {@inheritDoc} */
@Override
public ActionMode onWindowStartingActionMode(android.view.ActionMode.Callback callback) {
return null;
}
/** {@inheritDoc} */
@Override
public ActionMode onWindowStartingActionMode(
android.view.ActionMode.Callback callback, int type) {
return null;
}
/** {@inheritDoc} */
@Override
public void onActionModeStarted(ActionMode mode) {
}
/** {@inheritDoc} */
@Override
public void onActionModeFinished(ActionMode mode) {
}
// end Window.Callback methods
// begin public api
/**
* Retrieves the current {@link android.view.WindowManager} for the dream.
* Behaves similarly to {@link android.app.Activity#getWindowManager()}.
*
* @return The current window manager, or null if the dream is not started.
*/
public WindowManager getWindowManager() {
return mWindow != null ? mWindow.getWindowManager() : null;
}
/**
* Retrieves the current {@link android.view.Window} for the dream.
* Behaves similarly to {@link android.app.Activity#getWindow()}.
*
* @return The current window, or null if the dream is not started.
*/
public Window getWindow() {
return mWindow;
}
/**
* Inflates a layout resource and set it to be the content view for this Dream.
* Behaves similarly to {@link android.app.Activity#setContentView(int)}.
*
* Note: Requires a window, do not call before {@link #onAttachedToWindow()}
* * @param layoutResID Resource ID to be inflated. * * @see #setContentView(android.view.View) * @see #setContentView(android.view.View, android.view.ViewGroup.LayoutParams) */ public void setContentView(@LayoutRes int layoutResID) { getWindow().setContentView(layoutResID); } /** * 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. * *Note: This requires a window, so you should usually call it during * {@link #onAttachedToWindow()} and never earlier (you cannot call it * during {@link #onCreate}).
* * @see #setContentView(int) * @see #setContentView(android.view.View, android.view.ViewGroup.LayoutParams) */ public void setContentView(View view) { getWindow().setContentView(view); } /** * 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. * *Note: This requires a window, so you should usually call it during * {@link #onAttachedToWindow()} and never earlier (you cannot call it * during {@link #onCreate}).
* * @param view The desired content to display. * @param params Layout parameters for the view. * * @see #setContentView(android.view.View) * @see #setContentView(int) */ public void setContentView(View view, ViewGroup.LayoutParams params) { getWindow().setContentView(view, params); } /** * Adds a view to the Dream's window, leaving other content views in place. * *Note: Requires a window, do not call before {@link #onAttachedToWindow()}
* * @param view The desired content to display. * @param params Layout parameters for the view. */ public void addContentView(View view, ViewGroup.LayoutParams params) { getWindow().addContentView(view, params); } /** * Finds a view that was identified by the id attribute from the XML that * was processed in {@link #onCreate}. * *Note: Requires a window, do not call before {@link #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.
*
* @param id the ID to search for
* @return The view if found or null otherwise.
* @see View#findViewById(int)
* @see DreamService#requireViewById(int)
*/
@Nullable
public Note: Requires a window, do not call before {@link #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.
*
* @param id the ID to search for
* @return a view with given ID
* @see View#requireViewById(int)
* @see DreamService#findViewById(int)
*/
@NonNull
public final Non-interactive dreams (default) will dismiss on the first input event. Interactive dreams should call {@link #finish()} to dismiss themselves.
* The value returned by this method is only meaningful when the dream has started.
*
* 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 {@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.
*
* 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 {@link #stopDozing} or {@link #finish} to stop dozing.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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}.
* null if the {@link ServiceInfo} doesn't contain valid dream metadata.
*/
@Nullable
private static TypedArray readMetadata(PackageManager pm, ServiceInfo serviceInfo) {
if (serviceInfo == null || serviceInfo.metaData == null) {
return null;
}
try (XmlResourceParser parser =
serviceInfo.loadXmlMetaData(pm, DreamService.DREAM_META_DATA)) {
if (parser == null) {
if (DEBUG) Log.w(TAG, "No " + DreamService.DREAM_META_DATA + " metadata");
return null;
}
final AttributeSet attrs = Xml.asAttributeSet(parser);
while (true) {
final int type = parser.next();
if (type == XmlPullParser.END_DOCUMENT || type == XmlPullParser.START_TAG) {
break;
}
}
if (!parser.getName().equals(DREAM_META_DATA_ROOT_TAG)) {
if (DEBUG) {
Log.w(TAG, "Metadata does not start with " + DREAM_META_DATA_ROOT_TAG + " tag");
}
return null;
}
return pm.getResourcesForApplication(serviceInfo.applicationInfo).obtainAttributes(
attrs, com.android.internal.R.styleable.Dream);
} catch (PackageManager.NameNotFoundException | IOException | XmlPullParserException e) {
if (DEBUG) Log.e(TAG, "Error parsing: " + serviceInfo.packageName, e);
return null;
}
}
@Nullable
private static ComponentName convertToComponentName(@Nullable String flattenedString,
ServiceInfo serviceInfo) {
if (flattenedString == null) {
return null;
}
if (!flattenedString.contains("/")) {
return new ComponentName(serviceInfo.packageName, flattenedString);
}
// Ensure that the component is from the same package as the dream service. If not,
// treat the component as invalid and return null instead.
final ComponentName cn = ComponentName.unflattenFromString(flattenedString);
if (cn == null) return null;
if (!cn.getPackageName().equals(serviceInfo.packageName)) {
Log.w(TAG,
"Inconsistent package name in component: " + cn.getPackageName()
+ ", should be: " + serviceInfo.packageName);
return null;
}
return cn;
}
/**
* Called by DreamController.stopDream() when the Dream is about to be unbound and destroyed.
*
* Must run on mHandler.
*/
private void detach() {
if (mStarted) {
if (mDebug) Slog.v(mTag, "detach(): Calling onDreamingStopped()");
mStarted = false;
onDreamingStopped();
}
if (mActivity != null && !mActivity.isFinishing()) {
mActivity.finishAndRemoveTask();
} else {
finish();
}
mDreamToken = null;
mCanDoze = false;
}
/**
* Called when the Dream is ready to be shown.
*
* Must run on mHandler.
*
* @param dreamToken Token for this dream service.
* @param started A callback that will be invoked once onDreamingStarted has completed.
*/
private void attach(IBinder dreamToken, boolean canDoze, boolean isPreviewMode,
IRemoteCallback started) {
if (mDreamToken != null) {
Slog.e(mTag, "attach() called when dream with token=" + mDreamToken
+ " already attached");
return;
}
if (mFinished || mWaking) {
Slog.w(mTag, "attach() called after dream already finished");
try {
mDreamManager.finishSelf(dreamToken, true /*immediate*/);
} catch (RemoteException ex) {
// system server died
}
return;
}
mDreamToken = dreamToken;
mCanDoze = canDoze;
// This is not a security check to prevent malicious dreams but a guard rail to stop
// third-party dreams from being windowless and not working well as a result.
if (mWindowless && !mCanDoze && !isCallerSystemUi()) {
throw new IllegalStateException("Only doze or SystemUI dreams can be windowless.");
}
mDispatchAfterOnAttachedToWindow = () -> {
if (mWindow != null || mWindowless) {
mStarted = true;
try {
onDreamingStarted();
} finally {
try {
started.sendResult(null);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
}
};
// We need to defer calling onDreamingStarted until after the activity is created.
// If the dream is windowless, we can call it immediately. Otherwise, we wait
// for the DreamActivity to report onActivityCreated via
// DreamServiceWrapper.onActivityCreated.
if (!mWindowless) {
Intent i = new Intent(this, DreamActivity.class);
i.setPackage(getApplicationContext().getPackageName());
i.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_NO_USER_ACTION);
i.putExtra(DreamActivity.EXTRA_CALLBACK, new DreamActivityCallbacks(mDreamToken));
final ServiceInfo serviceInfo = fetchServiceInfo(this,
new ComponentName(this, getClass()));
i.putExtra(DreamActivity.EXTRA_DREAM_TITLE,
fetchDreamLabel(this, serviceInfo, isPreviewMode));
try {
mDreamManager.startDreamActivity(i);
} catch (SecurityException e) {
Log.w(mTag,
"Received SecurityException trying to start DreamActivity. "
+ "Aborting dream start.");
detach();
} catch (RemoteException e) {
Log.w(mTag, "Could not connect to activity task manager to start dream activity");
e.rethrowFromSystemServer();
}
} else {
mDispatchAfterOnAttachedToWindow.run();
}
}
private void onWindowCreated(Window w) {
mWindow = w;
mWindow.setCallback(this);
mWindow.requestFeature(Window.FEATURE_NO_TITLE);
WindowManager.LayoutParams lp = mWindow.getAttributes();
lp.flags |= (WindowManager.LayoutParams.FLAG_LAYOUT_IN_SCREEN
| WindowManager.LayoutParams.FLAG_LAYOUT_INSET_DECOR
| WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED
| WindowManager.LayoutParams.FLAG_DISMISS_KEYGUARD
| WindowManager.LayoutParams.FLAG_ALLOW_LOCK_WHILE_SCREEN_ON
| WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED
| (mFullscreen ? WindowManager.LayoutParams.FLAG_FULLSCREEN : 0)
| (mScreenBright ? WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON : 0)
);
lp.layoutInDisplayCutoutMode =
WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS;
mWindow.setAttributes(lp);
// Workaround: Currently low-profile and in-window system bar backgrounds don't go
// along well. Dreams usually don't need such bars anyways, so disable them by default.
mWindow.clearFlags(WindowManager.LayoutParams.FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS);
// Hide all insets when the dream is showing
mWindow.getDecorView().getWindowInsetsController().hide(WindowInsets.Type.systemBars());
mWindow.setDecorFitsSystemWindows(false);
mWindow.getDecorView().addOnAttachStateChangeListener(
new View.OnAttachStateChangeListener() {
private Consumer