Most visited

Recently visited

Added in API level 24

TileService

public class TileService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.service.quicksettings.TileService


A TileService provides the user a tile that can be added to Quick Settings. Quick Settings is a space provided that allows the user to change settings and take quick actions without leaving the context of their current app.

The lifecycle of a TileService is different from some other services in that it may be unbound during parts of its lifecycle. Any of the following lifecycle events can happen indepently in a separate binding/creation of the service.

TileService will be detected by tiles that match the .ACTION_QS_TILE and require the permission "android.permission.BIND_QUICK_SETTINGS_TILE". The label and icon for the service will be used as the default label and icon for the tile. Here is an example TileService declaration.

 <service
     android:name=".MyQSTileService"
     android:label="@string/my_default_tile_label"
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>
 

See also:

Summary

Constants

String ACTION_QS_TILE

Action that identifies a Service as being a TileService.

String ACTION_QS_TILE_PREFERENCES

An activity that provides a user interface for adjusting TileService preferences.

String META_DATA_ACTIVE_TILE

Meta-data for tile definition to set a tile into active mode.

Inherited constants

From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2

Public constructors

TileService()

Public methods

final Tile getQsTile()

Gets the Tile for this service.

final boolean isLocked()

Checks if the lock screen is showing.

final boolean isSecure()

Checks if the device is in a secure state.

IBinder onBind(Intent intent)

Return the communication channel to the service.

void onClick()

Called when the user clicks on this tile.

void onDestroy()

Called by the system to notify a Service that it is no longer used and is being removed.

void onStartListening()

Called when this tile moves into a listening state.

void onStopListening()

Called when this tile moves out of the listening state.

void onTileAdded()

Called when the user adds this tile to Quick Settings.

void onTileRemoved()

Called when the user removes this tile from Quick Settings.

static final void requestListeningState(Context context, ComponentName component)

Requests that a tile be put in the listening state so it can send an update.

final void showDialog(Dialog dialog)

Used to show a dialog.

final void startActivityAndCollapse(Intent intent)

Start an activity while collapsing the panel.

final void unlockAndRun(Runnable runnable)

Prompts the user to unlock the device before executing the Runnable.

Inherited methods

From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks2
From interface android.content.ComponentCallbacks

Constants

ACTION_QS_TILE

Added in API level 24
String ACTION_QS_TILE

Action that identifies a Service as being a TileService.

Constant Value: "android.service.quicksettings.action.QS_TILE"

ACTION_QS_TILE_PREFERENCES

Added in API level 24
String ACTION_QS_TILE_PREFERENCES

An activity that provides a user interface for adjusting TileService preferences. Optional but recommended for apps that implement a TileService.

Constant Value: "android.service.quicksettings.action.QS_TILE_PREFERENCES"

META_DATA_ACTIVE_TILE

Added in API level 24
String META_DATA_ACTIVE_TILE

Meta-data for tile definition to set a tile into active mode.

Active mode is for tiles which already listen and keep track of their state in their own process. These tiles may request to send an update to the System while their process is alive using requestListeningState(Context, ComponentName). The System will only bind these tiles on its own when a click needs to occur. To make a TileService an active tile, set this meta-data to true on the TileService's manifest declaration.

 <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
      android:value="true" />
 
 

Constant Value: "android.service.quicksettings.ACTIVE_TILE"

Public constructors

TileService

Added in API level 24
TileService ()

Public methods

getQsTile

Added in API level 24
Tile getQsTile ()

Gets the Tile for this service.

This tile may be used to get or set the current state for this tile. This tile is only valid for updates between onStartListening() and onStopListening().

Returns
Tile

isLocked

Added in API level 24
boolean isLocked ()

Checks if the lock screen is showing. When a device is locked, then showDialog(Dialog) will not present a dialog, as it will be under the lock screen. If the behavior of the Tile is safe to do while locked, then the user should use startActivity(Intent) to launch an activity on top of the lock screen, otherwise the tile should use unlockAndRun(Runnable) to give the user their security challenge.

Returns
boolean true if the device is locked.

isSecure

Added in API level 24
boolean isSecure ()

Checks if the device is in a secure state. TileServices should detect when the device is secure and change their behavior accordingly.

Returns
boolean true if the device is secure.

onBind

Added in API level 24
IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned 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.

Parameters
intent 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.
Returns
IBinder Return an IBinder through which clients can call on to the service.

onClick

Added in API level 24
void onClick ()

Called when the user clicks on this tile.

onDestroy

Added in API level 24
void onDestroy ()

Called by the system to notify a Service that it is no longer used and is being removed. The service should clean up any resources it holds (threads, registered receivers, etc) at this point. Upon return, there will be no more calls in to this Service object and it is effectively dead. Do not call this method directly.

onStartListening

Added in API level 24
void onStartListening ()

Called when this tile moves into a listening state.

When this tile is in a listening state it is expected to keep the UI up to date. Any listeners or callbacks needed to keep this tile up to date should be registered here and unregistered in onStopListening().

See also:

onStopListening

Added in API level 24
void onStopListening ()

Called when this tile moves out of the listening state.

onTileAdded

Added in API level 24
void onTileAdded ()

Called when the user adds this tile to Quick Settings.

Note that this is not guaranteed to be called between onCreate() and onStartListening(), it will only be called when the tile is added and not on subsequent binds.

onTileRemoved

Added in API level 24
void onTileRemoved ()

Called when the user removes this tile from Quick Settings.

requestListeningState

Added in API level 24
void requestListeningState (Context context, 
                ComponentName component)

Requests that a tile be put in the listening state so it can send an update. This method is only applicable to tiles that have META_DATA_ACTIVE_TILE defined as true on their TileService Manifest declaration, and will do nothing otherwise.

Parameters
context Context
component ComponentName

showDialog

Added in API level 24
void showDialog (Dialog dialog)

Used to show a dialog. This will collapse the Quick Settings panel and show the dialog.

Parameters
dialog Dialog: Dialog to show.

See also:

startActivityAndCollapse

Added in API level 24
void startActivityAndCollapse (Intent intent)

Start an activity while collapsing the panel.

Parameters
intent Intent

unlockAndRun

Added in API level 24
void unlockAndRun (Runnable runnable)

Prompts the user to unlock the device before executing the Runnable.

The user will be prompted for their current security method if applicable and if successful, runnable will be executed. The Runnable will not be executed if the user fails to unlock the device or cancels the operation.

Parameters
runnable Runnable

Hooray!