Event.ACTIVATE

This event is sent out when the window is activated. The event doesn’t go through a capture phase, and it won’t bubble up the Display List. Some examples of when your window may dispatch this event include:

• When the NativeWindow is first created and activated
• When your application contains multiple NativeWindows and the user clicks on a window which previously was not the active window, giving it focus and bringing it to the front, the window will dispatch Event.ACTIVATE
• When you switch to another running application elsewhere on the system (an AIR application, or otherwise) and then switch back to this window, the event will be dispatched

Event.DEACTIVATE

Similarly, this event is sent out when the window is deactivated. Again, the event doesn’t go through a capture phase, and it won’t bubble up the Display List. Some examples of when your window may dispatch this event include:

• When your application contains multiple NativeWindows and the user clicks on a window which previously was not the active window, giving it focus and bringing it to the front, the window which previously was active and had the focus will dispatch Event.DEACTIVATE
• When you switch to another running application elsewhere on the system (an AIR application, or otherwise), the previously active window will dispatch this event

Event.CLOSING
Event.CLOSE

I have grouped these two events as they are rather obviously connected. If the user clicks the exit button in the system chrome, for example, the sequence of events will be:

• An Event.CLOSING event is dispatched.
• If this event is not cancelled (by calling the event’s preventDefault method) then the window will be closed, using NativeWindow.close () which was discussed in the previous part of this post
• Once the window has been closed, an Event.CLOSE event will be dispatched

As mentioned in the previous part of this series, if you want to implement your own “close” functionality, perhaps by creating your own application chrome, you should follow this same logic to give other objects elsewhere in your application a chance to cancel the closing operation if necessary.

NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGING
NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGE

Again, these events are related in a similar way to Event.CLOSING and Event.CLOSE. The events are dispatched as part of one of the following operations:

• Maximizing a window which was previously un-maximized
• Minimizing a window which was previously un-minimized
• Restoring a window from a maximized or minimized state

Unlike Event.CLOSING / Event.CLOSE, these events are defined within a subclass of Event, suggesting that there may be some added goodies within the event object that we can examine. As expected, there are a couple of properties available to tell us a little more about what is happening – to be more precise, the event object will tell us the value of the current state, and the value of the state we are moving to.

This is information is available by examining the NativeWindowDisplayStateEvent.beforeDisplayState and NativeWindowDisplayStateEvent.afterDisplayState properties. Both properties will be a string, matching one of the constants defined in the NativeWindowDisplayState class. These are:

• NativeWindowDisplayState.MAXIMIZED
• NativeWindowDisplayState.MINIMIZED
• NativeWindowDisplayState.NORMAL

So, for example, when a user clicks the maximize button in the system chrome, the sequence of events will be:

• A NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGING event is dispatched.
• If this event is not cancelled (by calling the event’s preventDefault method) then the state change will continue
• Once the display state has updated, a NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGE event will be dispatched

NativeWindowBoundsEvent.MOVING
NativeWindowBoundsEvent.MOVE

These events are dispatched whenever the position of the window within the system desktop is moved. This could be for one of a number of reasons:

• A system-controlled move operation, for example the user dragging the window around with the system chrome
• If the window is maximized
• If the window is minimized
• If the window is restored from maximized, or minimized state
• If the window is moved programmatically, by setting the x, y, or bounds properties

Again, the events here are defined in a custom subclass of Event, and this time the hidden treasures available to use are the beforeBounds and afterBounds properties, which obviously tell the us the “old” and “new” positions (and sizes, if we’re interested) of the window.

The sequence of events which would happen as part of a move operation would be:

• A NativeWindowBoundsEvent.MOVING event is dispatched.
• If this event is not cancelled (by calling the event’s preventDefault method) then the move operation will continue
• Once the window has been moved, a NativeWindowBoundsEvent.MOVE event will be dispatched

It’s worth noting that when a window is being dragged around by the user, it will repeatedly go through this cycle, moving the window in small steps. If at any stage, one of the NativeWindowBoundsEvent.MOVING events is cancelled, the move operation will terminate. This includes moves triggered by the NativeWindow.startMove () method discussed in the previous part of the post.

NativeWindowBoundsEvent.RESIZING
NativeWindowBoundsEvent.RESIZE

The events listed here work similarly to those dispatched as part of the move operation, although this time they apply to resize operations. Resize operations may occur for one of a number of reasons:

