Chapter 2. How to Make an Interface

We achieved a lot in the last chapter. Not only did we install Titanium and the emulators but we also created an app! Now that everything is set up we can start to explore the tools that are available to make cross-platform apps.

This chapter will explore the tools that are available in Titanium for building great, engaging, native cross-platform apps. By the end of the chapter we will have moved far beyond our first app by coding windows, views, buttons, and table views, and establishing principles that can be applied to the other controls in the toolkit. We will also touch on how to handle events triggered by the user, which will provide an insight into some of the techniques that we will cover in more detail in Chapter 4, Gluing Your App Together with Events, Variables, and Callbacks.

Expect to read about the following:

Windows
Views
Table views
Navigation groups and tabs
Labels and buttons
Debugging
Android menus
iOS style buttons

Tip

Downloading the example...

What's in the toolkit?

Broadly speaking you can split the tools in the Titanium SDK into three categories; tools for laying out information on the screen, tools for getting user input, and tools for showing information. Some tools cross these boundaries and lie outside them, but the following list shows the core tools that you will use most of the time:

A recap

Before we move on to other tools in the toolkit let's take a moment to examine and understand the code that was generated for us in the last chapter. Even though the app was small, it included several key elements that will be used by most apps.

We will now cover the core items in the app. First and most importantly, the window.

Window

A window, or as it is named in the code, Titanium.UI.Window, is the canvas on which all other elements are attached. Without a window there can be no sliders, no buttons, nothing. All app elements are attached (or to use the Titanium terminology, added) to a window using the add command. An app requires at least one window to function and that window must be called from within the app.js file. The following code sample shows how a label is created and added to a window.

var win1 = Titanium.UI.createWindow({  
    title:'Tab 1',
    backgroundColor:'#fff'
});
var label1 = Titanium.UI.createLabel({
    color:'#999',
    text:'I am Window 1',
    font:{fontSize:20,fontFamily:'Helvetica Neue'},
    textAlign:'center',
    width:'auto'
});

win1.add(label1);

Note

A reference to Titanium.UI.createWindow is the same as Ti.UI.createWindow. Ti is a useful shortcut that is built into Titanium that will be used throughout the book.

In the app created in the last chapter there are two windows, one...

Tab group and tabs

A tab group is a container for a group of tabs. It is displayed at the top of the screen on Android and the bottom on iOS, and allows the user to move between different screens on your app.

Tab groups are very well integrated and well suited to iOS apps and in particular iPhone apps, where they are commonly found on lots of apps; but it doesn't always look good on Android. As is shown in the next image, a tab group on a low resolution Android device takes up a lot of valuable screen estate. Think carefully about how your app will look on Android before committing to creating your app with it.

Note

Tab groups may be on the way out in Android. Titanium 3.0 now creates Android action bars instead of tab groups if you set the Android SDK to higher than 11 in tiapp.xml. See http://developer.appcelerator.com/blog/2012/12/breaking-changes-in-titanium-sdk-3-0.html.

Creating a tab group

Tab groups are created by calling Titanium.UI.createTabGroup() . Tabs are added to tab groups. A...

Labels

Labels are used to display text. Here is an example call to create a label.

var label1 = Titanium.UI.createLabel({
    color:'#999',
    text:'I am Window 1',
    font:{fontSize:20,fontFamily:'Helvetica Neue'},
    textAlign:'center',
    width:Ti.UI.FILL,
});

The properties are explained in the following table:

Attribute	Description
`color`	The color of the label text. This can be specified as a predefined color name (`'green'`) or hex triplet; for example, `'#FFF'` refers to white and `'#999'` refers to light gray.
`text`	The text to display.
`font`	The font properties. Note that the font properties are specified in JSON format. Even if you are only defining the `fontName` property, it should still be JSON formatted otherwise it will be ignored. JSON is discussed in Chapter 3, How to Design Titanium Apps. Properties that can be specified are: `fontFamily` `fontSize` `fontStyle` `fontWeight`
`textAlign`	The justification of the text within the defined size of the label.
`width...`

Views

Views are an empty drawing surface onto which other items are added. They are the building blocks of a layout. Their beauty is that they allow you to format a section of the screen within the view without having to worry about the other parts of the screen.

Note

What's the difference between a view and a table view?

A table view is used to lay out a vertical list of information such as a list of countries. A view is a container of objects. They are used to help lay out other objects. For example, you could use a view to make a horizontal row of buttons. Views are best thought of as a way to lay out an area of the screen.

Before I attempt to explain how views are used we should add one to the app.

Time for action – adding a view to a window

In the app.js file add the following code that will add a view to the second tab:

var view = Ti.UI.createView({
    top:20,
    bottom:'50%',
    left:20,
    right:'50%',
    backgroundColor:'red'
});

win2.add(view);

What just happened?

A red box has been added to the top left of the second tab as shown in the following screenshot:

The beauty of views is that they act as containers for anything you add to them. So, if you add a button to a view and give the button details of where you want it positioned, for example, 10 pixels from the top and 10 pixels from the left, it will be positioned 10 pixels from the top of the view. Thus a view becomes a small drawing area independent of the window. If you add something to a view, its position is not relative to the window, but relative to the view. So if we add a button with a specific position to our view, the button will be positioned within the view not relative to the window, as we shall now see...

