# Titanium.Android.QuickSettingsService

Android service for creating custom quick settings tiles and handling user's interaction with them.

Availability
7.0

# Overview

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:

  1. 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.
  2. Register the service in your tiapp.xml file. 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

# apiName READONLY

Availability
7.0
apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.


# bubbleParent

Availability
7.0
bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true


# icon

Availability
10.0.0

Changes the Tile's icon.

If no image is passed as Tile icon it will use the Application's one.


# intent READONLY

Availability
7.0

The intent used to start or bind to the Service.


# label

Availability
10.0.0
label :String

The Tile's label.

If no label is set the Tile uses the Application name.


# lifecycleContainer

Availability
7.0

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.


# serviceInstanceId READONLY

Availability
7.0
serviceInstanceId :Number

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.


# state

Availability
10.0.0
state :Number

Sets the state of the Tile.

State can be one of the following: TILE_STATE_UNAVAILABLE, TILE_STATE_INACTIVE, TILE_STATE_ACTIVE

# Methods

# addEventListener

Availability
7.0
addEventListener(name, callback) void

Adds the specified callback as an event listener for the named event.

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# applyProperties

Availability
7.0
applyProperties(props) void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# fireEvent

Availability
7.0
fireEvent(name[, event]) void

Fires a synthesized event to any registered listeners.

Parameters

Name 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.

Returns

Type
void

# foregroundCancel

Availability
7.3.0
foregroundCancel() void

Puts the service into the "background" state and removes its foreground notification.

If you call the foregroundNotify method to put the service into the "foreground" state, then you call this method to put the service back into the "background" state. This will also automatically remove the foreground service's notification that was put into the status bar.

Note that stopping a foreground service will remove its foreground notification from the status bar as well. So, you do not have to call this method to remove it. This method is only intended to be used by services that need to dynamically change states.

Returns

Type
void

# foregroundNotify

Availability
7.3.0
foregroundNotify(id, notification[, foregroundServiceType]) void

Puts the service into the "foreground" state and displays a notification.

Calling this method will change the service from the "background" state (the default) to the "foreground" state. It will also post a notification to the status bar to notify the end-user that the app is doing work, even while backgrounded. This feature is typically used by apps that play music, monitor current location, or perform large downloads while the app is in the background.

Note that a foreground service is far less likely to be terminated by the operating system while the app is in the background. A foreground service is also needed if the app needs to acquire location data since Android 8.0 and higher throttles location acquisition while the app is in the background.

See Android 8.0 "Background Execution Limits":

  • https://developer.android.com/about/versions/oreo/background

You can call this method before or after the service has been started. If you need to change the displayed notification, then you can call this method again with the same notification ID and with an updated [notification]Titanium.Android.Notification object.

The notification will be automatically removed from the status bar when the service has been stopped or if you call the foregroundCancel method.

This method will fail on Android 9.0 and above unless you set the following Android manifest permission in your "tiapp.xml" file.

<ti:app>
    <android xmlns:android="http://schemas.android.com/apk/res/android">
        <manifest>
            <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
        </manifest>
    </android>
</ti:app>

Parameters

Name 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_*>.

Returns

Type
void

# getIcon DEPRECATED

Availability
7.0
getIcon() String | Titanium.Blob | Titanium.Filesystem.File

DEPRECATED SINCE 10.0.0

Please use the icon property to get/set the value.

Returns the Tile's current icon.

Returns


# getLabel DEPRECATED

Availability
7.0
getLabel() String

DEPRECATED SINCE 10.0.0

Please use the label property to get/set the value.

Returns the Tile's current label.

Returns

Type
String

# getState DEPRECATED

Availability
7.0
getState() Number

DEPRECATED SINCE 10.0.0

Please use the state property to get/set the value.

Returns the Tile's current state.

Returns

Type
Number

# isLocked

Availability
7.0
isLocked() Boolean

