You are reading 12.6.1. See this page in 13.4.1.
Titanium.Android.QuickSettingsService
Extends Titanium.Android.ServiceTitanium.Proxy
Android service for creating custom quick settings tiles and handling user's interaction with them.
A special kind of service providing access to a tile in the quick settings menu. Used for customization and event handling of the tile. Usage is similar to default Titanium.Android.Service but with the addition of some specific attributes and methods. This service is not started from within the application with the help of an Intent, but instead whenever the custom tile is added in the quick settings menu by the user. Applications can have multiple tiles in the quick settigs menu, but a Titanium.Android.QuickSettingsService corresponds to a single one - you need separate service file for every tile.
To create a service file:
- Write the JavaScript code you want the service to execute in a separate file. The service can execute any Titanium APIs but you should only use non-UI APIs.
- Register the service in your
tiapp.xmlfile. Refer to the example below.
Icons used for the 'icon' attribute in the service declaration in tiapp.xml must
be in the Android drawables folder, so they you should be put under
platform/android/res/drawable
Icons added with the setIcon method can be outside the directory.
To get a reference to the Service inside the JavaScript service code, use the
Titanium.Android.currentService property to retrieve a reference to the service,
Further Reading:
Examples
Update Tile Example
This example shows how to create a service in JavaScript. It will update the Tile in quick settings according to the user's interaction.
File: updatequicksettings.js:
var service = Ti.Android.currentService;
service.addEventListener('click', function () {
if (service.getState() == Ti.Android.TILE_STATE_ACTIVE) {
service.setState(Ti.Android.TILE_STATE_INACTIVE);
service.setLabel('Inactive');
service.setIcon('inactive.png');
} else {
service.setState(Ti.Android.TILE_STATE_ACTIVE);
service.setLabel('Active');
service.setIcon('active.png');
}
service.updateTile();
}Register the service in tiapp.xml:
<ti:app>
<android xmlns:android="http://schemas.android.com/apk/res/android">
<services>
<service url="updatequicksettings.js" type="quicksettings" label="Active" icon="active.png"/>
</services>
</android>
</ti:app>Properties 8
Inherited from Titanium.Proxy
The name of the API that this proxy corresponds to.
Inherited from Titanium.Proxy
Indicates if the proxy will bubble an event to its parent.
Default: true
Changes the Tile's icon.
If no image is passed as Tile icon it will use the Application's one.
Inherited from Titanium.Android.Service
The intent used to start or bind to the Service.
The Tile's label.
If no label is set the Tile uses the Application name.
Inherited from Titanium.Proxy
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
Inherited from Titanium.Android.Service
A service can be started more than once -- this number (based on an incrementing integer) indicates which "start number" in the sequence the current service instance is.
Sets the state of the Tile.
State can be one of the following: TILE_STATE_UNAVAILABLE, TILE_STATE_INACTIVE, TILE_STATE_ACTIVE
Methods 20
Inherited from Titanium.Proxy
Adds the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. 4 fields
|
applyProperties
since 3.0.0Inherited from Titanium.Proxy
Applies the properties to the proxy.
| Parameters | Type | Description |
|---|---|---|
| props | Dictionary | A dictionary of properties to apply. |
Inherited from Titanium.Proxy
Fires a synthesized event to any registered listeners.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| event? | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. |
foregroundCancel
since 7.3.0Inherited from Titanium.Android.Service
Puts the service into the "background" state and removes its foreground notification.
foregroundNotify
since 7.3.0Inherited from Titanium.Android.Service
Puts the service into the "foreground" state and displays a notification.
| Parameters | Type | Description |
|---|---|---|
| id | Number | Unique integer ID to be assigned to the notification. Cannot be zero. |
| notification | Titanium.Android.Notification | Notification to display in the status bar. Cannot be null. |
| foregroundServiceType? | Number | Notification service type specified by <Titanium.Android.FOREGROUND_SERVICE_TYPE_*>. |
getIcon
deprecatedDeprecated since 10.0.0
Please use the icon property to get/set the value.
Returns the Tile's current icon.
getLabel
deprecatedDeprecated since 10.0.0
Please use the label property to get/set the value.
Returns the Tile's current label.
getState
deprecatedDeprecated since 10.0.0
Please use the state property to get/set the value.
Returns the Tile's current state.
Returns 'true' if the device is currently locked, 'false' otherwise.
Returns 'true' if the device is in secure state, 'false' otherwise.
Inherited from Titanium.Proxy
Removes the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to 4 fields
|
setIcon
deprecatedDeprecated since 10.0.0
Please use the icon property to get/set the value.
Changes the Tile's icon.
If no image is passed as Tile icon it will use the Application's one.
| Parameters | Type | Description |
|---|---|---|
| icon | String | Titanium.Blob | Titanium.Filesystem.File | Source of the icon image |
setLabel
deprecatedDeprecated since 10.0.0
Please use the label property to get/set the value.
Changes the Tile's label.
If no label is set the Tile uses the Application name.
| Parameters | Type | Description |
|---|---|---|
| label | String | String to be used. |
setState
deprecatedDeprecated since 10.0.0
Please use the state property to get/set the value.
Sets the state of the Tile.
State can be one of the following: TILE_STATE_UNAVAILABLE, TILE_STATE_INACTIVE, TILE_STATE_ACTIVE
| Parameters | Type | Description |
|---|---|---|
| state | Number | State to be set. |
Opens an Alert dialog.
Creates and shows a default Alert dialog with the provided options dictionary.
Note: Alert dialog only supports one of the following: message/options.
If you pass both - only message will be shown.
| Parameters | Type | Description |
|---|---|---|
| options | showParams | Dictionary containing the options for the dialog. |
Inherited from Titanium.Android.Service
Starts the Service.
Colapses the quick settings menu and starts an activity for the passed Intent.
| Parameters | Type | Description |
|---|---|---|
| intent | Titanium.Android.Intent | Intent to be fired. |
Inherited from Titanium.Android.Service
Stops this running instance of the Service.
Prompts the user to unlock the device and runs the JS code.
| Parameters | Type | Description |
|---|---|---|
| jsCode | String | JavaScript code to be evaluated. |
Applies current tile's properties.
Updates the Tile's with it's current label, icon and state.
Events 14
Inherited from Titanium.Android.Service
For Javascript-based services that you create, pause fires after each time the JavaScript
code executes.
| Event properties | Type | Description |
|---|---|---|
| iteration | Number | Incrementing integer indicating which iteration of an interval-based Service is pausing. For example, if you have an interval-based Service running every 10 seconds, iteration 3 would occur at about 30 seconds after you start the instance (assuming your service code runs quickly). |
Inherited from Titanium.Android.Service
For JavaScript-based Services which you create, resume fires each time the JavaScript
code executes.
| Event properties | Type | Description |
|---|---|---|
| iteration | Number | Incrementing integer indicating which iteration of an interval-based Service is pausing. For example, if you have an interval-based Service running every 10 seconds, iteration 3 would occur at about 30 seconds after you start the instance (assuming your service code runs quickly). |
Inherited from Titanium.Android.Service
Fired when the bound service instance starts.
Tile is listening for events.
Dispatched whenever the user has opened the quick setting menu and the Tile is added in there.
Inherited from Titanium.Android.Service
Fired when the bound service instance stops.
Tile has stopped listening for events.
Dispatched whenever the user has collapsed the quick setting menu and the Tile is not visible.
Inherited from Titanium.Android.Service
Fired when the task that comes from the service's application has been removed.
The Tile has been added in the quick menu.
Dispatched wheneved the user has moved the Tile for this service in the quick settings menu.
Dispatched when the alert dialog has been cancelled.
Dispatched when the negative (index 2) button has been clicked.
Dispatched when the neutral (index 1) button has been clicked.
An item from the signle choice menu has been selected.
| Event properties | Type | Description |
|---|---|---|
| itemIndex | Number | Index of the selected item from the single choice menu in the dialog. |
Dispatched when the positive (index 0) button has been clicked.
The Tile has been removed from the quick menu.
Dispatched wheneved the user has removed the Tile for this service from the quick settings menu.