Darrell Loverin (Dev)
Jody Zhang (QA)

Functional and Design Specification

Glossary

  • Flex Chrome - Application chrome drawn using Flex/Flash instead of the native operating system. The Flex Chrome consists of a title bar, a border, and a gripper for resizing the window.
  • System Chrome - Application chrome drawn by the native operating system using its native widgets. The chrome consists of a title bar and a window frame for resizing the window.

Summary and Background

The Spark Window component is a skinnable version of the Halo Window component. The Spark Window has most of the properties and methods of the Halo Window. The main difference between the Spark and Halo versions of Window is the Spark component does not support the styles on the Halo component. Instead, the styles are embedded into the component's skin. If a developer wants to use different styles, they can easily create a custom skin.

The Spark Window component is designed to be used with the Spark WindowedApplication.

Usage Scenarios

Use spark.components.Window to create additional native windows in an AIR application. The first window will always be a WindowedApplication. The advantage of using a Spark Window over a Halo Window is the Spark Window can be easily skinned and Spark graphic elements may be placed directly in the application without the need to wrap them in a Group tag.

Detailed Description

Most of the properties and methods are the same as the Halo component. All the styles on the Halo component are not available in the Spark component.

API change to Halo Window, mx.core.Window

Changed getWindow to return IWindow.

With the addition of the Spark Window, there are now two kinds of Window components, Spark and Halo. The getWindow API used to return a Halo Window. The API has been changed to return IWindow so the actual type can be either a Spark Window or a Halo Window.

public static function getWindow(component:UIComponent):Window

to

public static function getWindow(component:UIComponent):IWindow

Differences between Spark and Halo Window Components

Properties

Added backgroundColor:uint

The backgroundColor of the Window. Same implementation as in spark.components.Application.

Added colorCorrection:uint

The value of the stage's colorCorrection property. Same implementation as in spark.components.Application.

Added resizeAffordance

The number of pixels from the edge of the application where a mouse click can initiate a resize of the application.

Changed statusBar:UIComponent

The type of the status bar was changed from UIComponent to IVisualElement.

Removed statusBarFactory:IFactory

Used for Halo custom status bars. Not needed in Spark.

Removed statusBarStyleFilters:Object

Spark styles are created within the skin.

Changed titleBar:UIComponent

The type of titleBar has changed from UIComponent to TitleBar.

Removed titleBarFactory:IFactory

The titleBar will be created by the Spark infrastructure.

Removed titleBarStyleFilters:Object

The titleBar does not support any external styles.

Methods

No changes.

Events

No changes.

Styles

All REMOVED:

buttonAlignment="auto"
buttonPadding="2"
closeButtonSkin="mx.skins.halo.windowCloseButtonSkin"
gripperPadding="3"
gripperStyleName="gripperStyle"
headerHeight="<i>undefined</i>"
maximizeButtonSkin="mx.skins.halo.WindowMaximizeButtonSkin"
minimizeButtonSkin="mx.skins.halo.WindowMinimizeButtonSkin"
restoreButtonSkin="mx.skins.halo.WindowRestoreButtonSkin"
showFlexChrome="true"
statusBarBackgroundColor="0xC0C0C0"
statusBarBackgroundSkin="mx.skins.halo.StatusBarBackgroundSkin"
statusTextStyleName="<i>undefined</i>"
titleAlignment="auto"
titleBarBackgroundSkin="mx.skins.halo.ApplicationTitleBarBackgroundSkin"
titleBarButtonPadding="5"
titleBarColors="[ 0x000000, 0x000000 ]"
titleTextStyleName="<i>undefined</i>"

Effects

No changes.

Skins

The Window component can use the same skins as the WindowedApplication component. The shared skins are the spark.skins.default.WindowedApplicationSkin and spark.skins.default.FlexChromeSkin skins. The skin sharing is accomplished by declaring the HostComponent to be of type Object. The backgroundColor property is then accessed thru the hostComponent member.

    ...

    <fx:Metadata>
      [HostComponent("Object")]
    </fx:Metadata>

    ...

    <!-- layer 1: background fill -->
    <s:Rect id="backgroundRect" left="1" right="1" top="1" bottom="1" >
        <s:fill>
            <s:SolidColor id="bgFill" color="{hostComponent.backgroundColor as uint}" />
        </s:fill>
    </s:Rect>

    ...

