core/java/android/service/quicksettings/TileService.java

   1 /*
   2  * Copyright (C) 2015 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 package android.service.quicksettings;
  17
  18 import android.Manifest;
  19 import android.annotation.SdkConstant;
  20 import android.annotation.SdkConstant.SdkConstantType;
  21 import android.annotation.SystemApi;
  22 import android.app.Dialog;
  23 import android.app.Service;
  24 import android.content.ComponentName;
  25 import android.content.Context;
  26 import android.content.Intent;
  27 import android.graphics.drawable.Icon;
  28 import android.os.Handler;
  29 import android.os.IBinder;
  30 import android.os.Looper;
  31 import android.os.Message;
  32 import android.os.RemoteException;
  33 import android.view.View;
  34 import android.view.View.OnAttachStateChangeListener;
  35 import android.view.WindowManager;
  36
  37 /**
  38  * A TileService provides the user a tile that can be added to Quick Settings.
  39  * Quick Settings is a space provided that allows the user to change settings and
  40  * take quick actions without leaving the context of their current app.
  41  *
  42  * <p>The lifecycle of a TileService is different from some other services in
  43  * that it may be unbound during parts of its lifecycle.  Any of the following
  44  * lifecycle events can happen indepently in a separate binding/creation of the
  45  * service.</p>
  46  *
  47  * <ul>
  48  * <li>When a tile is added by the user its TileService will be bound to and
  49  * {@link #onTileAdded()} will be called.</li>
  50  *
  51  * <li>When a tile should be up to date and listing will be indicated by
  52  * {@link #onStartListening()} and {@link #onStopListening()}.</li>
  53  *
  54  * <li>When the user removes a tile from Quick Settings {@link #onTileRemoved()}
  55  * will be called.</li>
  56  * </ul>
  57  * <p>TileService will be detected by tiles that match the {@value #ACTION_QS_TILE}
  58  * and require the permission "android.permission.BIND_QUICK_SETTINGS_TILE".
  59  * The label and icon for the service will be used as the default label and
  60  * icon for the tile. Here is an example TileService declaration.</p>
  61  * <pre class="prettyprint">
  62  * {@literal
  63  * <service
  64  *     android:name=".MyQSTileService"
  65  *     android:label="@string/my_default_tile_label"
  66  *     android:icon="@drawable/my_default_icon_label"
  67  *     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
  68  *     <intent-filter>
  69  *         <action android:name="android.service.quicksettings.action.QS_TILE" />
  70  *     </intent-filter>
  71  * </service>}
  72  * </pre>
  73  *
  74  * @see Tile Tile for details about the UI of a Quick Settings Tile.
  75  */
  76 public class TileService extends Service {
  77
  78     /**
  79      * An activity that provides a user interface for adjusting TileService preferences.
  80      * Optional but recommended for apps that implement a TileService.
  81      */
  82     @SdkConstant(SdkConstantType.INTENT_CATEGORY)
  83     public static final String ACTION_QS_TILE_PREFERENCES
  84             = "android.service.quicksettings.action.QS_TILE_PREFERENCES";
  85
  86     /**
  87      * Action that identifies a Service as being a TileService.
  88      */
  89     public static final String ACTION_QS_TILE = "android.service.quicksettings.action.QS_TILE";
  90
  91     /**
  92      * Meta-data for tile definition to set a tile into active mode.
  93      * <p>
  94      * Active mode is for tiles which already listen and keep track of their state in their
  95      * own process.  These tiles may request to send an update to the System while their process
  96      * is alive using {@link #requestListeningState}.  The System will only bind these tiles
  97      * on its own when a click needs to occur.
  98      *
  99      * To make a TileService an active tile, set this meta-data to true on the TileService's
 100      * manifest declaration.
 101      * <pre class="prettyprint">
 102      * {@literal
 103      * <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
 104      *      android:value="true" />
 105      * }
 106      * </pre>
 107      */
 108     public static final String META_DATA_ACTIVE_TILE
 109             = "android.service.quicksettings.ACTIVE_TILE";
 110
 111     /**
 112      * Used to notify SysUI that Listening has be requested.
 113      * @hide
 114      */
 115     public static final String ACTION_REQUEST_LISTENING
 116             = "android.service.quicksettings.action.REQUEST_LISTENING";
 117
 118     /**
 119      * @hide
 120      */
 121     public static final String EXTRA_SERVICE = "service";
 122
 123     /**
 124      * @hide
 125      */
 126     public static final String EXTRA_TOKEN = "token";
 127
 128     /**
 129      * @hide
 130      */
 131     public static final String EXTRA_COMPONENT = "android.service.quicksettings.extra.COMPONENT";
 132
 133     private final H mHandler = new H(Looper.getMainLooper());
 134
 135     private boolean mListening = false;
 136     private Tile mTile;
 137     private IBinder mToken;
 138     private IQSService mService;
 139     private Runnable mUnlockRunnable;
 140     private IBinder mTileToken;
 141
 142     @Override
 143     public void onDestroy() {
 144         if (mListening) {
 145             onStopListening();
 146             mListening = false;
 147         }
 148         super.onDestroy();
 149     }
 150
 151     /**
 152      * Called when the user adds this tile to Quick Settings.
 153      * <p/>
 154      * Note that this is not guaranteed to be called between {@link #onCreate()}
 155      * and {@link #onStartListening()}, it will only be called when the tile is added
 156      * and not on subsequent binds.
 157      */
 158     public void onTileAdded() {
 159     }
 160
 161     /**
 162      * Called when the user removes this tile from Quick Settings.
 163      */
 164     public void onTileRemoved() {
 165     }
 166
 167     /**
 168      * Called when this tile moves into a listening state.
 169      * <p/>
 170      * When this tile is in a listening state it is expected to keep the
 171      * UI up to date.  Any listeners or callbacks needed to keep this tile
 172      * up to date should be registered here and unregistered in {@link #onStopListening()}.
 173      *
 174      * @see #getQsTile()
 175      * @see Tile#updateTile()
 176      */
 177     public void onStartListening() {
 178     }
 179
 180     /**
 181      * Called when this tile moves out of the listening state.
 182      */
 183     public void onStopListening() {
 184     }
 185
 186     /**
 187      * Called when the user clicks on this tile.
 188      */
 189     public void onClick() {
 190     }
 191
 192     /**
 193      * Sets an icon to be shown in the status bar.
 194      * <p>
 195      * The icon will be displayed before all other icons.  Can only be called between
 196      * {@link #onStartListening} and {@link #onStopListening}.  Can only be called by system apps.
 197      *
 198      * @param icon The icon to be displayed, null to hide
 199      * @param contentDescription Content description of the icon to be displayed
 200      * @hide
 201      */
 202     @SystemApi
 203     public final void setStatusIcon(Icon icon, String contentDescription) {
 204         if (mService != null) {
 205             try {
 206                 mService.updateStatusIcon(mTileToken, icon, contentDescription);
 207             } catch (RemoteException e) {
 208             }
 209         }
 210     }
 211
 212     /**
 213      * Used to show a dialog.
 214      *
 215      * This will collapse the Quick Settings panel and show the dialog.
 216      *
 217      * @param dialog Dialog to show.
 218      *
 219      * @see #isLocked()
 220      */
 221     public final void showDialog(Dialog dialog) {
 222         dialog.getWindow().getAttributes().token = mToken;
 223         dialog.getWindow().setType(WindowManager.LayoutParams.TYPE_QS_DIALOG);
 224         dialog.getWindow().getDecorView().addOnAttachStateChangeListener(
 225                 new OnAttachStateChangeListener() {
 226             @Override
 227             public void onViewAttachedToWindow(View v) {
 228             }
 229
 230             @Override
 231             public void onViewDetachedFromWindow(View v) {
 232                 try {
 233                     mService.onDialogHidden(mTileToken);
 234                 } catch (RemoteException e) {
 235                 }
 236             }
 237         });
 238         dialog.show();
 239         try {
 240             mService.onShowDialog(mTileToken);
 241         } catch (RemoteException e) {
 242         }
 243     }
 244
 245     /**
 246      * Prompts the user to unlock the device before executing the Runnable.
 247      * <p>
 248      * The user will be prompted for their current security method if applicable
 249      * and if successful, runnable will be executed.  The Runnable will not be
 250      * executed if the user fails to unlock the device or cancels the operation.
 251      */
 252     public final void unlockAndRun(Runnable runnable) {
 253         mUnlockRunnable = runnable;
 254         try {
 255             mService.startUnlockAndRun(mTileToken);
 256         } catch (RemoteException e) {
 257         }
 258     }
 259
 260     /**
 261      * Checks if the device is in a secure state.
 262      *
 263      * TileServices should detect when the device is secure and change their behavior
 264      * accordingly.
 265      *
 266      * @return true if the device is secure.
 267      */
 268     public final boolean isSecure() {
 269         try {
 270             return mService.isSecure();
 271         } catch (RemoteException e) {
 272             return true;
 273         }
 274     }
 275
 276     /**
 277      * Checks if the lock screen is showing.
 278      *
 279      * When a device is locked, then {@link #showDialog} will not present a dialog, as it will
 280      * be under the lock screen. If the behavior of the Tile is safe to do while locked,
 281      * then the user should use {@link #startActivity} to launch an activity on top of the lock
 282      * screen, otherwise the tile should use {@link #unlockAndRun(Runnable)} to give the
 283      * user their security challenge.
 284      *
 285      * @return true if the device is locked.
 286      */
 287     public final boolean isLocked() {
 288         try {
 289             return mService.isLocked();
 290         } catch (RemoteException e) {
 291             return true;
 292         }
 293     }
 294
 295     /**
 296      * Start an activity while collapsing the panel.
 297      */
 298     public final void startActivityAndCollapse(Intent intent) {
 299         startActivity(intent);
 300         try {
 301             mService.onStartActivity(mTileToken);
 302         } catch (RemoteException e) {
 303         }
 304     }
 305
 306     /**
 307      * Gets the {@link Tile} for this service.
 308      * <p/>
 309      * This tile may be used to get or set the current state for this
 310      * tile. This tile is only valid for updates between {@link #onStartListening()}
 311      * and {@link #onStopListening()}.
 312      */
 313     public final Tile getQsTile() {
 314         return mTile;
 315     }
 316
 317     @Override
 318     public IBinder onBind(Intent intent) {
 319         mService = IQSService.Stub.asInterface(intent.getIBinderExtra(EXTRA_SERVICE));
 320         mTileToken = intent.getIBinderExtra(EXTRA_TOKEN);
 321         try {
 322             mTile = mService.getTile(mTileToken);
 323         } catch (RemoteException e) {
 324             throw new RuntimeException("Unable to reach IQSService", e);
 325         }
 326         if (mTile != null) {
 327             mTile.setService(mService, mTileToken);
 328             mHandler.sendEmptyMessage(H.MSG_START_SUCCESS);
 329         }
 330         return new IQSTileService.Stub() {
 331             @Override
 332             public void onTileRemoved() throws RemoteException {
 333                 mHandler.sendEmptyMessage(H.MSG_TILE_REMOVED);
 334             }
 335
 336             @Override
 337             public void onTileAdded() throws RemoteException {
 338                 mHandler.sendEmptyMessage(H.MSG_TILE_ADDED);
 339             }
 340
 341             @Override
 342             public void onStopListening() throws RemoteException {
 343                 mHandler.sendEmptyMessage(H.MSG_STOP_LISTENING);
 344             }
 345
 346             @Override
 347             public void onStartListening() throws RemoteException {
 348                 mHandler.sendEmptyMessage(H.MSG_START_LISTENING);
 349             }
 350
 351             @Override
 352             public void onClick(IBinder wtoken) throws RemoteException {
 353                 mHandler.obtainMessage(H.MSG_TILE_CLICKED, wtoken).sendToTarget();
 354             }
 355
 356             @Override
 357             public void onUnlockComplete() throws RemoteException{
 358                 mHandler.sendEmptyMessage(H.MSG_UNLOCK_COMPLETE);
 359             }
 360         };
 361     }
 362
 363     private class H extends Handler {
 364         private static final int MSG_START_LISTENING = 1;
 365         private static final int MSG_STOP_LISTENING = 2;
 366         private static final int MSG_TILE_ADDED = 3;
 367         private static final int MSG_TILE_REMOVED = 4;
 368         private static final int MSG_TILE_CLICKED = 5;
 369         private static final int MSG_UNLOCK_COMPLETE = 6;
 370         private static final int MSG_START_SUCCESS = 7;
 371
 372         public H(Looper looper) {
 373             super(looper);
 374         }
 375
 376         @Override
 377         public void handleMessage(Message msg) {
 378             switch (msg.what) {
 379                 case MSG_TILE_ADDED:
 380                     TileService.this.onTileAdded();
 381                     break;
 382                 case MSG_TILE_REMOVED:
 383                     if (mListening) {
 384                         mListening = false;
 385                         TileService.this.onStopListening();
 386                     }
 387                     TileService.this.onTileRemoved();
 388                     break;
 389                 case MSG_STOP_LISTENING:
 390                     if (mListening) {
 391                         mListening = false;
 392                         TileService.this.onStopListening();
 393                     }
 394                     break;
 395                 case MSG_START_LISTENING:
 396                     if (!mListening) {
 397                         mListening = true;
 398                         TileService.this.onStartListening();
 399                     }
 400                     break;
 401                 case MSG_TILE_CLICKED:
 402                     mToken = (IBinder) msg.obj;
 403                     TileService.this.onClick();
 404                     break;
 405                 case MSG_UNLOCK_COMPLETE:
 406                     if (mUnlockRunnable != null) {
 407                         mUnlockRunnable.run();
 408                     }
 409                     break;
 410                 case MSG_START_SUCCESS:
 411                     try {
 412                         mService.onStartSuccessful(mTileToken);
 413                     } catch (RemoteException e) {
 414                     }
 415                     break;
 416             }
 417         }
 418     }
 419
 420     /**
 421      * Requests that a tile be put in the listening state so it can send an update.
 422      *
 423      * This method is only applicable to tiles that have {@link #META_DATA_ACTIVE_TILE} defined
 424      * as true on their TileService Manifest declaration, and will do nothing otherwise.
 425      */
 426     public static final void requestListeningState(Context context, ComponentName component) {
 427         Intent intent = new Intent(ACTION_REQUEST_LISTENING);
 428         intent.putExtra(EXTRA_COMPONENT, component);
 429         context.sendBroadcast(intent, Manifest.permission.BIND_QUICK_SETTINGS_TILE);
 430     }
 431 }