lowpitch.com

NativeWindowInitOptions – configure your AIR NativeWindow

In a previous post I listed some code to create and activate a NativeWindow in an Actionscript AIR project without really explaining what was going on behind the scenes. In this post, I’ll explain a little more about the NativeWindowInitOptions class, and how you can control the appearance and behaviour of the NativeWindow that you create.

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.