Titanium SDK

# Titanium.Android.RemoteViews

The Titanium binding of Android RemoteViews.

Availability
1.6
Extends
Titanium.Proxy

# Overview

RemoteViews is an API for referencing and updating a remote view hierarchy that lives in another process, for example, in a Titanium.Android.Notification.

To create a remote view hierarchy, you must define an Android XML layout for the views you want to display, and place the XML file in the platform/android/res/layout inside your project folder. See the examples for a sample XML layout and sample code for creating a remote view.

To use a remote view hierarchy in a notification, see Titanium.Android.Notification.contentView.

Because the remote view hierarchy belongs to another process, you cannot call methods on it directly, but you can call methods on the RemoteViews object to update views in the heirarchy by ID. To reference a view inside the layout, use the Titanium.App.Android.R object to reference the view's ID. For example, if you have a view with the ID notify_imageview, you can refer to it using:

Ti.App.Android.R.id.notify_imageview

See also:

# Examples

# Create a Remote View

The following code excerpt creates a RemoteViews object based on a custom layout called custom_layout.xml, and set a label's text.

var AppR = Ti.App.Android.R;
var customLayout = Ti.Android.createRemoteViews({ layoutId: AppR.layout.custom_layout });
customLayout.setTextViewText(AppR.id.custom_text, "Click Me!");

This example uses a simple custom layout:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="fill_parent" 
        android:layout_height="fill_parent" 
        android:orientation="vertical" >
    <TextView android:id="@+id/custom_text"
            android:layout_width="fill_parent"
            android:layout_height="fill_parent"
            android:background="#ffffff"
            android:textColor="#aaff0000"
            android:textStyle="italic"
            android:gravity="center"
            android:text="Hello, I am a TextView" />
</LinearLayout>

The layout file for this example must be placed in platform/android/res/layout/custom_layout.xml.

# Properties

# apiName READONLY

Availability
3.2.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
3.0.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

# layoutId CREATION ONLY

Availability
1.6
layoutId :Number

Android layout resource ID for the view to display. Required.

To define a custom layout resource in your application, the XML layout file should be placed in platform/android/res/layout folder inside your project folder.

Use R to reference the ID of the layout.

# lifecycleContainer

Availability
3.6.0
lifecycleContainer :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.

# packageName CREATION ONLY

Availability
1.6
packageName :String

Package name that the resource ID lives in. Optional.

# Methods

# addEventListener

Availability
1.6
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
3.0.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
1.6
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

# removeEventListener

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

# setBoolean

Availability
1.6
setBoolean(viewId, methodName, value) → void

Calls a method taking a single boolean argument on a view in the remote view hierarchy. See Android's documentation for [setBoolean](https://developer.android.com/reference/android/widget/RemoteViews.html#setBoolean(int, java.lang.String, boolean)).

Parameters

Name Type Description
viewId Number

Resource ID of the view to invoke the method on. Application-specific resource IDs can be specified using R.

methodName String

Name of the method to call.

value Boolean

Value to pass to the method.

Returns

Type
void

# setChronometer

Availability
1.6
setChronometer(viewId, base, format, started) → void

Sets the base time, format string, and started flag for a chronometer in the remote view hierarchy.

See Android's documentation for [setChronometer](https://developer.android.com/reference/android/widget/RemoteViews.html#setChronometer(int, long, java.lang.String, boolean)).

Parameters

Name Type Description
viewId Number

Resource ID of the Chronometer to update. Application-specific resource IDs can be specified using R.

base Date

Time at which the timer would have read 0:00.

format String

Chronometer format string, or null to simply display the timer value.

started Boolean

True if you want the clock to be started, false if not.

Returns

Type
void

# setDouble

Availability
1.6
setDouble(viewId, methodName, value) → void

Calls a method taking a single double argument on a view in the remote view hierarchy.

See Android's documentation for [setDouble](https://developer.android.com/reference/android/widget/RemoteViews.html#setDouble(int, java.lang.String, double)).

Parameters

Name Type Description
viewId Number

Resource ID of the view to update. Application-specific resource IDs can be specified using R.

methodName String

Name of the method to call.

value Number

Value to pass to the method.

Returns

Type
void

# setImageViewResource

Availability
1.6
setImageViewResource(viewId, srcId) → void

Sets the image for an image view in the remote view hierarchy using an Android drawable resource.

See Android's documentation for [setImageViewResource](https://developer.android.com/reference/android/widget/RemoteViews.html#setImageViewResource(int, int)).

Parameters

Name Type Description
viewId Number

Resource ID of the ImageView to update. Application-specific resource IDs can be specified using R.

srcId Number

Resource ID of the new image. Application-specific resource IDs can be specified using R.

Returns

Type
void

# setImageViewUri

Availability
1.6
setImageViewUri(viewId, uri) → void

