class NativeWindow

Indicates whether native windows are supported on the client system.

Indicates whether OpenFL supports native window menus on the current computer system.

When NativeWindow.supportsMenu is true, a native menu will be displayed for a window when a NativeMenu object is assigned to the window menu property (unless the window systemChrome property is NativeWindowSystemChrome.NONE). Be sure to use the NativeWindow.supportsMenu property to determine whether the operating system supports native window menus. Using other means (such as Capabilities.os) to determine support can lead to programming errors (if some possible target operating systems are not considered).

Note: Assigning a menu to a window when NativeWindow.supportsMenu is false or when the window systemChrome property is NativeWindowSystemChrome.NONE is allowed, but does nothing.

Indicates whether OpenFL supports native windows with transparent pixels.

When NativeWindow.supportsTransparency is true, transparency in pixels of a native window will be honored, if the window transparent property is set to true. Opacity of all pixels will be set to 1 if NativeWindow.supportsTransparency is false, regardless of the value of the window transparent property. Fully transparent pixels will render as black when NativeWindow.supportsTransparency is false. Be sure to use the NativeWindow.supportsTransparency property to determine whether the operating system supports transparency. Using other means (such as Capabilities.os) to determine support can lead to programmin errors (if some possible target operating systems are not considered).

Note: The value of this property might change while an application is running, based on user preferences set for the operating system.

Creates a new NativeWindow instance and a corresponding operating system window.

The settings defined in the initOptions parameter cannot be changed after the window is created. Invalid initOptions settings will cause an illegal operation error to be thrown. Settings that are valid but not available on the current system will not throw an exception. The window capabilities specific to the current operating system can be detected, if desired, using the static NativeWindow members such as systemMaxSize.

The default window size is determined by the operating system, and windows are created in an invisible state. To prevent changes to the window from being visible, do not change the window visible property to true or call activate() until the window changes are finished.

Indicates whether this window is the active application window.

Use the activate() method to make a window active.

The size and location of this window.

The dimensions of a window include any system chrome. The dimensions of a window's stage are equal to the dimensions of the window, minus the size of any system chrome. Changing the width and height of the window will change the stage's stageWidth and stageHeight. The reverse also applies; changing the stage dimensions will change the window size.

A resize event is dispatched whenever the width or height of this window changes. Likewise, a move event is dispatched whenever the origin (x,y) of this window changes. On Mac OS and Windows, setting the bounds property directly will not dispatch a moving or resizing event. However, on Linux the NativeWindow does dispatch a moving and resizing events when you set the bounds property.

Setting the bounds property of a window is equivalent to setting its x, y, width, and height properties. Likewise, setting any of the individual dimensions is equivalent to setting the bounds property. When you set all the dimensions at the same time by using the bounds property, fewer events are dispatched.

The order in which the individual dimensions are set is not guaranteed. On Linux window managers that do not allow windows to extend off the desktop area, a change to an individual property may be blocked even though the net affect of applying all the property changes would have resulted in a legal window.

If the width or height specified is less than the minimum or greater than the maximum allowed width or height, then the window width or height is set to the closest legal size. The factors that determine the minimum and maximum width and height are the following:

• The minSize and maxSize properties of the NativeWindow object
• The minimum and maximum operating system limits, which are the values of NativeWindow.systemMinSize and NativeWindow.systemMaxSize.
• The maximum width and height of a window in Adobe AIR, which are each 4095 pixels. (In AIR 1.5 and earlier, the maximum width and height of a window is 2880 pixels each.)
• The minimum width and height required by any displayed system chrome.

Pixel values are rounded to the nearest integer when the position or dimensions of a window are changed.

Indicates whether this window has been closed.

Accessing the following properties on a closed window will throw an illegal operation error:

• title
• bounds
• x, y, width, height
• displayState
• visible

Likewise, calling the following methods on a closed window will also throw an illegal operation error:

• minimize()
• maximize()
• restore()
• startResize()
• startMove()

The display state of this window.

The height of this window in pixels.

The dimensions of a window include any system window chrome that is displayed. The height of the usable display area inside a window is available from the Stage.stageHeight property.

Changing the height property of a window is equivalent to changing the height through the bounds property.

If the height specified is less than the minimum or greater than the maximum allowed height, then the window height is set to the closest legal size. The factors that determine the minimum and maximum height are the following:

• The minSize.y and maxSize.y properties of the NativeWindow object
• The minimum and maximum operating system limits, which are the values of NativeWindow.systemMinSize.y and NativeWindow.systemMaxSize.y.
• The maximum height of a window in Adobe AIR, which is 4095 pixels (2880 pixels in AIR 1.5 and earlier).

On Linux, setting the height property is an asynchronous operation.

To detect the completion of the height change, listen for the resize event, which is dispatched on all platforms.

Pixel values are rounded to the nearest integer when the height of a window is changed.

The maximum size for this window.

