NativeWindow – using AIR windows with Actionscript (part 1 of 3)
In a previous post I described how to create and activate an application window when creating an Actionscript AIR project in Flex Builder 3. I then went on to describe in a little more detail the various properties of the NativeWindowInitOptions class, and how setting some or all of these properties can affect the style and behaviour of the window that will be created. I guess the final step is to describe how to work with the window once it has been created, starting with an explanation of the flash.display.NativeWindow class. There’s quite a bit of functionality contained within the class, so I’ll break this post up into three. Part 1 will describe the properties of a NativeWindow, part 2 will list the public methods and finally part 3 will discuss the events dispatched by the Window throughout its lifetime.
As previously mentioned, an application window is created and displayed in Adobe AIR by creating a new instance of the NativeWindow class, and then calling this instance’s activate method. Content is added to the window by adding DisplayObjects to the stage property of the NativeWindow instance.
Here are descriptions of each of the NativeWindow’s public properties…
NativeWindow.active
Indicates whether or not a NativeWindow is the active application window or not. So for example, if your application has opened two windows, depending on which of those windows is currently being interacted with, one window’s active property will return true, and the other will return false. To activate a NativeWindow programmatically, you can call someNativeWindow.activate ().
NativeWindow.alwaysInFront
Rather obviously, this Boolean property will specify whether or not the window will always be on top of other windows (even those from other applications). For most situations, this property should be left as false unless the window needs to stay on top of other applications for a particular reason.
It’s possible to trigger certain behaviours by changing the value of this property. Setting this value from false to true will bring the window in front of all other application windows. Changing the value from true to false will send the window behind any other windows on the system with alwaysInFront set to true, but still on top of all other windows.
NativeWindow.bounds
This property, of type flash.geom.Rectangle, contains information about the position and size of the window including any system chrome. The fact that these dimensions include the system chrome is important. The size of the stage of the window (the area which is used for any content added to the stage), is equal to the size of the window minus the size of the chrome.
Setting the bounds property of a window is the same as setting it’s x, y, width, and height properties all in one step.
If you attempt to set the size of the window to an illegal size (for example, smaller than the minSize property, larger than the maxSize property, or larger or smaller than the limits imposed by the OS) then the window will be sized to the nearest acceptable value. This applies when setting the size of the window through the bounds property, and also when setting the width or height directly.
This property will be revisited in part 3 of this post when Events dispatched by the window will be discussed.
NativeWindow.closed
This Boolean indicates whether or not the window has been closed. Attempting to access certain properties or methods of a window which has been closed will cause an IllegalOperationError to be the thrown.
NativeWindow.displayState
This property is a string, and describes the window’s current display state. The possible values of this property are fairly self explanatory:
- NativeWindowDisplayState.NORMAL
- NativeWindowDisplayState.MINIMIZED
- NativeWindowDisplayState.MAXIMIZED
NativeWindow.height
The height of the window including any system chrome. To access the height of the usable area within the system chrome, use stage.stageHeight.
NativeWindow.maximizable
This Boolean tells us whether or not the window is maximizable. The value is set using the NativeWindowInitOptions instance, passed to the constructor, and cannot be modified once the window has been created.
NativeWindow.maxSize
This property, of type flash.geom.Point (Point.x corresponds to the width, Point.y corresponds to the height), allows us to specify the maximum size of the window. This maximum size is enforced when resizing is triggered both by Actionscript, or by the user clicking the OS maximize button.
NativeWindow.menu
This property allows us to create a flash.display.NativeMenu to be displayed for the Window. Note, for the menu to be displayed, NativeWindow.supportsMenu must be set to true, and NativeWindow.systemChrome must not be set to NativeWindowSystemChrome.NONE.
NativeWindow.minimizable
This Boolean tells us whether or not the window is minimizable. The value is set using the NativeWindowInitOptions instance, passed to the constructor, and cannot be modified once the window has been created.
NativeWindow.minSize
This property, of type flash.geom.Point, allows us to specify the minimum size of the window. This minimum size is enforced when resizing is triggered either by Actionscript, or by the user clicking the OS maximize button.
NativeWindow.resizable
This Boolean tells us whether or not the window is resizable. The value is set using the NativeWindowInitOptions instance, passed to the constructor, and cannot be modified once the window has been created.
NativeWindow.stage
This property gives us read-only access to the flash.display.Stage object at the root of this window’s display list. For content to be displayed in the window, it must be added to the stage (or to a descendant of a DisplayObject already added to the stage).
NativeWindow.supportsMenu
Setting this Boolean to true allows us to display a NativeMenu for this window by setting the menu property (see above). For the menu to be displayed, the systemChrome property must not be set to NativeWindowSystemChrome.NONE.
NativeWindow.supportsNotification
You know how sometimes an application can flash in some way to show you that something has happened? On Windows, the window’s entry in the task bar might flash, or on OS X the icon in the dock might jump around a bit. This property tells you whether or not this functionality is supported on the system on which your application is running. If this property is true, you can trigger this visual cue with the window’s notifyUser method.
NativeWindow.supportsTransparency
This Boolean property tells us whether or not transparency of windows is supported in the current environment. If the transparent property of the window is set to true, and supportsTransparency is also true, then your transparent window will work as expected. If, however, supportsTransparency is false, the your transparent window will not render correctly. Any pixels intended to have an alpha of 0 will be rendered as black. It’s also worth noting that this value may change during the lifetime of your window, for example if a user updates a preference setting.
NativeWindow.systemChrome
This read-only property tells us what system chrome is employed by the window. The property will match one of the constants defined in the NativeWindowSystemChrome class. The systemChrome is originally specified in the NativeWindowInitOptions class which is passed to the NativeWindow constructor and cannot be altered once the window has been created.
NativeWindow.systemMaxSize
This read-only property lets us find out the maximum size of a window allowed by the operating system. It’s a flash.geom.Point object with Point.x representing the width, and Point.y representing the height.
NativeWindow.systemMinSize
Similarly, thisy property lets us find out the minimum size of a window allowed by the operating system. Again, it’s a flash.geom.Point object with Point.x representing the maximum width, and Point.y representing the maximum height.
NativeWindow.title
This property lets us set the window title. Assuming we are using system chrome, the title will be displayed in the title bar, and also in other OS-specific locations such as the Windows taskbar.
NativeWindow.transparent
This Boolean tells us whether or not the window supports transparency. The value is set using the NativeWindowInitOptions instance, passed to the constructor, and cannot be modified once the window has been created. This property also relies upon the supportsTransparency property (see above) being equal to true.
NativeWindow.type
This read-only property tells us what window type setting was chosen when the window was created. The property will match one of the string constants defined in the NativeWindowType class. The type is originally specified in the NativeWindowInitOptions class which is passed to the NativeWindow constructor and cannot be altered once the window has been created.
NativeWindow.visible
This boolean allows us to control whether or not the window is visible. A window which is invisible will still be accessible, and all its methods and properties will still exist, it just will be hidden.
When a window is first created, it’s visible property will default to false. To show a window, you have to either call the activate method or set the visible property to true.
NativeWindow.width
The width of the window including any system chrome. To access the width of the usable area within the system chrome, use stage.stageWidth.
NativeWindow.x
This property is the horizontal co-ordinate of the window’s top left corner relative to the operating system’s desktop.
NativeWindow.y
This property is the vertical co-ordinate of the window’s top left corner relative to the operating system’s desktop. There are two ways to programmatically reposition a NativeWindow. Either set it’s x and y properties to new values, or set the bounds property as described above.
That’s it!
So that’s all the properties of the NativeWindow class – there’s quite a few of them, but there’s nothing too complicated in there. In the second part of this post I’ll list the public methods exposed by NativeWindow.
Update: Part 2 of this post can be found here.