Sets the image for an image view in the remote view hierarchy using a URI.

This method supports supports both Android and Titanium URLs.

See Android's documentation for [setImageViewUri](https://developer.android.com/reference/android/widget/RemoteViews.html#setImageViewUri(int, android.net.Uri)).

Parameters

Name Type Description
viewId Number

Resource ID of the ImageView to update. Application-specific resource IDs can be specified using R.

uri String

URI of the image (both Android and Titanium URLs are supported).

Returns

Type
void

# setInt

Availability
1.6
setInt(viewId, methodName, value) → void

Calls a method taking a single int argument on a view in the remote view hierarchy.

See Android's documentation for [setInt](https://developer.android.com/reference/android/widget/RemoteViews.html#setInt(int, java.lang.String, int))

Parameters

Name Type Description
viewId Number

Resource ID of the view to update. Application-specific resource IDs can be specified using R.

methodName String

Name of the method to call.

value Number

Value to pass to the method.

Returns

Type
void

# setOnClickPendingIntent

Availability
1.6
setOnClickPendingIntent(viewId, pendingIntent) → void

Launches a Titanium.Android.PendingIntent when the specified view is clicked.

See Android's documentation for [setOnClickPendingIntent](https://developer.android.com/reference/android/widget/RemoteViews.html#setOnClickPendingIntent(int, android.app.PendingIntent)).

Parameters

Name Type Description
viewId Number

Resource ID of the view to add a click listener to. Application-specific resource IDs can be specified using R.

pendingIntent Titanium.Android.PendingIntent

The PendingIntent to execute when this view is clicked.

Returns

Type
void

# setProgressBar

Availability
1.6
setProgressBar(viewId, max, progress, indeterminate) → void

Sets the progress, max value, and indeterminate flag of a progress bar in the remote view hierarchy.

See Android's documentation for [setProgressBar](https://developer.android.com/reference/android/widget/RemoteViews.html#setProgressBar(int, int, int, boolean)).

Parameters

Name Type Description
viewId Number

Resource ID of the progress bar to update. Application-specific resource IDs can be specified using R.

max Number

The new maximum value of the progress bar.

progress Number

The new progress value of the progress bar (from 0..max).

indeterminate Boolean

Determines whether the progress bar is indeterminate. If true, the progress bar displays an infinite looping animation.

Returns

Type
void

# setString

Availability
1.6
setString(viewId, methodName, value) → void

Calls a method taking a single String argument on a view in the remote view hierarchy.

See Android's documentation for [setString](https://developer.android.com/reference/android/widget/RemoteViews.html#setString(int, java.lang.String, java.lang.String)).

Parameters

Name Type Description
viewId Number

Resource ID of the view to update. Application-specific resource IDs can be specified using R.

methodName String

Name of the method to call.

value String

String to pass to the method.

Returns

Type
void

# setTextColor

Availability
1.6
setTextColor(viewId, color) → void

Sets the text color of a view in the remote view hierarchy.

See Android's documentation for [setTextColor](https://developer.android.com/reference/android/widget/RemoteViews.html#setTextColor(int, int)).

Parameters

Name Type Description
viewId Number

Resource ID of the view to update. Application-specific resource IDs can be specified using R.

color Number

Color as an integer.

Returns

Type
void

# setTextViewText

Availability
1.6
setTextViewText(viewId, text) → void

Sets the text of a text view in the remote view hierarchy.

See Android's documentation for [setTextViewText](https://developer.android.com/reference/android/widget/RemoteViews.html#setTextViewText(int, java.lang.CharSequence)).

Parameters

Name Type Description
viewId Number

Resource ID of the text view to update. Application-specific resource IDs can be specified using R.

text String

New text for the text view.

Returns

Type
void

# setUri

Availability
1.6
setUri(viewId, methodName, value) → void

Calls a method taking one URI on a view in the remote view hierarchy.

See Android's documentation for [setUri](https://developer.android.com/reference/android/widget/RemoteViews.html#setUri(int, java.lang.String, android.net.Uri)).

Parameters

Name Type Description
viewId Number

Resource ID of the view to update. Application-specific resource IDs can be specified using R.

methodName String

Name of the method to call.

value String

URI (as a string) to pass to the method.

Returns

Type
void

# setViewVisibility

Availability
1.6
setViewVisibility(viewId, visibility) → void

Sets the visibility of a view in the remote view hierarchy.

See Android's documentation for [setViewVisibility](https://developer.android.com/reference/android/widget/RemoteViews.html#setViewVisibility(int, int))

Parameters

Name Type Description
viewId Number

Resource ID of the view to show or hide. Application-specific resource IDs can be specified using R.

visibility Number

The visibility. Either 0 (VISIBLE), 4 (INVISIBLE) or 8 (GONE).

Returns

Type
void

Contents