# Titanium.Android.QuickSettingsService

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

Availability

7.0

Extends

Titanium.Android.Service

# 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:

• Android Quick Settings Tile API (opens new window)

# 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

# icon

Availability

10.0.0

icon :String | Titanium.Blob | Titanium.Filesystem.File

Changes the Tile's icon.

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

---

# label

Availability

10.0.0

label :String

The Tile's label.

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

---

# 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

This API can be assigned the following constants:

• Titanium.Android.TILE_STATE_UNAVAILABLE
• Titanium.Android.TILE_STATE_INACTIVE
• Titanium.Android.TILE_STATE_ACTIVE

# Methods

# 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

Type

String | Titanium.Blob | Titanium.Filesystem.File

---

# 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

---

# 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

---

# 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

---

# 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

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