• A system-controlled resize operation, for example the user resizing the window via the system resize handles
• If the window is maximized
• If the window is minimised
• If the window is restored from maximized, or minimized state
• If the window is resized programmatically, by setting the width, height or bounds properties

The event type is the same as with the move operation, giving us access to the “old” and “new” sizes of the window. The sequence of events works in the same way too:

• A NativeWindowBoundsEvent.RESIZING event is dispatched.
• If this event is not cancelled (by calling the event’s preventDefault method) then the resize operation will continue
• Once the window has been resized, a NativeWindowBoundsEvent.RESIZE event will be dispatched

Lastly, as with the move operation, when a window is being resized by the user, it will repeatedly go through this cycle, resizing the window in small steps. If at any stage, one of the NativeWindowBoundsEvent.RESIZING events is cancelled, the resize operation will terminate. This includes resizes triggered by the NativeWindow.startResize () method discussed in the previous part of the post.

That’s all of ‘em

So that’s all of the events covered now. You can see how to handle various different operations that will happen during the lifetime of your window. You can react to (and cancel, if you wish) moves, resizes and the closing of your window. Most importantly, if creating your own application chrome, or implementing your own close/resize/move functionality, you should try and keep these operations cancelable. It’ll make things much easier down the line if, for example, you want to stop the user closing the window before the save their work.

Conclusion

I’ve now gone through all of the properties, methods and events exposed by a NativeWindow. As you can see, the API is fairly thorough, but extremely simple to use. It makes it easy to create, move, resize, hide, and reorder your windows, and to control how your windows will look and behave. I will try and carry this all through into an example at some point, but for now I hope this explanation has been fairly useful. Gimme a shout if there’s anything I’ve missed……

Once a NativeWindow has been created, you can call methods to move, resize, reposition, activate and close the window. All these methods are fairly simple, with the odd gotcha thrown in for good measure. So, here’s a description of each of these methods…

NativeWindow.activate ()

Calling NativeWindow.activate () firstly sets the visible of the window to true. Next, the window is brought to the front. Lastly, the window is given keyboard and mouse focus. Typically, you’d call the activate method shortly after creating it.

NativeWindow.close ()

This method, rather obviously, closes the window. This has several implications… First of all, once a window has been closed, it cannot be re-opened. References to a window that has been closed will exist, but some methods and properties of that window will no longer be available, and if accessed an exception will be thrown. Any DisplayObjects that were within the window, and not referenced anywhere else, will be available for Garbage Collection.

If you just want to close a window temporarily, consider setting its visible to false.

One other thing to mention here… when you call NativeWindow.close () no event is dispatched to signify the window is about to close. A Close event is sent out after the window has been closed, but if you want the action of closing the window to be preventable, you’ll need to send out a Closing event (take a look at air.Event.CLOSING which is more than suitable) giving interested parties a chance to set preventDefault on that event. If , and only if, the isDefaultPrevented () method of your custom Closing event returns false, then you can proceed to close your window.

NativeWindow.globalToScreen (globalPoint:Point)

This method is kind of like MovieClip.localToGlobal from days gone by, but takes things one step further. The method takes a Point object, representing co-ordinates relative to the origin of the NativeWindow’s stage and converts it to a Point object representing the same position relative to the top-left position of the system’s desktop.

NativeWindow.maximize ()
NativeWindow.minimize ()
NativeWindow.restore ()

This three methods are kind of similar, so I’ve grouped them here. The methods will attempt to maximize, minimize or restore the NativeWindow programmatically.

All three operations happen asynchronously, and you can detect the completion of these operations by listening out for a NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGE event.

Something important to note here, when the user tries to perform one of these three actions from the system chrome, a NativeWindowDisplayStateEvent.DISPLAY_STATE_CHANGING event is dispatched, giving interested parties a chance to cancel the operation (by calling preventDefault () ). To ensure this behaviour is also preventable when performing these options with code, you’ll need to manually dispatch a suitable DISPLAY_STATE_CHANGING event, and then investigate the event’s isDefaultPrevented () method before continuing the maximize / minimize / restore operation.

NativeWindow.notifyUser (type:String)

Assuming that NativeWindow.supportsNotification is true (see the previous post for more details), calling this method will trigger a visual cue to the user that something has happened. There are currently two different types of cue that you can trigger. NotificationType.INFORMATIONAL will trigger the cue for a short period of time, whereas NotificationType.CRITICAL will ensure the visial cue continues until the user brings focus to the window.

NativeWindow.orderInBackOf (window:NativeWindow)
NativeWindow.orderInFrontOf (window:NativeWindow)