The default skin is spark.skins.default.WindowedApplicationSkin. If you want to use the Flex Chrome, then override the skinClass style and set it to the Flex Chrome Skin. One way to do this is to add a Style block to your application. For example:

<fx:Style >

@namespace "library://ns.adobe.com/flex/spark";
Window
{
     skinClass: ClassReference("spark.skins.default.FlexChromeSkin");
}

</fx:Style>

API Description

Parts of the API that are the same are not shown.

package spark.components
{

 ...

//--------------------------------------
//  SkinStates
//--------------------------------------

/**
 *  The application is enabled and inactive.
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
[SkinState("normalActive")]

/**
 *  The application is disabled and inactive.
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
[SkinState("disabledInactive")]


/**
 *  The Window is a top-level container for additional windows
 *  in an AIR desktop application.
 *
 *  <p>The Window container is a special kind of container in the sense
 *  that it cannot be used within other layout containers. An spark.components.Window
 *  component must be the top-level component in its MXML document.</p>
 *
 *  <p>The easiest way to use a Window component to define a native window is to
 *  create an MXML document with an <code>&lt;s:Window&gt;</code> tag
 *  as the top-level tag in the document. You use the Window component
 *  just as you do any other container, including specifying the layout
 *  type, defining child controls, and so forth. Like any other custom
 *  MXML component, when your application is compiled your MXML document
 *  is compiled into a custom class that is a subclass of the Window
 *  component.</p>
 *
 *  <p>In your application code, to make an instance of
 *  your Window subclass appear on the screen you first create an instance
 *  of the class in code (by defining a variable and calling the <code>new
 *  MyWindowClass()</code> constructor. Next you set any properties you wish
 *  to specify for the new window. Finally you call your Window component's
 *  <code>open()</code> method to open the window on the screen.</p>
 *
 *  <p>Note that several of the Window class's properties can only be set
 *  <strong>before</strong> calling the <code>open()</code> method to open
 *  the window. Once the underlying NativeWindow is created, these initialization
 *  properties can be read but cannot be changed. This restriction applies to
 *  the following properties:</p>
 *
 *  <ul>
 *    <li><code>maximizable</code></li>
 *    <li><code>minimizable</code></li>
 *    <li><code>resizable</code></li>
 *    <li><code>systemChrome</code></li>
 *    <li><code>transparent</code></li>
 *    <li><code>type</code></li>
 *  </ul>
 *
 *  @mxml
 *
 *  <p>The <code>&lt;s:Window&gt;</code> tag inherits all of the tag
 *  attributes of its superclass and adds the following tag attributes:</p>
 *
 *  <pre>
 *  &lt;s:Window
 *    <strong>Properties</strong>
 *    alwaysInFront="false"
 *    backgroundColor="white"
 *    colorCorrection="default"
 *    height="100"
 *    maxHeight="10000"
 *    maximizable="true"
 *    maxWidth="10000"
 *    menu="<i>null</i>"
 *    minHeight="0"
 *    minimizable="true"
 *    minWidth="0"
 *    resizable="true"
 *    showGripper="true"
 *    showStatusBar="true"
 *    showTitleBar="true"
 *    status=""
 *    systemChrome="standard"
 *    title=""
 *    titleIcon="<i>null</i>"
 *    transparent="false"
 *    type="normal"
 *    visible="true"
 *    width="100"
 * 
 *    <strong>Effects</strong>
 *    closeEffect="<i>No default</i>"
 *    minimizeEffect="<i>No default</i>"
 *    unminimizeEffect="<i>No default</i>"
 * 
 *    <strong>Events</strong>
 *    applicationActivate="<i>No default</i>"
 *    applicationDeactivate="<i>No default</i>"
 *    closing="<i>No default</i>"
 *    displayStateChange="<i>No default</i>"
 *    displayStateChanging="<i>No default</i>"
 *    moving="<i>No default</i>"
 *    networkChange="<i>No default</i>"
 *    resizing="<i>No default</i>"
 *    windowComplete="<i>No default</i>"
 *    windowMove="<i>No default</i>"
 *    windowResize="<i>No default</i>"
 *  /&gt;
 *  </pre>
 * 
 *  @see spark.components.WindowedApplication
 * 
 *  
 *  @langversion 3.0
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
public class Window extends SkinnableContainer implements IWindow
{
    include "../../mx/core/Version.as";

    //--------------------------------------------------------------------------
    //
    //  Class methods
    //
    //--------------------------------------------------------------------------

    /**
     *  Returns the Window to which a component is parented.
     *
     *  @param component the component whose Window you wish to find.
     *  
     *  @langversion 3.0
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public static function getWindow(component:UIComponent):IWindow
    {
        if (component.systemManager is WindowedSystemManager)
            return WindowedSystemManager(component.systemManager).window;
        
        return null;
    }

    //--------------------------------------------------------------------------
    //
    //  Constructor
    //
    //--------------------------------------------------------------------------

    /**
     *  Constructor.
     *  
     *  @langversion 3.0
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function Window();

    //--------------------------------------------------------------------------
    //
    //  Skin Parts
    //
    //--------------------------------------------------------------------------

    //----------------------------------
    //  gripper
    //----------------------------------

    /**
     *  A skin part that defines the gripper button used to resize the window. 
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    [SkinPart (required="false")]
    public var gripper:Button;

    //----------------------------------
    //  statusBar
    //----------------------------------

    /**
     *  The SkinPart that displays the status bar.
     *  
     *  @langversion 3.0
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    [SkinPart (required = "false")]
    public var statusBar:IVisualElement;

    //----------------------------------
    //  statusText
    //----------------------------------

    /**
     *  A reference to the UITextField that displays the status bar's text.
     *  
     *  @langversion 3.0
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    [SkinPart (required="false")]
    public var statusText:TextGraphicElement;
    
    //----------------------------------
    //  titleBar
    //----------------------------------

    /**
     *  The UIComponent that displays the title bar.
     *  
     *  @langversion 3.0
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    [SkinPart (required="false")]
    public var titleBar:TitleBar;

     ...

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    //----------------------------------
    //  backgroundColor
    //----------------------------------
    
    /**
     *  Background color of a component. 
     *  This property specifies the background color, both while the application
     *  loads, and while it is running.
     *
     *  @default 0xFFFFFF
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get backgroundColor():uint;

    /**
     * @private
     */
    public function set backgroundColor(value:uint):void;

    //----------------------------------
    //  colorCorrection
    //----------------------------------
    
   /**
    *  The value of the stage's <code>colorCorrection</code> property. If this application
    *  does not have access to the stage's <code>colorCorrection</code> property, 
    *  the value of the <code>colorCorrection</code> property will be reported as 
    *  null. Only the main application is allowed to set the <code>colorCorrection</code>
    *  property. If a sub-application's needs to set the color correction property it will
    *  need to set it via the main application's instance, either directly using an object
    *  instance or via an event (there is no framework event for this purpose).  
    *
    *  @default ColorCorrection.DEFAULT
    *  
    *  @langversion 3.0
    *  @playerversion Flash 10
    *  @playerversion AIR 1.5
    *  @productversion Flex 4
    */
    public function get colorCorrection():String;

    //---------------------------------
    //  resizeAffordance
    //---------------------------------

    /**
     *  Provides a margin of error around the application's border so a resize
     *  and be more easily started. A click on the application is considered a
     *  click on the application's border if the click occurs with the resizeAffordance
     *  number of pixels from the outside edge of the application's window.
     *  
     *  @langversion 3.0
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public var resizeAffordance:Number = 6;
        
    ...

Backwards Compatibility

API change to Halo Window, mx.core.Window

Changed getWindow to return IWindow

There are two kinds of Window components, Spark and Halo. The API used to return a Halo Window. The API has been changed to return IWindow so the actual type can be either a Spark Window or a Halo Window.

public static function getWindow(component:UIComponent):Window

to

public static function getWindow(component:UIComponent):IWindow

QA

Run the same tests as run against the Halo Window. Then test creating new skins for the Spark Window. Test adding Spark components to the Spark Window.

You must be logged in to comment.