Time for action – adding a button to a view

In app.js add the following code to add the button to the view:

var button1 = Titanium.UI.createButton({
    title:'Button in View',
    top:10,
    left:10
});

view.add(button1);

Note

The text on the button is specified by the title argument. Other objects such as a label or textfield use the text argument to specify the displayed content. See the Appcelerator documentation http://docs.appcelerator.com/titanium/3.0/# for the appropriate argument for your object.

What just happened?

A button has been added within the view. Note that the position of the button of 10 pixels from the top and 10 pixels from the left is relative to the view and not the window. This is an important and very useful feature of views. You lay out the view within a window, like drawing a picture in a paint package that occupies only part of your display.

Note

Notice how the button butts up against the top-right edge of the view. We didn't specify a size for the button via the...

Time for action – making something happen when the button is pressed

Perform the following steps to make something happen when the button is pressed:

Add an event listener to the button. This event listener will respond when the user clicks on the button.
```
button1.addEventListener('click', function(e) {alert('You clicked me!')})
```
Run the app and click on the button!

What just happened?

You added an event listener to the button so that when the button is clicked, an alert box is displayed. The Appcelerator documentation lists the events that are applicable for an object. You will use event listeners frequently in Titanium. They are explained in more detail in Chapter 4, Gluing Your App Together with Events, Variables, and Callbacks.

Adding a settings screen – a TableView masterclass

Views really come into their own when they are added to other controls, which we will see later in this chapter. We will also see them being used to control the layout of other elements. However, first of all, it's time to make something simple but useful with our app.

In this example we are going to use a table view to create a setting screen for the app. It's just one of the many uses there are for a table view. It's a versatile item that crops up in many places such as your contact list and your e-mail inbox. It is a very useful tool. We will now create a settings screen similar to that shown in the previous example.

Time for action – adding a new window

Perform the following steps to add a new window:

Add a new window and create a tab for it in the same way as in the earlier example from this chapter:

var winSettings = Ti.UI.createWindow({
});

var tabSettings = Titanium.UI.createTab({  
    icon:'KS_nav_views.png',
    title:'Settings',
    window:winSettings
});

Add the new tab to the tab group:
```
tabGroup.addTab(tabSettings);
```
In an attempt to keep the app.js file tidy we will place the code to create the settings layout in a function at the top of the file:
```
function setupSettings() {
    
}
```
The setupSettings function will create a settings layout that will be built on a view. The view will be returned from the function. Make changes to the function code by adding the following code:
```
function setupSettings() {
    
    var view = Ti.UI.createView({});
    return view;
}
```
This view can be added to the winSettings window by adding the code highlighted in the folowing code. The code adds the return value, which...

Time for action – adding a styled TableViewRow object

With a few simple additions and some changes to fonts we can make a more complex table view layout. This example will add a TableViewRow object that is similar in appearance to the mailbox e-mail listing. Perform the following steps to add a styled TableViewRow object:

Add an empty TableViewRow object:

var secondRow = Ti.UI.createTableViewRow({});

Add a title to the new row:

var theTitle = Ti.UI.createLabel({
        text: 'The title',
        font:{fontSize:'16',fontWeight:'bold'},
        minimumFontSize:'12',
        textAlign:'left',
        top:'2',
        left:'10',
        height:'20'
     });

Add another label with context information:

var theSnippet =  Titanium.UI.createLabel({
        text:'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor',
        font:{fontSize:'11',fontWeight:'normal'},
            textAlign:'left',
        color:'#666',
        bottom:'0',
        left:'10',
        height...

Platform-specific tools

There are many fundamental differences between Android and iOS. Android has the menu, iOS has a back button. Titanium respects this and has elements for individual operating systems.

For the final set of examples in this chapter, we will look at some of the platform-specific tools available in Titanium. It may seem incongruous to have platform-specific controls but it is an absolutely necessary part of the toolkit for creating native applications that embrace the identifying features of the platform. If it is a significant feature of an operating system that is not cross-platform it will be included in Titanium. A great example of this is the menu button on Android. It's a fundamental part of the Android design and something that the user will expect to be available yet there is no equivalent in iOS. Your Android app should make use of it.

Adding an Android menu

In the next example we will add an Android menu to our app.

Time for action – adding an Android menu

Perform the following steps for adding an Android menu:

Add a function that will define the pop-up menu:

function addMenu(win) {
    var activity = win.activity;

    activity.onCreateOptionsMenu = function(e){

    var firstItem = e.menu.add({ title: 'First Item' });
    firstItem.addEventListener("click", function(e) {Ti.API.debug('First Item'); });
    
    var secondItem = e.menu.add({ title: 'Second Item'});
    secondItem.addEventListener("click", function(e) {Ti.API.warn('Second Item'); });
    
    var thirdItem = e.menu.add({ title: 'Third Item'});
    thirdItem.addEventListener("click", function(e) {alert('Third Item'); });
};
}

Further down app.js where the windows are defined, add the highlighted code to call the function:
```
win1.add(label1);
addMenu(win1);
```
Run the app using the Android emulator.

What just happened?

A pop-up menu was created that is activated by pressing the menu key when Tab 1 is selected. The pop-up menu has three items and...

Time for action – running the Android menu changes on iOS

If you are running on a Mac and have the iOS SDK installed, try running the app on the iOS emulator.

What just happened?

The app will fail to run. The red screen of death that will become familiar as you code your apps will be displayed.

Why did this fail?

The line that caused the error is as follows:

var activity = win.activity;

An iOS window has no concept of an activity. The activity property will not be available on iOS. The Appcelerator documentation is clear in this respect; the documentation shows that the activity property only exists on Android as shown in the following image:

You have to handle this platform-specific code yourself. Fortunately, it's not hard to do and if you are developing a cross-platform app it is a concept you will use often.

Isolating platform-specific code

When you have platform-specific code you have to have some way of avoiding executing it on the wrong platform. This usually means wrapping the code in an...

Time for action – add an iOS fix for the Android menu

Here is how to fix the Android menu problem on iOS:

Add the following function to app.js:

function isAndroid() {
    return (Ti.Platform.name == 'android');
}

Wrap the addMenu function where our platform-specific code lies with this code:

function addMenu(win) {
    
    if (isAndroid()) {
    var activity = win.activity;

    activity.onCreateOptionsMenu = function(e){

    var firstItem = e.menu.add({ title: 'First Item' });
    firstItem.addEventListener("click", function(e) {Ti.API.debug('First Item'); });
    
    var secondItem = e.menu.add({ title: 'Second Item'});
	secondItem.addEventListener("click", function(e) {Ti.API.warn('Second Item'); });
    
    var thirdItem = e.menu.add({ title: 'Third Item'});
    thirdItem.addEventListener("click", function(e) {alert('Third Item'); });
    }
};
}

Run the app on the iOS emulator.

What just happened?

An if statement was added that ensured that if the app was run on iOS, a menu would not...

Capturing debug messages

There are a few helper functions that are available to enable you to send out debug messages from the app.

Function

Description

Ti.API.debug('text')

Or

console.debug('text')

Write a message to the console at the debug level.

Ti.API.warn('text')

Or

console.warn('text')

Write a message to the console at the warn level. These messages are colored yellow.

alert('text')

Displays an alert box with the text and a single OK button.

Tip

Debugging code should be removed from your code or disabled before you go live. They are unlikely to result in your app submission being rejected, but the same messages that appear on the console in Titanium will be logged to the log files on your device. You don't want a clever developer snooping on your debug messages when the app is live.

Note

Note that by default debug messages will not appear on the console. The default log level is to record errors and warnings. This can be altered by navigating to the Run | Run Configurations...

Time for action – adding an info button to the navigation bar

Perform the following steps to add an info button to the navigation bar:

Add a new function to the top of app.js:

function rightButton(win) {
    if (!isAndroid()) {

      var right = Ti.UI.createButton({
         systemButton:Ti.UI.iPhone.SystemButton.INFO_LIGHT
      });
      right.addEventListener('click',function()
      {
         alert('button clicked!');
      });
      win.setRightNavButton(right); 
   }
}

Add a call to the function from the main body of app.js:
```
rightButton(win1);
```
Run the App in the iOS emulator.

What just happened?

A couple of iOS-specific properties were used in the rightButton function. The systemButton property allows a predefined iOS icon to be applied to your button. There are several styles available (see documentation for Titanium.UI.iPhone.SystemButton). Then an iOS specific window method setRightNavButton was used to place this button on the right-hand side of the navigation bar.

Summary

That's enough for this chapter. Yes, there are plenty of other elements in the toolkit that we have not covered. I could show you how to add a slider, or a switch, but I see little value in adding several examples when the principle is very similar to adding a button. Don't take my word for it; have a look at the examples from the code snippets. The main difference is the name of the control.

This chapter has taught you the principles you need to employ for adding any of the items in the toolkit. I urge you to go away and play with the app.js code and add sliders, switches, text areas, or any other control. Go ahead and enjoy yourself, it doesn't matter if you break the code, we will be throwing it away after this chapter anyway. It's a good time to move on from this app; it's served us well but it's getting a bit messy and disorganized.

If playing and editing with the code is not your thing, have a look around the Kitchensink app (which can be installed from the Titanium dashboard...

Appcelerator Titanium Application Development by Example Beginner's Guide: Once you've got into Appcelerator Titanium you'll never look back. This book is the perfect introduction to developing native cross-platform apps for iOS, Android, and Windows 8.

What do you get with Print?

Contact Details

Shipping Address

Billing Address

Key benefits

Description

Who is this book for?

What you will learn

Product Details

What do you get with Print?

Contact Details

Shipping Address

Billing Address

Product Details

Packt Subscriptions

Frequently bought together

Table of Contents

Recommendations for you

Customer reviews

Filter reviews by

People who bought this also bought

About the author

FAQs