Tag Archives: titanium tabs

Seven days with Titanium – day 1 – windows, views, navigation and tabs

Today is going to be the first day of the Titanium tutorial for beginners and a pretty long post.
Before we begin here is the recap of what we have written until now (and updated what will come): Seven days with Titanium – day 0 – introduction

As specified in the Introduction post I will try in this lesson to say some things about navigation, windows, views and tabs – the basics of the interface.

I will try to first to enumerate each of these elements and then explain what they do and how to use them. Also each interface element has a link to it’s documentation page on Appcelerator site.

Everything that is related to the interface you will find it into the Titanium.UI module. There are also some platform specific modules that cover elements of interface present only on the specific platform: Titanium.UI.Android,Titanium.UI.iPhone,Titanium.UI.iPad but for now we won’t talk about them.

The Window element

The basic element in a Titanium application is a Window. There is nothing complicated here, it’s a “container” for all the other elements if you wish. An application can have one or more windows but it must to have at least one window. A Window it’s one of the few elements that can exist by itself without the need to be a child of something.

The View element

Another basic element it’s a View. The View can be the analog of a div tag in HTML so basically it’s just a rectangle that can hold other elements for an easy and convenient control of the application’s layout. A View cannot exists by itself it will have to be a child of a Window or other element that accepts Views as child (a TableRowView or another View for example).

The TabGroup and the Tabs

The main navigational elements (and common to all platforms) is the TabGroup and the Tabs. Exactly what the names says – analog with a browser with tabs capabilities , a TabGroup will hold more Tabs. Each Tab will control (open) a window. If you decide that you application will have a TabGroup this will be the “root” of the application. What does it mean? That any window opened by the Tabs in TabGroup will be controlled by this and the TabGroup has one instance only and it cannot be closed or removed, but only hidden.

There is also an iPhone specific navigation element, named NavigationGroup that allows to navigate through windows without the need to create the navigation toolbar/buttons by ourselves.

Example

This is how an application with a TabGroup, 2 Windows, 2 Tabs and a View looks loke on the Android and the iPhone platforms.

Seven days with Titanium- day 1 - androidSeven days with Titanium- day 1 - iPhone

More details about each element

Before we continue it would be great to take a look at each element documentation page because there is a lot of valuable info there. As you see, each interface element has some properties that are setters and/or getters like top, backgroundColor, etc), some methods (add(), open()) and events – usually user interaction events (touchstart, doubletap, etc) or specific events (open,close). Very similar with the web elements.

I want to specify some things:
sizes are in pixels but without the usual “px” notation, or in percents – but this requires to be written as a string:

...
top:25,
width:"50%"
...

colors are in hexa rgb , the short or the long form , don’t use names:

...
backgroundColor:"#f00",
borderColor:"#ff0055"
...

Let’s try to elaborate a little.

The Window element, again

The window element is created using the function Titanium.UI.createWindow.

var win1 = Titanium.UI.createWindow({  
    title:'Tab 1',
    backgroundColor:'#fff'
});

What the above code means? That we pass to the createWindow function an object argument with all the properties that we want to set.

This could be written like this:

var win1 = Titanium.UI.createWindow();
 
win1.title='Tab 1'
win1.backgroundColor='#fff';

I think it’s pretty clear so I won’t go further with the code for view, tabs and so on. It’s similar to this only that you use Titanium.UI.createView, etc

How the tabGroup, tabs and the windows are related

The logic behind the above UI elements it’s as it follows:

The tabGroup is the root of the application, the “master”, it cannot be included in any other UI element.
This holds the tabs( at least one) and a tab, when clicked, opens the window associated with it.

Here is a sample code:

 
// create tab group
var tabGroup = Titanium.UI.createTabGroup();
 
// create base UI tabs and  windows
 
var win1 = Titanium.UI.createWindow({  
    title:'Tab 1',
    backgroundColor:'#fff'
});
var tab1 = Titanium.UI.createTab({  
    icon:'KS_nav_views.png',
    title:'Tab 1',
    window:win1
});
 
var win2 = Titanium.UI.createWindow({  
    title:'Tab 2',
    backgroundColor:'#fff'
});
var tab2 = Titanium.UI.createTab({  
    icon:'KS_nav_views.png',
    title:'Tab 2',
    window:win2
});
 
//  add tab
 
tabGroup.addTab(tab1);  
tabGroup.addTab(tab2);  
// open tab group
tabGroup.open();

The above code will generate a similar interface with the screenshots without the labels “I am window 1” etc and the red view. This would be a good exercise for you :).

Important !

As you see we set the same titles to tab1 – win1 and to tab2 – win2. This is not mandatory from the code point of view. The window associated to each tab is specified using the window property that points to the previous declared window. Why it’s like this then? It’s about usability. The user needs to have the same values when he/she has to associate two visual elements or will get confused. Also Apple might not like this when you will submit your app.

Resources

The above code it’s found in the default app.js file that you get when you create a new project. I only explained a little how things are.

A very very good resource it’s the KitcheSink project form Appcelerator team, found here.

For the advanced coders this is another tutorial on how to create a tooltip with Titanium that basically it’s just a view with a background image.

I think it’s enough for day 1, the post is too long and I’ll only add that I’m waiting for your questions, suggestions and critics if I made any mistake 🙂 With your questions/suggestions I’ll update the post or create a new one linked to “day 1”.

Check the Spanish version of this post:
Siete días con Titanium – Día 1 – Ventanas, vistas, navegación y pestañas