day1

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

31 thoughts on “Seven days with Titanium – day 1 – windows, views, navigation and tabs”

  1. Just a slight typo in the tabGroup explanation.
    “The tableGroup is the root of the application” – Shouldn’t it be “tabGroup” and not “tableGroup”? You might confuse those who don’t know.

  2. No problem. I was kinda disappointed though that this part didn’t feature anything more, since I already knew this. Guess I’m better than I thought x)

    Looking forward to the rest of the tutorials! The hardest part is coming up with a good app idea. Well at least I’ll be prepared when it happens. :)

  3. Well, just shout, what would you like to know, or what would you like to learn, and if know how, I’ll try to reply.
    All your comments are a great help for me to improve this.

  4. Are the tutorials posted every day, like day 2 will be posted tomorrow etc? Just to clear things up. And I’d really like some game tutorials, but as you said, this is a beginners tutorial. Just a tip for future stuff :)

  5. Thanks for your efforts!

    Nothing new for me (ye), but I still enjoy reading your tutorials in case I missed anything.

    Looking forward to the more advanced topics.

    Keep up the good work!

    /J

  6. Hi,

    I have to disagree with you when you say “colors are in hexa rgb, (…) don’t use names”. You can use color names. Examples of this are found in the kitchenSink app code. Also, if you search your project files for a file named Webcolor.m, in my case located inside /”myprojectpath”/build/iPhone/classes/, and take a peek at it, you can see that it recognizes the following words as colors:

    black, gray, darkgray, lightgray, white, red, green, blue, cyan, yellow, magenta, orange, purple, brown, transparent, aqua, fuchsia, lime, maroon, pink, navy, silver, olive, teal.

    One of many undocumented pieces of code of the Titanium platform :)

  7. can you please elaborate about how to change the properties of the Tabs like color, font, background, position etc.. i have tried everything but nothing worked..

    thanx in advance..

    David

  8. Hi David. There is no way to change the look of the tabs. The only way you could do this would be to create your own custom interface elements that emulate the tab behaviour.

  9. Hello Dan.

    I was wondering if it’s possible to use Tabs not just in the main window (app.js) but into another window.

    I’m loading a new ‘createWindow’ and then trying to create the tabGroup there. But it’s not working, I’m sort of mad about it. And maybe the proper answer is “you cannot do it in that way”, tabGroup only works on the first UI element. So please Dan, if you can help me on that, I would be more than glad.

  10. The tutorial specifies that the tabGroup is the “root” of the application – “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.”
    So you cannot have a tabGroup in a window or more tabGroups in the app.

  11. If I have two tabs and on tab1 the user selects a value(say a dropdown)… how can I update the content on tab2 to reflect the change in preference from tab1?

    Thanks for the tutorial!

  12. You can try to use some global variables – maybe set in Titanium.App ( Titanium.App.my_var = “something” ), but take care to use some names that don’t overwrite Titanium’s properties, or, you could make use of custom events.

  13. Can you say anything about views vs. windows performance-wise? As an example, if I were to make a book or a slideshow, would I make 30 views and animate them in one window or would I make 30 windows?

    Thanks for a great tutorial series – much appreciated! There’s next to nothing out there on Appcelerator so this is great!

  14. Hi Chris,
    I think the choice between windows and views in your case depends on how much load your app will put on the device.
    If there is much load on each scene, use windows and close it as soon as you don’t need it anymore – to free resurces. If all is lighter, you could use views.

  15. Hi Dan,

    just found this, and I like it a lot. I was quite confused about some pretty basic stuff, like the views, tabs and windows, yet your posts cleared them up.

    Some additions you might want to add is stuff like show(), hide(), open() and close(). These four methods all apply to different objects, and opening and closing can be animated (as you already may know and will probably cover in a later tutorial day (i am just on day one).

    Thanks again for the excellent explainations though,
    Christophe Leske

  16. can i add tabGroup in window…means suppose i have an window and above one search button at just bottom of that there is tabGroup i want to add tabGroup in root window can its possible???

  17. Hi,
    Can you please guide me on how to implement radio buttons and check boxes in Titanium for iPhone and android platforms?

    Thanks

  18. On the iPhone you won’t find this two controls. You can use a switch instead of the checkbox, or you can try to emulate them with normal images.

  19. Dan,
    Is there a way in which we can define a generic layout for an application on Android/iPhone .I mean the positioning of UI components, can it be generalized so that we need not care about the pixels and the positioning is relative .

  20. As far as I know, not for now. On the android devices all the screens sizes start as a derivate of 320×480 so it’s pretty safe to develop for this resolution because the device will scale the app. The only thing you need to take care is the background images and the splash, to be made for those resolutions you need to support.

  21. Is it possible to close a tabgroup completely or close the app ?

    My app sign’s on a public website and i would like to give the possibility for the user to logoff and quit the app on a single tap..

    Thanks

  22. On iOs you cannot close the app except using the home button on the device. On Android I think it’s possible but is is not a good practice.

Comments are closed.