These methods will move the window directly behind, or in front of, the window passed as the parameter. As always, some things to note.

• Attempting to re-order minimized or hidden windows is not possible.
• The methods will return true if the window was moved successfully, and false otherwise.
• If the window that you are moving behind, or in front of, has a different alwaysInFront property than the current window (see the previous post for more information), the window you are moving will have its alwaysInFront property changed to match this other window.
• When a window is reordered, it is not activated, and is not given the focus.

NativeWindow.orderToBack ()
NativeWindow.orderToFront ()

These methods will move the window behind, or in front of, all other visible windows. Things to note here include:

• Attempting to re-order minimized or hidden windows is not possible.
• The methods will return true if the window was moved successfully, and false otherwise.
• If the window’s alwaysInFront property is set to false, then calling orderToFront () will not move the window in front of any windows which have alwaysInFront set to true.
• Likewise, if the window’s alwaysInFront property is set to true then calling orderToBack () will not move the window behind any windows which have alwaysInFront set to false.

NativeWindow.startMove ()

Calling this method will trigger the start of a system-controlled move of the window. What this means is that you can create your own custom drag bar, listen to MouseEvent.MOUSE_DOWN events from that drag bar and then, in the event handler, call myNativeWindow.startMove () to begin the move process.

While the window is being moved, the window dispatches various events. This will be covered in more detail in the next part of this discussion. However, it’s worth mentioning here that a Move sequence can be terminated by handling, and then cancelling, the NativeWindowBoundsEvent.MOVING event.

The method returns true if the move process was successfully initiated, or false otherwise (for example, if the window was already maximized).

NativeWindow.startResize (edgeOrCorner:String)

This method is very similar to NativeWindow.startMove (). It allows you to create your own resize handles, listen to MouseMove.MOUSE_DOWN events from that resize handle, and then call myNativeWindow.startResize () from the event handler to begin the resize.

Again, while the window is being resized, it dispatches various events which will be covered in the next part of this discussion. As with moving a window, you can terminate the resize sequence by handling, then cancelling, the NativeWindowBoundsEvent.RESIZING event.

The method returns true if the resize process was successfully initiated, or false otherwise (for example, if the window was already maximized).

Unlike the startMove method, this method accepts a parameter. This parameter specifies which corner or edge of the window the resize should stem from. The possible values of this parameter are specified as constants in the NativeWindowResize class. The default is NativeWindowResize.BOTTOM_RIGHT.

That’s it!

That’s all of the public methods exposed by the NativeWindow class. You can see how to move, resize and re-order windows within the operating system, how to visually alert the user that the application needs their attention, how to activate the window, and how to close it. In the final part of this topic I’ll describe the various different Events that are dispatched by a NativeWindow during it’s lifetime.

Update: Part 3 of this post can be found here.

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.

The code I used in the previous post was this:

Fairly obviously, the NativeWindow constructor accepts an instance of NativeWindowInitOptions as its first parameter. In the previous example, I’m not doing anything fancy with the NativeWindowInitOptions instance that I create, I just create a new instance of the class and pass it to the NativeWindow constructor. As a result, all the various properties will have their default values, and the NativeWindow will be totally default. How terribly dull. Here’s a list of properties of NativeWindowInitOptions that you can play with to control how the NativeWindow will look and behave when it’s created….

NativeWindowInitOptions.minimizable

This is pretty obvious, but if the minimizable property is set to true then the NativeWindow will be minimizable. Otherwise, it won’t. This can have knock-on consequences on the appearance of the window. For example, when running on Windows, the value of this property can affect the window menu, and the window minimize button. If you don’t manually set this property, it will default to true.

NativeWindowInitOptions.maximizable

Again, if the maximizable property is set to true then the NativeWindow will be maximizable. This property may also affect the appearance of the window on some operating systems. This property also defaults to true.

NativeWindowInitOptions.resizable

The resizable property controls whether or not the window can be resized. When set to false, the little resize handles won’t appear in the corner of the window. Again, this property defaults to true.

(Note: When running on OS X, resizable and maximizable must both be set to false to prevent resizing. If you do one and not the other, it won’t work as expected).

NativeWindowInitOptions.systemChrome

