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.
- When a tile is added by the user its TileService will be bound to and
onTileAdded()
will be called. - When a tile should be up to date and listing will be indicated by
onStartListening()
andonStopListening()
. - When the user removes a tile from Quick Settings
onTileRemoved()
will be called. onTileAdded()
andonTileRemoved()
may be called outside of theService.onCreate()
-onDestroy()
window
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 |
CATEGORY_ACCESSIBILITY
Tile category for accessibility related tiles. |
String |
CATEGORY_CONNECTIVITY
Tile category for connectivity related tiles. |
String |
CATEGORY_DISPLAY
Tile category for display related tiles. |
String |
CATEGORY_PRIVACY
Tile category for privacy related tiles. |
String |
CATEGORY_UTILITIES
Tile category for utility tiles. |
String |
META_DATA_ACTIVE_TILE
Meta-data for tile definition to set a tile into active mode. |
String |
META_DATA_TILE_CATEGORY
Meta-data to set a category for a tile. |
String |
META_DATA_TOGGLEABLE_TILE
Meta-data for a tile to mark is toggleable. |
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 |
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 |
final
void
|
startActivityAndCollapse(PendingIntent pendingIntent)
Starts an |
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
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
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"
CATEGORY_ACCESSIBILITY
public static final String CATEGORY_ACCESSIBILITY
Tile category for accessibility related tiles. This is a possible value for
ERROR(/META_DATA_TILE_CATEGORY)
Constant Value: "android.service.quicksettings.CATEGORY_ACCESSIBILITY"
CATEGORY_CONNECTIVITY
public static final String CATEGORY_CONNECTIVITY
Tile category for connectivity related tiles. This is a possible value for
ERROR(/META_DATA_TILE_CATEGORY)
Constant Value: "android.service.quicksettings.CATEGORY_CONNECTIVITY"
CATEGORY_DISPLAY
public static final String CATEGORY_DISPLAY
Tile category for display related tiles. This is a possible value for
ERROR(/META_DATA_TILE_CATEGORY)
Constant Value: "android.service.quicksettings.CATEGORY_DISPLAY"
CATEGORY_PRIVACY
public static final String CATEGORY_PRIVACY
Tile category for privacy related tiles. This is a possible value for
ERROR(/META_DATA_TILE_CATEGORY)
Constant Value: "android.service.quicksettings.CATEGORY_PRIVACY"
CATEGORY_UTILITIES
public static final String CATEGORY_UTILITIES
Tile category for utility tiles. This is a possible value for
ERROR(/META_DATA_TILE_CATEGORY)
.
Constant Value: "android.service.quicksettings.CATEGORY_UTILITIES"
META_DATA_ACTIVE_TILE
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_TILE_CATEGORY
public static final String META_DATA_TILE_CATEGORY
Meta-data to set a category for a tile. Optional but recommended for apps that implement a TileService.
This category could be used to classify the provided tile, such as in the edit page for Quick Settings.
To set the category of a TileService, set this meta-data to the appropriate string on the TileService's manifest declaration. For example:
<meta-data android:name="android.service.quicksettings.TILE_CATEGORY" android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
Constant Value: "android.service.quicksettings.TILE_CATEGORY"
META_DATA_TOGGLEABLE_TILE
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
public final Tile getQsTile ()
Gets the Tile
for this service.
onStartListening()
and onStopListening()
.
Returns | |
---|---|
Tile |
isLocked
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
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
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. |
onDestroy
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
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 inonStopListening()
.
See also:
onStopListening
public void onStopListening ()
Called when this tile moves out of the listening state.
onTileAdded
public void onTileAdded ()
Called when the user adds this tile to Quick Settings.
Note that this is not guaranteed to be called betweenService.onCreate()
and onStartListening()
, it will only be called when the tile is added
and not on subsequent binds.
onTileRemoved
public void onTileRemoved ()
Called when the user removes this tile from Quick Settings.
requestListeningState
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:
-
NullPointerException
ifcomponent
isnull
. -
SecurityException
if the package ofcomponent
does not match the calling package or if the calling user cannot act on behalf of the user from thecontext
. -
IllegalArgumentException
if the user of thecontext
is not the current user. Only thrown for apps targetingBuild.VERSION_CODES.TIRAMISU
Parameters | |
---|---|
context |
Context |
component |
ComponentName |
showDialog
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
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
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
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 |