Returns 'true' if the device is currently locked, 'false' otherwise.

Returns

Type
Boolean

# isSecure

Availability
7.0
isSecure() Boolean

Returns 'true' if the device is in secure state, 'false' otherwise.

Returns

Type
Boolean

# removeEventListener

Availability
7.0
removeEventListener(name, callback) void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

# setIcon DEPRECATED

Availability
7.0
setIcon(icon) void

DEPRECATED 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

Name Type Description
icon String | Titanium.Blob | Titanium.Filesystem.File

Source of the icon image

Returns

Type
void

# setLabel DEPRECATED

Availability
7.0
setLabel(label) void

DEPRECATED 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

Name Type Description
label String

String to be used.

Returns

Type
void

# setState DEPRECATED

Availability
7.0
setState(state) void

DEPRECATED 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

Name Type Description
state Number

State to be set.

Returns

Type
void

# showDialog

Availability
7.0
showDialog(options) void

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

Name Type Description
options showParams

Dictionary containing the options for the dialog.

Returns

Type
void

# start

Availability
7.0
start() void

Starts the Service.

Effective only if this instance of Titanium.Android.Service was created with createService.

Returns

Type
void

# startActivityAndCollapse

Availability
7.0
startActivityAndCollapse(intent) void

Colapses the quick settings menu and starts an activity for the passed Intent.

Parameters

Name Type Description
intent Titanium.Android.Intent

Intent to be fired.

Returns

Type
void

# stop

Availability
7.0
stop() void

Stops this running instance of the Service.

Returns

Type
void

# unlockAndRun

Availability
7.0
unlockAndRun(jsCode) void

Prompts the user to unlock the device and runs the JS code.

Parameters

Name Type Description
jsCode String

JavaScript code to be evaluated.

Returns

Type
void

# updateTile

Availability
7.0
updateTile() void

Applies current tile's properties.

Updates the Tile's with it's current label, icon and state.

Returns

Type
void

# Events

# pause

Availability
7.0

For Javascript-based services that you create, pause fires after each time the JavaScript code executes.

The resume and pause events occur in pairs, with resume firing just before your JavaScript service code executes, and pause just after.

Properties

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

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.


# resume

Availability
7.0

For JavaScript-based Services which you create, resume fires each time the JavaScript code executes.

For example, if your Service runs on an interval of 10000 (10 seconds), you would expect to see resume fired every 10 seconds, just as the JavaScript service code you wrote is about to execute.

Properties

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

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.


# start

Availability
7.0

Fired when the bound service instance starts.

Bound service instances are created via createService.


# stop

Availability
7.0

Fired when the bound service instance stops.

The service stops when stop or stopService is called and there are no more bound, un-stopped clients.


# taskremoved

Availability
7.0

Fired when the task that comes from the service's application has been removed.

This event is fired if the service is currently running and the user has removed a task that comes from the service's application, eg. the user swipes the application away from the recent applications list. It only works for unbound service which is started using startService.


# startlistening

Availability
7.0

Tile is listening for events.

Dispatched whenever the user has opened the quick setting menu and the Tile is added in there.


# stoplistening

Availability
7.0

Tile has stopped listening for events.

Dispatched whenever the user has collapsed the quick setting menu and the Tile is not visible.


# tileadded

Availability
7.0

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.


# tileremoved

Availability
7.0

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.


# tiledialogoptionselected

Availability
7.0

An item from the signle choice menu has been selected.

Properties

Name Type Description
itemIndex Number

Index of the selected item from the single choice menu in the dialog.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.


# tiledialogcancelled

Availability
7.0

Dispatched when the alert dialog has been cancelled.


# tiledialogpositive

Availability
7.0

Dispatched when the positive (index 0) button has been clicked.


# tiledialogneutral

Availability
7.0

Dispatched when the neutral (index 1) button has been clicked.


# tiledialognegative

Availability
7.0

Dispatched when the negative (index 2) button has been clicked.