Titanium.Android.QuickSettingsService

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 settings 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.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,

Properties #

apiName#

extended

Type: 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, Button
returns Ti.UI.Button.

bubbleParent#

extended

Type: 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.

icon#

Type: 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.

intent#

extended

Type: Titanium.Android.Intent

The intent used to start or bind to the Service.

label#

Type: String

The Tile's label.

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

lifecycleContainer#

extended

Type: Titanium.UI.Window, Titanium.UI.TabGroup

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#

extended

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

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

extended

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

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name of the event.	No
`callback`	`Callback<Titanium.Event>`	Callback function to invoke when the event is fired.	No

applyProperties #

extended

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	Summary	Optional
`props`	`Dictionary`	A dictionary of properties to apply.	No

fireEvent #

extended

Fires a synthesized event to any registered listeners.

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name of the event.	No
`event`	`Dictionary`	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.	Yes

foregroundCancel #

extended

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.

foregroundNotify #

extended

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	Summary	Optional
`id`	`Number`	Unique integer ID to be assigned to the notification. Cannot be zero.	No
`notification`	`Titanium.Android.Notification`	Notification to display in the status bar. Cannot be null.	No
`foregroundServiceType`	`Number`	Notification service type specified by <Titanium.Android.FOREGROUND_SERVICE_TYPE_*>.	Yes

getIcon #

Returns the Tile's current icon.

Returns: String, Titanium.Blob, Titanium.Filesystem.File

getLabel #

Returns the Tile's current label.

Returns: String

getState #

Returns the Tile's current state.

Returns: Number

isLocked #

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

Returns: Boolean

isSecure #

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

Returns: Boolean

removeEventListener #

extended

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	Summary	Optional
`name`	`String`	Name of the event.	No
`callback`	`Callback<Titanium.Event>`	Callback function to remove. Must be the same function passed to `addEventListener`.	No

setIcon #

Changes the Tile's icon.

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

Parameters:

Name	Type	Summary	Optional
`icon`	`String, Titanium.Blob, Titanium.Filesystem.File`	Source of the icon image	No

setLabel #

Changes the Tile's label.

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

Parameters:

Name	Type	Summary	Optional
`label`	`String`	String to be used.	No

setState #

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	Summary	Optional
`state`	`Number`	State to be set.	No

showDialog #

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	Summary	Optional
`options`	`showParams`	Dictionary containing the options for the dialog.	No

start #

extended

Starts the Service.

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

startActivityAndCollapse #

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

Parameters:

Name	Type	Summary	Optional
`intent`	`Titanium.Android.Intent`	Intent to be fired.	No

stop #

extended

Stops this running instance of the Service.

unlockAndRun #

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

Parameters:

Name	Type	Summary	Optional
`jsCode`	`String`	JavaScript code to be evaluated.	No

updateTile #

Applies current tile's properties.

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

Events #

pause #

extended

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.

Event Properties:

Name	Type	Summary
`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).

resume #

extended

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.

Event Properties:

Name	Type	Summary
`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).

start #

extended

Fired when the bound service instance starts.

Bound service instances are created via Titanium.Android.createService.

startlistening #

Tile is listening for events.

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

stop #

extended

Fired when the bound service instance stops.

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

stoplistening #

Tile has stopped listening for events.

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

taskremoved #

extended

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, e.g. the user swipes the application away from
the recent applications list. It only works for unbound service which is
started using Titanium.Android.startService.

tileadded #

The Tile has been added in the quick menu.

Dispatched whenever the user has moved the Tile for this service in the quick settings menu.

tiledialogcancelled #

Dispatched when the alert dialog has been cancelled.

tiledialognegative #

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

tiledialogneutral #

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

tiledialogoptionselected #

An item from the single choice menu has been selected.

Event Properties:

Name	Type	Summary
`itemIndex`	`Number`	Index of the selected item from the single choice menu in the dialog.

tiledialogpositive #

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

tileremoved #

The Tile has been removed from the quick menu.

Dispatched whenever the user has removed the Tile for this service from the quick settings menu.

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();
}

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

Notificationchannels

Launchoptionstype

Notificationparams

Usernotificationattachment

Usernotificationsettings

Mediascannerresponse

Clipboarditemstype

Systemimageparameters

Titanium.Android.QuickSettingsService ​

Properties #

apiName#

bubbleParent#

icon#

intent#

label#

lifecycleContainer#

serviceInstanceId#

state#

Methods #

addEventListener #

applyProperties #

fireEvent #

foregroundCancel #

foregroundNotify #

getIcon #

getLabel #

getState #

isLocked #

isSecure #

removeEventListener #

setIcon #

setLabel #

setState #

showDialog #

start #

startActivityAndCollapse #

stop #

unlockAndRun #

updateTile #

Events #

pause #

resume #

start #

startlistening #

Titanium.Android.QuickSettingsService