Added in API level 24

TileService


open class TileService : Service
kotlin.Any
   ↳ 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 {@value #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
static String

Action that identifies a Service as being a TileService.

static String

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

static String

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

static String

Meta-data for a tile to mark is toggleable.

Inherited constants
Public constructors

Public methods
Tile!

Gets the Tile for this service.

Boolean

Checks if the lock screen is showing.

Boolean

Checks if the device is in a secure state.

open IBinder?
onBind(intent: Intent!)

open Unit

Called when the user clicks on this tile.

open Unit

open Unit

Called when this tile moves into a listening state.

open Unit

Called when this tile moves out of the listening state.

open Unit

Called when the user adds this tile to Quick Settings.

open Unit

Called when the user removes this tile from Quick Settings.

static Unit
requestListeningState(context: Context!, component: ComponentName!)

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

Unit
showDialog(dialog: Dialog!)

Used to show a dialog.

Unit

Start an activity while collapsing the panel.

Unit

Starts an android.app.Activity.

Unit
unlockAndRun(runnable: Runnable!)

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

Inherited functions

Constants

ACTION_QS_TILE

Added in API level 24
static val ACTION_QS_TILE: String

Action that identifies a Service as being a TileService.

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

ACTION_QS_TILE_PREFERENCES

Added in API level 24
static val ACTION_QS_TILE_PREFERENCES: String

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.

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

META_DATA_ACTIVE_TILE

Added in API level 24
static val META_DATA_ACTIVE_TILE: String

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. 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" />
  
  
Value: "android.service.quicksettings.ACTIVE_TILE"

META_DATA_TOGGLEABLE_TILE

Added in API level 30
static val META_DATA_TOGGLEABLE_TILE: String

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" />
  
  
Value: "android.service.quicksettings.TOGGLEABLE_TILE"

Public constructors

TileService

TileService()

Public methods

getQsTile

Added in API level 24
fun getQsTile(): Tile!

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().

isLocked

Added in API level 24
fun isLocked(): Boolean

Checks if the lock screen is showing. When a device is locked, then showDialog 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 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.

Return
Boolean true if the device is locked.

isSecure

Added in API level 24
fun isSecure(): Boolean

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

Return
Boolean true if the device is secure.

onBind

Added in API level 24
open fun onBind(intent: Intent!): IBinder?
Parameters
intent Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Return
IBinder? Return an IBinder through which clients can call on to the service.

onClick

Added in API level 24
open fun onClick(): Unit

Called when the user clicks on this tile.

onDestroy

Added in API level 24
open fun onDestroy(): Unit

onStartListening

Added in API level 24
open fun onStartListening(): Unit

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
open fun onStopListening(): Unit

Called when this tile moves out of the listening state.

onTileAdded

Added in API level 24
open fun onTileAdded(): Unit

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
open fun onTileRemoved(): Unit

Called when the user removes this tile from Quick Settings.

requestListeningState

Added in API level 24
static fun requestListeningState(
    context: Context!,
    component: ComponentName!
): Unit

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:

showDialog

Added in API level 24
fun showDialog(dialog: Dialog!): Unit

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
fun startActivityAndCollapse(intent: Intent!): Unit

Deprecated: for versions android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE and up, use TileService#startActivityAndCollapse(PendingIntent) instead.

Start an activity while collapsing the panel.

Exceptions
java.lang.UnsupportedOperationException if called in versions android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE and up

startActivityAndCollapse

Added in API level 34
fun startActivityAndCollapse(pendingIntent: PendingIntent): Unit

Starts an android.app.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
fun unlockAndRun(runnable: Runnable!): Unit

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.