The size limit is specified as the coordinates of a Point object. The point x property corresponds to the window width, the y property to the window height.

The maxSize restriction is enforced for window resizing operation invoked both through Haxe code and through the operating system.

Setting maxSize will change the window bounds if the current bounds are larger than the new maximum size.

If the width or height specified is greater than the maximum allowed width or height, then the window width is set to the closest legal size. The factors that determine the minimum and maximum width and height are the following:

• The maximum operating system limit, which is the value NativeWindow.systemMaxSize.
• The maximum width and height of a window in Adobe AIR, which is 4095 pixels for each. (In AIR 1.5 and earlier, the maximum width and height of a window is 2880 pixels each.)

Note: On some operating systems, such as Mac OS X, maximizing a window will only enlarge the window to the maxSize value even if the maximized window will be smaller than the operating system screen. The window will still be in the maximized display state.

See also:

• NativeWindow.maxSize

• NativeWindow.width

• NativeWindow.height

Reports the maximizable setting used to create this window.

The maximizable setting cannot be changed after a window is created.

Note: Some Linux window managers allow windows to be maximized by the user even when the maximizable property is set to false.

The minimum size for this window.

The size limit is specified as the coordinates of a Point object. The point x property corresponds to the window width, the y property to the window height.

Setting minSize, will change the window bounds if the current bounds are smaller than the new minimum size.

The minSize restriction is enforced for window resizing operations invoked both through ActionScript code and through the operating system.

Note: The width and height of any displayed system chrome may make it impossible to set a window as small as the specified minimum size.

See also:

• NativeWindow.maxSize

• NativeWindow.width

• NativeWindow.height

Reports the minimizable setting used to create this window.

The minimizable setting cannot be changed after a window is created.

Note: Some Linux window managers allow windows to be minimizable by the user even when the minimizable property is set to false.

The NativeWindow object that owns this window.

Window ownership is established when a window is created and cannot be changed. To create a window that has an owner, set the owning NativeWindow object as the owner property of the NativeWindowInitOptions object used to create the owned window.

Note: On Linux, some window managers do not display owned windows in front of the owning window when the owner is in fullscreen mode.

Reports the window renderMode setting used to create this window.

The value returned by NativeWindow.renderMode will be one of the constants defined in the NativeWindowRenderMode class.

The renderMode setting cannot be changed after a window is created.

Reports the resizable setting used to create this window.

The resizable setting cannot be changed after a window is created.

The Stage object for this window. The Stage object is the root object in the display list architecture used in OpenFL.

The stage is the root of the display list for the window. Add visual display objects to a window by adding them to the stage or to another object already in the display list of this stage. The stage dimensions are those of the window client area when the window uses system chrome. The stage dimensions are equal to the dimensions of the window if system chrome is not used.

Reports the system chrome setting used to create this window.

The values returned by NativeWindow.systemChrome will be one of the constants defined in the NativeWindowSystemChrome class.

The system chrome setting cannot be changed after a window is created.

The window title.

The title will appear in the system chrome for the window, if displayed, as well as in other system-dependent locations (such as the task bar).

Reports the transparency setting used to create this window.

The transparent property cannot be changed after a window is created Transparency affects both the visual appearance and the mouse behavior of the window. On Windows and Mac OS X, the window will not capture mouse events when the alpha value of the pixel is below a certain threshold, which varies between about .06 and .01 depending on th operating system. On Linux, the window will capture mouse events above completely transparent areas and therefore will prevent users from accessing other windows and items on the desktop.

Note: Window transparency cannot always be supported. If the user's operating system configuration is such that transparency is not available, the window will be created without transparency. Areas that would have been transparent are composited against black. Use the NativeWindow.supportsTransparency property to determine whether window transparency is supported.

Specifies whether this window is visible.

An invisible window is not displayed on the desktop, but all window properties and methods are valid.

By default, visible is set to false. To display a window, set visible to true or call NativeWindow.activate().

If this window has an owner, the visible state of that owning window determines whether this window is displayed. If the owning window is not displayed, then any owned windows are not displayed, even if their visible properties are true.

Note: On Mac OS X, setting visible to false on a minimized window will not remove the window icon from the dock. If a user subsequently clicks the dock icon, the window will return to the visible state and be displayed on the desktop.

The width of this window in pixels.

The dimensions reported for a native window include any system window chrome that is displayed. The width of the usable display area inside a window is available from the Stage.stageWidth property.

Changing the width property of a window is equivalent to changing the width through the bounds property.

If the width specified is less than the minimum or greater than the maximum allowed width, then the window width is set to the closest legal size. The factors that determine the minimum and maximum width are the following:

• The minSize.x and maxSize.x properties of the NativeWindow object
• The minimum and maximum operating system limits, which are the values of NativeWindow.systemMinSize.x and NativeWindow.systemMaxSize.x.
• The maximum width of a window in Adobe AIR, which is 4095 pixels (2880 pixels in AIR 1.5 and earlier).