The systemChrome property controls how the chrome of your NativeWindow will look. The default value is NativeWindowSystemChrome.STANDARD, and with this value the AIR application will adopt the look of a typical window in the operating system on which it’s running. So, when your AIR app runs on Windows, the chrome / menu bar / etc. will look like a typical Windows app. When the same app runs on OS X, it’ll look like a Mac app. The other possible value of this property is NativeWindowSystemChrome.NONE, which essentially hides the default system chrome, enabling you to create your own chrome for your NativeWindow.

NativeWindowInitOptions.transparent

This property, which defaults to false, determines whether or not the window supports transparency. If set to true, your window will be blended with the desktop beneath it. In other words, if you have content with an alpha of 0.5, your desktop will be visible through your window.

When this property is set to true, any areas of a window which do not contain a DisplayObject, or that only contain a DisplayObject with an alpha value under a certain threshold, will no longer react to mouse events. If a user clicks one of these “empty” areas, the mouse click will be handled by whatever happens to be sitting beneath your window, even though the click may have occurred within your application’s rectangle. The ‘threshold’ mentioned above varies between different operating systems but tends to fall between 0.05 and 0.01.

For those of you who may wish to create an application shaped like a clown’s face, this property is for you.
(Note: You can only set this property to false if you have also specified a value of NativeWindowSystemChrome.NONE for the systemChrome.)

NativeWindowInitOptions.type

There are currently three possible values for this property:

• NativeWindowType.NORMAL
  This is the default value for this property, and a NativeWindow of this type will use standard-sized chrome, and will also show up in the Windows taskbar or OS X window menu. Here is a screen shot of a very basic AIR window of this type running on OS X
  
  
  
• NativeWindowType.UTILITY
  A NativeWindow of this type still uses the system chrome, but in slimmed down form. Additionally, this type of window does not show up in the Windows taskbar or OS X window menu. Here is a screen shot of an AIR window of this type as a comparison.
  
  
  

  (Note: One thing I have noticed about windows of this type is that, on OS X at least, they are not minimizable by default. They are maximizable and resizable, but the minimize button is disabled)

• NativeWindowType.LIGHTWEIGHT
  A NativeWindow of this type has no system chrome, and in fact the value of the systemChrome mentioned above must be set to NativeWindowSystemChrome.NONE for this to work. An example of this type of window might be a notification message, similar to the one that pops up when you recieve a new IM in MSN Messenger, or a new email in Gmail Notifier.

These properties cannot be altered after the NativeWindow has been created

It is important to mention that each of these properties must be set on the NativeWindowInitOptions object before you attempt to create your NativeWindow. If you create your NativeWindow, passing the NativeWindowInitOptions object in as the parameter, and then subsequently attempt to alter the value of any of these properties, it will have no effect. Once the NativeWindow has been created, the properties mentioned above are set in stone.

Putting it all together

Finally, a code sample. The following snippet will create and activate a NativeWindow that supports transparency, has no chrome, is not maximizable, resizable or minimizable, and is of type NativeWindowType.UTILITY, meaning it will not be displayed in the Windows taskbar or OS X window menu. It then adds itself to the stage of the newly created window.

At some point soon I will try to write up the NativeWindow class in more detail, including listing the properties it offers, and the events that it dispatches.

I followed the workaround steps and it seemed to work OK, but when I first published my application… nothing happened. A little icon appeared in my dock, mysteriously titled adl (which I’ve since discovered stands for the AIR debug launcher), but no windows of Flash-based goodness appeared anywhere. After much digging around, I came across this entry in the Adobe Bug System and found the answer buried away in the comments.

When I’d previously created Flex-based AIR projects, I hadn’t really appreciated that the Flex framework was handling all of the window-creating shenanigans on my behalf. Just by making my root MXML tag a WindowedApplication, instead of a “normal” Application, the main AIR window was being created and activated automatically. When you’re not using the Flex framework, you have to do this stuff yourself.

As it turns out, the two most important classes involved in this process are flash.display.NativeWindow and flash.display.NativeWindowInitOptions. A NativeWindow is essentially the window you see on your desktop when you run an AIR application. This includes the menu bar (if any) and the system chrome (if any).

To successfully create and launch a window in AIR, you’ll need to create and activate a NativeWindow object, and then add your Document class (or some Sprite, at least) to that Window’s stage, accessible through the NativeWindow’s stage property. The code will look something like…

This code will create and activate an AIR window with default options, and add someSprite to the stage of that Window. From then on, you can continue with your code just as you would in a traditional Flash application and all will work as expected.

I’ll post more about the NativeWindow and NativeWindowInitOptions classes at some point soon….

(Update: Check out this post for more information about the NativeWindowInitOptions class)