Titanium.UI.Window

A window is a top-level container which can contain other views. Windows can be opened and closed. Opening a window causes the window and its child views to be added to the application's render stack, on top of any previously opened windows. Closing a window removes the window and its children from the render stack.

Windows contain other views, but in general they are not contained inside other views. There are a few specialized top-level views that manage windows, including:

• NavigationGroup
• SplitWindow
• TabGroup.

By default, windows occupy the entire screen except for the navigation bar, status bar, and in the case of windows contained in tab groups, the tab bar. To take up the entire screen, covering any other UI, specify fullscreen:true when creating the window.

Use the Titanium.UI.createWindow method to create a window.

Sub-contexts

Windows can be loaded from another JavaScript file by specifying the property url, referencing a file relative to your application Resources folder. It's important to note that Titanium will refuse to load JavaScript files from a remote URL. Loading remote JavaScript from a URL and providing it with the full capabilities of the Titanium API would be very dangerous.

When your Window is loaded from a separate JavaScript file, the code will be executed in a separate JavaScript context (called a "sub-context") than your app.js global context. It will also execute in its own separate thread.

On Android, a new context is also created when you create a heavyweight window. See the section, "Android Heavyweight and Lightweight Windows" for more information.

The special property Titanium.UI.currentWindow is available inside a sub-context that points to the JavaScript instance by reference in the global context.

Passing Data Between Contexts

By default, sub-context variables cannot access JavaScript references in the global context. There are two ways to pass data between the global context and the sub-context:

• Shared references
• Events

Note that in both cases, you cannot pass functions between contexts, only serializable data. Serializable data includes any JavaScript primitive or simple object composed of JavaScript primitives.

Passing Data with Shared References

You can allow a sub-context access to properties in the global context by reference assignment. An example best illustrates how to do this.

In app.js, you could define a property:

var message = "Hi world!";

Now, you can create a new Window - let's call it foo.js - in your app.js.

var w = Titanium.UI.createWindow({
    url:'foo.js'
});

To give your new window access to message, you would need to assign it to a property on the new window reference, w.

w.alertMessage = message;

This creates a new alertMessage property on the new window that holds a reference to the message property in the global context. Now, let's look at the code for foo.js.

alert(Titanium.UI.currentWindow.alertMessage);

In the above code, the foo.js will show an alert containing the text from the message property in the global context.

Passing Data with Events

If you'd like to send events to a window from the global context and vice versa, you could use the built-in event mechanism. For example, you could define a custom event called foo. The window could listen for this event and then respond with some action. For example, in your sub-context you might define:

Titanium.UI.currentWindow.addEventListener('foo',function(e)
{
    Titanium.API.info("foo event received = "+JSON.stringify(e));
});

You could now fire the event from app.js like this:

var window = Titanium.UI.createWindow({
    url:'bar.js'
});
window.open();
window.fireEvent('foo',{a:'b'});

It's worth noting two important limitations of the example above:

• You must open the window before you can send events to it. You also may have to fire the event after a specified amount of time if you intend to immediately send data to the window. This is because windows are opened asynchronously and on a separate thread than the caller thread.

• You can only send JSON-serializable data in fireEvent. If you attempt to send objects that have function references, they will be null.

Animations

Windows can be animated like any normal View. To transition between 2 windows, you can use the transition property on an animation. For example, to flip right-to-left between two windows, you could do the following:

var window2 = Titanium.UI.createWindow({url:'foo.js'});
var t = Ti.UI.iPhone.AnimationStyle.FLIP_FROM_LEFT;
window1.animate({view:window2,transition:t});

In the above example, the window2 view will be animated from the right-to-left over window1.

Windows can be opened or closed with animation. In the example below, we create a window that will open from small to large with a bounce effect. This is done by applying a transformation at initialization time that scales the original size of the window to 0. When the window is opened, a new 2D transformation is applied that will scale the window size from 0 to 110% of it's original size and then, after 1/20th of a second, will scale it back to it's original size at 100%. This gives the bounce effect during animation.

var t = Titanium.UI.create2DMatrix().scale(0);
 
// create a window with the initial transform scaled to 0
var w = Titanium.UI.createWindow({
    backgroundColor:'#336699',
    borderWidth:8,
    borderColor:'#999',
    height:400,
    width:300,
    borderRadius:10,
    opacity:0.92,
    transform:t
});
 
// create first transform to go beyond normal size
var t1 = Titanium.UI.create2DMatrix().scale(1.1);
 
var a = Titanium.UI.createAnimation();
a.transform = t1;
a.duration = 200;
 
// when this animation completes, scale to normal size
a.addEventListener('complete', function()
{
    // we can use the identity transform to take it back to it's real size
    var t2 = Titanium.UI.create2DMatrix();
    w.animate({transform:t2, duration:200});
});

iPad Modal Windows

For iPad, iPhone SDK 3.2 and Titanium 1.2 introduced several new ways of presenting modal windows. In addition to full-screen modal windows, the iPad supports "Page sheet" and "Form sheet" style windows:

• Page sheet style windows have a fixed width, equal to the width of the screen in portait mode, and a height equal to the current height of the screen. This means that in portrait mode, the window covers the entire screen. In landscape mode, the window is centered on the screen horizontally.

• Form sheet style windows are smaller than the screen size, and centered on the screen.

The example below is a modal window using the Form sheet style:

You can create this type of modal window on iPad with the following code snippet:

var window = Titanium.UI.createWindow();
window.open({
    modal:true,
    modalTransitionStyle: Ti.UI.iPhone.MODAL_TRANSITION_STYLE_FLIP_HORIZONTAL,
    modalStyle: Ti.UI.iPhone.MODAL_PRESENTATION_FORMSHEET
})

Android Heavyweight and Lightweight Windows

In Android, Titanium windows can be heavyweight or lightweight:

• A heavyweight window is associated with a new Android Activity. Creating a heavyweight window always creates a new JavaScript context.

• A lightweight window is a fullscreen view, and runs in the same Android Activity as the code that created it. Creating a lightweight window creates a new JavaScript context if it was created with the 'url' property set.

The createWindow call creates a heavyweight window if any of the following properties are true on creation:

• fullscreen
• navBarHidden
• modal
• windowSoftInputMode

A heavyweight window is always created when you open a new window from inside a TabGroup.

Android "root" Windows

In Android, you may wish to specify that a window which you create (such as the first window) should be considered the root window and that the application should exit when the back button is pressed from that window. This is particularly useful if your application is not using a Tab Group and therefore the splash screen window is appearing whenever you press the back button from your lowest window on the stack.

To indicate that a particular window should cause an application to exit when the back button is pressed, pass exitOnClose: true as one of the creation arguments, as shown here:

var win = Titanium.UI.createWindow({
    title: 'My Root Window',
    exitOnClose: true
});