This documentation relates to previous versions of Titanium.

To see the latest documentation, visit docs.appcelerator.com.

This space has been migrated to https://techweb.axway.com/confluence/display/dr and will be removed from the Appcelerator wiki on August 9th, 2018

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Reverted from v. 15
Table of Contents
printablefalse
maxLevel4
minLevel3
classtutTOC
excludeGoal.*|Resources.*|Steps.*

Objective

In this section, you will examine some of the user interface and user experience components that are specific to Android. In addition, we'll see how these can be leveraged in a cross platform manner via the Titanium API.

...

Android devices have a hardware or software button that is used to display a menu of options. In native Android, every Activity can have an associated menu. In Titanium, every "heavyweight" window can have its own menu, as all heavyweight windows having a corresponding Android Activity. Because of the menu's association with the underlying Activity, it is created in a special Android-specific Activity event called onCreateOptionsMenu. Below we see how a basic Android menu is declared using Titanium.

Code Block
langjavascript

// Associated directly with an activity
activity = Ti.Android.currentActivity;
activity.onCreateOptionsMenu = function(e) {
    var menu = e.menu;
    var menuItem = menu.add({ title: "Item 1" });
    menuItem.setIcon("item1.png");
    menuItem.addEventListener("click", function(e) {
        // do something when the menu item is tapped
    });
};

// or with your heavyweight window, set here with navBarHidden
var win = Titanium.UI.createWindow({
	navBarHidden: false,
	activity : {
		onCreateOptionsMenu : function(e) {
			var menu = e.menu;
			var menuItem = menu.add({ title : 'Item 1' });
			menuItem.setIcon("item1.png");
			menuItem.addEventListener('click', function(e) {
				// do something when the menu item is tapped
			});
		}
	}

...

As with the Menu button, the Android Back button is associated with Activities or heavyweight windows. Users expect when they tap the Back button, that they'll "page back" through the stack of open windows. In addition, users will often use the Back button to exit or pause your app. For this reason, you may find it beneficial to handle presses of the Back button to clean up your app and the resources it may be utilizing.

Code Block
langjavascript

// must be a heavyweight window to capture the android:back event
// so set something like fullscreen:false
var win = Ti.UI.createWindow({
	title:'Hello world',
	backgroundColor:'#fff',
	fullscreen:false
});
win.addEventListener('android:back',function() {
	// do something
});

...

Titanium Labels have the ability to use inline HTML, as well as embedded links, on Android. You can include simple formatting HTML within a label and Android will render it properly. To do so, you use the html property rather than the text property. This is pretty handy for cross-platform apps so that you can provide platform-specific label text.

Code Block
langjavascript

var label = Ti.UI.createLabel({
	html: 'Testing <b>bold</b> <i>italic</i> text',
	text: 'This is for iOS',
	top:125,
	height:50,
	width:'100%'
});

Android also will "linkify" text within your labels. Given the following, the user could tap on the email address to open their mail client; tap the phone number to open the dialer; tap the URL to open their browser; or tap the address to open Maps.

Code Block
langjavascript

var lbl = Ti.UI.createLabel({
	autoLink : Ti.UI.Android.LINKIFY_ALL,
	left : 5, top : 5, right : 5, height : 100,
	backgroundColor : '#222',
	text : 'Contact\n test@test.com\n 817-555-5555\n http://bit.ly\n 440 Bernardo Ave, Mountain View, CA'
});

...

Android enables simple "toast" style notifications. These are short messages that briefly float over all other content in your app, disappearing a short time later. You can create such notifications in Titanium by using the Ti.UI.createNotification() method as shown here:

Code Block
langjavascript

var n = Ti.UI.createNotification({message:"Howdy folks"});
n.duration = Ti.UI.NOTIFICATION_DURATION_LONG;
// Also valid is NOTIFICATION_DURATION_SHORT

// Optionally, set the X & Y Offsets, by default
n.offsetX = 100;
n.offsetY = 75;
// display the toast message
n.show();

...

The Android status bar provides a central location for application and system notifications. Titanium enables you to post messages to the Status bar (sometimes referred to as the Notification bar) via the Titanium.Android.Notification module. To do so, you'll need to explore the Android-specific world of Intents, PendingIntents, and Activities. We won't go deep into those concepts in this guide, but here's a taste of what can be done:

Code Block
langjavascript

// Need an Intent to define what will happen when user taps the notification message
// In this case, it will open the Dialer ready to dial a fictitious number
var intent = Ti.Android.createIntent({
	action: Ti.Android.ACTION_DIAL,
    data: "tel:8175551212"
});
// Create a PendingIntent to tie together the Activity and Intent
var pending = Titanium.Android.createPendingIntent({
    activity: Titanium.Android.currentActivity,
    intent: intent,
    type: Titanium.Android.PENDING_INTENT_FOR_ACTIVITY,
    flags: Titanium.Android.FLAG_UPDATE_CURRENT
});
// Here's the notification now
var notification = Titanium.Android.createNotification({
        icon: 0x7f020000,
        contentTitle: 'Dial Now!',
		contentText : '817-555-1212',
        contentIntent: pending
});
// Send the Notification to the manager, the digit is an ID you could use to later cancel the notification
Titanium.Android.NotificationManager.notify(1, notification);

Nine-Patch Images

A nine-patch image is a PNG image with regions specified as stretchable or not stretchable.  For example, if you have an image with a logo centered against a solid background, you can create a nine-patch image with the area around the logo as stretchable.  If the image needs to be stretched for a larger device, the solid background color will be stretched, leaving the logo untouched.  Nine-patch images are a good solution to support Android devices with different screen sizes and densities.

To create a nine-patch image, you can either use the Android NDK draw9patch tool or a graphics editor.  If you are using a graphics editor, create a one-pixel transparent or white border around your PNG image, then change the top and left border to black pixels where you want the image to stretch.  You can optionally change the right and bottom border to black pixels to indicate extra padding areas.  For more information, refer to the Android Draw 9-Patch help tutorial for directions on using the draw9patch tool or refer to the Android nine-patch image specification for information on creating a nine-patch image in a graphics editor.

Name the file with the extension .9.png, for example, Resources/images/myimage.9.png.

To use a nine-patch image, reference the image in your code like you would a regular image without the .9 part of the extension, for example:

Code Block
var button = Ti.UI.createButton({
    backgroundImage: '/images/myimage.png'
});

Nine-patch images only work as background images. For example, you can use a nine-patch image to set an ImageView's backgroundImage property but not the image property.

The project should be cleaned to ensure that the files are correctly copied to the project.

You may also use a nine-patch image for a splash screen.  For more information, refer to Icons and Splash Screens.

Hands-on Practice

Goal

In this activity, you will manage the hardware Back button so that the first time it's tapped, a full-screen view will be closed and after that your app will be closed.

...