On Linux, setting the width property is an asynchronous operation.

To detect the completion of the width change, listen for the resize event, which is dispatched on all platforms.

Pixel values are rounded to the nearest integer when the width of a window is changed.

The horizontal axis coordinate of this window's top left corner relative to the origin of the operating system desktop.

On systems with more than one monitor, x can be negative. If you save the value, perhaps to reposition a window at its previous location, you should always verify that the window is placed in a usable location when the position is restored. Changes in screen resolution or monitor arrangement can can result in a window being placed off screen. Use the Screen class to obtain information about the desktop geometry.

Changing the x property of a window is equivalent to changing the location through the bounds property.

On Linux, setting the x property is an asynchronous operation.

To detect the completion of the position change, listen for the move event, which is dispatched on all platforms.

Pixel values are rounded to the nearest integer when the x-coordinate of a window is changed.

The vertical axis coordinate of this window's top left corner relative to the upper left corner of the operating system's desktop.

On systems with more than one monitor, y can be negative. If you save the value, perhaps to reposition a window at its previous location, you should always verify that the window is placed in a usable location when the position is restored. Changes in screen resolution or monitor arrangement can can result in a window being placed off screen. Use the Screen class to obtain information about the desktop geometry.

Changing the y property of a window is equivalent to changing the location through the bounds property.

On Linux, setting the y property is an asynchronous operation.

To detect the completion of the position change, listen for the move event, which is dispatched on all platforms.

Pixel values are rounded to the nearest integer when the y-coordinate of a window is changed.

Activates this window.

Activating a window will:

• Make the window visible
• Bring the window to the front
• Give the window keyboard and mouse focus

On Linux, activate() is an asynchronous operation.

The NativeWindow object dispatches an activate event on all platforms.

Closes this window.

A close event is dispatched as soon as the close operation is complete. A closing event will not be dispatched. If cancellation of the close operation should be allowed, manually dispatch a closing event and check whether any registered listeners cancel the default behavior before calling the close() method.

When a window is closed, any windows that it owns are also closed. The owned windows do not dispatch closing events.

If display object instances that are currently in the window are not referenced elsewhere they will be garbage collected and destroyed, except on the initial application window created by AIR. To allow display objects on the initial window to be garbage collected, remove them from the window stage.

After being closed, the NativeWindow object is still a valid reference, but accessing most properties and methods will throw an illegal operation error.

Closed windows cannot be reopened. If the window is already closed, no action is taken and no events are dispatched.

Note: to hide a window without closing it, set the window's visible property to false.

Returns a list of the NativeWindow objects that are owned by this window.

You cannot change ownership of NativeWindows by adding or removing objects from the returned vector. Window ownership cannot be changed after a window is created.

Maximizes this window.

Calling maximize() method dispatches a displayStateChange event, and, if applicable, a move and a resize event. Whereas system chrome will dispatch a displayStateChanging event that can be canceled when a maximize command is initiated by a user, your maximize logic must manually implement this behavior, if desired.

The maximize() method executes asynchronously. To detect the completion of the state change, listen for the displayStateChange event. If the window is already maximized, no action is taken and no events are dispatched.

OS behavior notes:

• On operating systems, such as Mac OS X, in which maximizing a window does not also prevent resizing, calling maximize() will zoom the window to fill the screen, but will not prevent subsequent resizing of the window. Resizing a zoomed window will also restore the display state.
• On some operating systems, such as Mac OS X, as well as on some Linux window managers, maximizing a window will not expand the window beyond the width and height specified in the maxSize property. On others, the window will expand to fill the screen even if the screen is larger than the maxSize.
• Some Linux window managers do not allow utility windows to be maximized.

Minimizes this window.

Calling minimize() dispatches a displayStateChange event, and, if applicable, a move and a resize event. Whereas system chrome will dispatch a displayStateChanging event that can be canceled when a minimize command is initiated by a user, calling minimize() directly does not. Your minimize logic may manually implement this behavior, if desired.

The minimize() method executes asynchronously. To detect th completion of the state change, listen for the displayStateChange event, which is dispatched on all platforms. If the window is already minimized, no action is taken and no events are dispatched.

Any windows owned by this window are hidden when it is minimized. The owned windows do not dispatch displayStateChanging or displayStateChange events.

Notes:

• On Windows, minimizing an invisible window (visible == false), will make the window visible.
• Some Linux window managers do not allow utility windows to be minimized.

Restores this window from either a minimized or a maximized state.

Calling restore() dispatches a displayStateChange event, and, if applicable, a move and a resize event. Whereas system chrome will dispatch a displayStateChanging event that can be canceled when a restore command is initiated by a user, your restore logic must manually implement this behavior, if desired.

If the window is already in the NativeWindowDisplayState.NORMAL state, no action is taken and no events are dispatched.

To detect the completion of the state change, listen for the displayStateChange event, which is dispatched on all platforms.