NativeWindow – using AIR windows with Actionscript (part 2 of 3)
In the previous post I listed the public properties exposed by an instance of NativeWindow. In this post, I’ll be going through NativeWindow’s public methods. The third and final part of this series will explain the Events dispatched by a NativeWindow during its lifetime.
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.