Launching windows
Requirements
Prerequisite knowledge
General experience of building applications with Flex Builder is suggested. For more details on getting started with this Quick Start, refer to Building the Quick Start sample applications with Flex.
User level
Intermediate
Required products
- Adobe AIR
- Flash Builder (Download trial)
Sample files
The Window Sampler application, shown in Figure 1, demonstrates the basics of opening new windows in Adobe AIR.
More specifically, it shows the following AIR features:
- Creating a window using the mx:Window class in the Flex framework
- Creating a window to display HTML using the HTMLLoader class
- Creating a window using the NativeWindow class
- Setting the window type
- Setting the window chrome
- Turning on transparency
- Setting the window title
- Setting the window position and size
- Setting whether a window is resizable, minimizable, and maximizable
Understanding the code
Note: This article does not describe all of the Flex components used in the MXML code for the file. For more information, see the Flex 3 Language Reference.
The Window Sampler creates windows using three techniques:
- Creates a Flex mx:Window object containing a DataChooser component.
- Creates an HTML root window and loads an example HTML page.
- Creates a NativeWindow object, adds a Sprite object to the stage, and draws a grid of rectangles filling the window.
Creating a Flex window
Window Sampler defines the function createNewFlexWindow() to create a Flex window based on the settings of the controls in the main window. The function performs the following tasks to create the window:
- Calls the mx:Window constructor and sets the window properties:
var newWindow:Window = new Window();
newWindow.maximizable = maximizableOption.selected;
newWindow.minimizable = minimizableOption.selected;
newWindow.resizable = resizableOption.selected;
newWindow.transparent = transparentOption.selected;
newWindow.systemChrome = Chrome.selectedItem.optionString;
newWindow.type = windowType.selectedItem.optionString;
newWindow.title = titleString.text;
newWindow.alwaysInFront = alwaysInFrontOption.selected;
newWindow.showStatusBar = false;
newWindow.layout = "absolute";
- Calls the window's
open()method. This creates the associated NativeWindow and Stage objects for the window, but does not display it because theopenWindowActiveparameter isfalse. Any properties that reference the stage or native window objects must be set after the call toopen():
newWindow.open(false);
newWindow.stage.align = stageAlignment.selectedItem.optionString;
newWindow.stage.scaleMode = ScaleMode.selectedItem.optionString;
newWindow.nativeWindow.x = Number(xPosition.text);
newWindow.nativeWindow.y = Number(yPosition.text);
- Adds content. This example adds a DateChooser control to the window and anchors the sides of the control to the sides of the window using styles:
var exampleContent:DateChooser = new DateChooser();
exampleContent.setStyle("top",10);
exampleContent.setStyle("left",10);
exampleContent.setStyle("bottom",10);
exampleContent.setStyle("right",10);
newWindow.addChild(exampleContent);
Activates the window to display it:
newWindow.activate();
Creating an ActionScript window
Window Sampler defines the function, createNewWindow() to create a new native window based on the settings of the controls in the main window. The function performs the following tasks to create the window:
- Creates a NativeWindowInitOptions object and sets its properties. The init options define the properties of a native window that cannot be changed after the window is created.
var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.maximizable = maximizableOption.selected;
options.minimizable = minimizableOption.selected;
options.resizable = resizableOption.selected;
options.transparent = transparentOption.selected;
options.systemChrome = Chrome.selectedItem.optionString;
options.type = windowType.selectedItem.optionString;
Note: Transparency is not supported for windows that use system chrome. Likewise, system chrome cannot be used for lightweight windows. These rules are enforced in Window Sampler by validating the settings as they are made.
- Creates the window, passing in the NativeWindowInitOptions object., and sets the window properties which can be changed after window creation:
var newWindow:NativeWindow = new NativeWindow(options);
newWindow.title = titleString.text;
newWindow.alwaysInFront = alwaysInFrontOption.selected;
newWindow.x = Number(xPosition.text);
newWindow.y = Number(yPosition.text);
newWindow.width = Number(widthValue.text);
newWindow.height = Number(heightValue.text);
newWindow.stage.align = stageAlignment.selectedItem.optionString;
newWindow.stage.scaleMode = ScaleMode.selectedItem.optionString;
The width and height properties set the outer dimensions of the window, including the size of any system chrome. Thus a window without system chrome has a smaller client area than a window with chrome set to the same width and height.
- Adds content.
A native window is created with a stage that represents the client (drawable) area of the window. This stage is the root container of the display tree. Add content to the client area of a native window by adding a DisplayList object (or an object that inherits from DisplayList) to the stage or another DisplayObject already on the stage with the addChild() method.
The following lines from the createNewWindow() method of the sample application set the stage properties based on the MXML control settings and draws some example content into the window by creating a Sprite and calling its graphics methods to draw a grid of rectangles:
var client:Sprite = new Sprite();
var rectSize:int = 40;
var rectSpace:int = 4;
with(client.graphics){
lineStyle(1,0,1);
beginFill(0x234578,.5);
for(var i:int = 0; i <= Math.floor(newWindow.stage.stageWidth/rectSize); i++){
for (var j:int = 0; j <= Math.floor(newWindow.stage.stageHeight/rectSize); j++){
drawRoundRect(i*rectSize,j*rectSize,
rectSize-rectSpace,rectSize-rectSpace,10,10);
}//j loop
}//i loop
endFill();
}
newWindow.stage.addChild(client);
Note: You cannot add Flex components directly to a native window.
- Adds interactivity. Two event handlers are added to windows with no chrome to allow you to move and close the window:
if(options.systemChrome == NativeWindowSystemChrome.NONE){
newWindow.stage.doubleClickEnabled = true;
newWindow.stage.addEventListener(KeyboardEvent.KEY_DOWN,
function(e:Event):void{e.target.stage.window.close();});
newWindow.stage.addEventListener(MouseEvent.MOUSE_DOWN,
function(e:Event):void{e.target.stage.window.startMove();})
}
- After the window has been created, content added, and event handlers attached, the final step is to make the window visible:
newWindow.visible = true;
About Stage properties
The stage scaleMode property sets how the stage scales and clips child display objects when a window is resized. Only the noScale mode should be used in AIR. In this mode, the stage is not scaled. The size of the stage changes directly with the bounds of the window. Objects may be clipped if the window is resized smaller.
The stage scale modes are designed for use in a browser environment where you don't always have control over the size or aspect ratio of the stage. The modes let you choose the least bad compromise when the stage does not match the ideal size or aspect ration of your application. In AIR, you always have control of the stage, so you get better results by changing the dimensions of your window than scaling the window content.
In the browser and for the initial AIR window, the relationship between the window size and the initial scale factor is read from the loaded SWF file. However, when you create a NativeWindow, AIR chooses an arbitrary relationship between the window size and the scale factor of 72:1. Thus, if your window is 72x72 pixels, a 10x10 rectangle added to the window is drawn the correct size. If the window is changed to 144x144, then a 10x10 pixel rectangle is scaled to 20x20 pixels. If you insist on using a scaleMode other than noScale, you can compensate by setting the scale factor of any display objects in the window to the ratio of 72 pixels to the current width and height of the stage. The Window Sampler uses the following code to rescale the Sprite objects added to the stage of the example ActionScript windows when noScale is not chosen as the scaleMode:
if(newWindow.stage.scaleMode != StageScaleMode.NO_SCALE){
client.scaleX = 72/newWindow.stage.stageWidth;
client.scaleY = 72/newWindow.stage.stageHeight;
}
Flex and HTML windows automatically set the stage scaleMode to noScale. Changing the scaleMode disturbs the automatic layout mechanisms used in these types of windows.
The stage align property sets the edge or corner to which the stage origin is anchored when the window is resized. For example, if you set the stage align property to bottomRight , then when the window is resized larger from the bottom, right corner, the stage origin also moves down and to the right in relation to the window. After this change, you would have to use negative coordinates to then position an object in the top, left corner. The stage origin is always the top, left corner of the window when the window is first opened, no matter which alignment value is chosen.
Creating an HTML window
Window Sampler defines the function, createNewHTMLWindow() to create an HTML window based on the settings of the controls in the main window. The function performs the following tasks to create the window:
- Creates a NativeWindowInitOptions object and sets its properties. The init options define the properties of a native window that cannot be changed after the window is created.
var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.maximizable = maximizableOption.selected;
options.minimizable = minimizableOption.selected;
options.resizable = resizableOption.selected;
options.transparent = transparentOption.selected;
options.systemChrome = Chrome.selectedItem.optionString;
options.type = windowType.selectedItem.optionString;
Note: Transparency is not supported for windows that use system chrome. Likewise, system chrome cannot be used for lightweight windows. These rules are enforced in Window Sampler by validating the settings as they are made.
- Creates the window, passing in the NativeWindowInitOptions object, and sets the window properties which can be changed after window creation:
var html:HTMLLoader = HTMLLoader.createRootWindow(false, options, true,
new Rectangle(Number(xPosition.text),
Number(yPosition.text),
Number(widthValue.text),
Number(heightValue.text)));
var newWindow:NativeWindow = html.stage.nativeWindow;
newWindow.alwaysInFront = alwaysInFrontOption.selected;
The HTMLLoader.createRootWindow() function creates a native window, adds an HTMLLoader object to the window stage, and sets up scroll bars.
- Loads the window content and, when the page load is complete, activates the window:
html.load(new URLRequest("app:/html/bounce.html"));
html.addEventListener(Event.COMPLETE, loadDocument);
function loadDocument(event:Event):void{
html.window.document.title = titleString.text;
//activate the new window
newWindow.activate();
html.removeEventListener(Event.COMPLETE, loadDocument);
}
