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 independently in a separate binding/creation of the service.

TileService will resolve against services that match the .ACTION_QS_TILE action 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>
 

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.

String META_DATA_TOGGLEABLE_TILE

Meta-data for a tile to mark is toggleable.

Inherited constants

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)

This method was deprecated in API level 34. for versions Build.VERSION_CODES.UPSIDE_DOWN_CAKE and up, use TileService#startActivityAndCollapse(PendingIntent) instead.

final void startActivityAndCollapse(PendingIntent pendingIntent)

Starts an Activity.

final void unlockAndRun(Runnable runnable)

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

Inherited methods

Constants

ACTION_QS_TILE

Added in API level 24
public static final 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
public static final 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.

This intent may also define a Intent#EXTRA_COMPONENT_NAME value to indicate the ComponentName that caused the preferences to be opened.

To ensure that the activity can only be launched through quick settings UI provided by this service, apps can protect it with the BIND_QUICK_SETTINGS_TILE permission.

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

META_DATA_ACTIVE_TILE

Added in API level 24
public static final 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"

META_DATA_TOGGLEABLE_TILE

Added in API level 30
public static final String META_DATA_TOGGLEABLE_TILE

Meta-data for a tile to mark is toggleable.

Toggleable tiles support switch tile behavior in accessibility. This is the behavior of most of the framework tiles. To indicate that a TileService is toggleable, set this meta-data to true on the TileService's manifest declaration.

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

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

Public constructors

TileService

public TileService ()

Public methods

getQsTile

Added in API level 24
public final 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
public final 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 ContextWrapper.startActivity(Intent) to launch an activity on top of the lock screen, otherwise the tile should use unlockAndRun(java.lang.Runnable) to give the user their security challenge.

Returns
boolean true if the device is locked.

isSecure

Added in API level 24
public final 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
public 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
public void onClick ()

Called when the user clicks on this tile.

onDestroy

Added in API level 24
public 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
public 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().

onStopListening

Added in API level 24
public void onStopListening ()

Called when this tile moves out of the listening state.

onTileAdded

Added in API level 24
public void onTileAdded ()

Called when the user adds this tile to Quick Settings.

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

onTileRemoved

Added in API level 24
public void onTileRemoved ()

Called when the user removes this tile from Quick Settings.

requestListeningState

Added in API level 24
public static final 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. For apps targeting Build.VERSION_CODES#TIRAMISU or later, this call may throw the following exceptions if the request is not valid:

Parameters
context Context

component ComponentName

showDialog

Added in API level 24
public final 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
Deprecated in API level 34
public final void startActivityAndCollapse (Intent intent)

This method was deprecated in API level 34.
for versions Build.VERSION_CODES.UPSIDE_DOWN_CAKE and up, use TileService#startActivityAndCollapse(PendingIntent) instead.

Start an activity while collapsing the panel.

Parameters
intent Intent

Throws
UnsupportedOperationException if called in versions Build.VERSION_CODES.UPSIDE_DOWN_CAKE and up

startActivityAndCollapse

Added in API level 34
public final void startActivityAndCollapse (PendingIntent pendingIntent)

Starts an Activity. Will collapse Quick Settings after launching.

Parameters
pendingIntent PendingIntent: A PendingIntent for an Activity to be launched immediately. This value cannot be null.

unlockAndRun

Added in API level 24
public final 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