Darrell Loverin (Dev)
Robert Vollmar (QA)

Functional and Design Specification

Glossary

N/A

Summary and Background

The advantage of using skins for the top level application is that you can change the look of your applications by substituting a new skin via CSS. This ability allows you to customize top-level applications beyond normal CSS attributes (border, padding, margins, background color) without the need to modify the application mxml itself.

FxApplication allows a developer to put top-level graphic elements and layout elements directly into the mxml file without the need to wrap them in a Group element.

Usage Scenarios

Jane is writing a new Gumbo application. Jane uses an FxApplication element as the root of the mxml file instead of Application and specifies the 2009 namespace. Jane can add Gumbo content without a problem but some halo content (faceless components such as RadioButtonGroup) needs to go in the declarations section or a runtime exception will result.

Detailed Description

This section discusses proposed changes to the Application and FxApplication API. It also discusses solutions to a couple of coding issues that have surfaced due the fact we will have two top level application classes.

Application API not brought forward to FxApplication

- Properties
  - application: the plan is to deprecate Application.application
  - controlBar
  - historyManagementEnabled
  - resetHistory
- Methods
  - addToCreationQueue()
- Styles
  - No styles are brought forward
- Events
  - N/A

API in FxApplication not in Application

- Properties
  - backgroundColor
  - colorCorrection - convenience method to set stage.colorCorrection.
- Methods
  - N/A
- Styles
  - None
- Events
  - N/A

Deprecate Application.application

With the addition of FxApplication there are now two root application classes. Code that calls Application.application needs to be changed to FlexGlobals.topLevelApplication. The advantage of this change is using FlexGlobals.topLevelApplication does not link the the Application class. If only FxApplication is being used, linking in Application increases the size of the application.

API Description

The FxApplication API is the same as Application except where noted in detailed description. The base class of FxApplication is FxContainer whereas the base class of Application is LayoutContainer.

package mx.core
{

public class FxApplication extends FxContainer

{

//----------------------------------
//  backgroundColor
//----------------------------------
    
[Bindable("backgroundColorUpdated")]

/**
 *  Background color of a component. 
 *  This property specifies the background color, both while the application
 *  loads, and while it is running.  
 */
public function get backgroundColor():uint;
public function set backgroundColor(value:uint):void;

//----------------------------------
// colorCorrection
//----------------------------------

[Inspectable(enumeration="default,off,on", defaultValue="default" )]
    
/**
 *  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. Also, the <code>colorCorrection</code> property cannot be set if the
 *  application does not have access to the stage's <code>colorCorrection</code> property.
 *
 *  @default ColorCorrection.DEFAULT
 */
public function get colorCorrection():String;
public function set colorCorrection(value:String):void;


...

}

package mx.core
{

public class Application extends LayoutContainer

{
[Deprecated(replacement="FlexGlobals.topLevelApplication", since="4.0")]
public static function get application():Object

...

}

B Features

Examples and Usage

An FxApplication with both Gumbo and Halo components

<?xml version="1.0" encoding="utf-8"?>
<FxApplication xmlns="http://ns.adobe.com/mxml/2009"
             backgroundColor="white"
             width="800" height="600">
    <layout>
        <VerticalLayout />
    </layout>
    <Ellipse width="10" height="10" y="3">
        <fill>
            <RadialGradient>
                <GradientEntry color="0xAAAAAA" />
                <GradientEntry color="0x336699" />
            </RadialGradient>
        </fill>
    </Ellipse>
    <Button label="halo button" />
    <FxButton label="gumbo button" />
</FxApplication>

An FxApplication with a custom skin

The most flexible way to specify a custom skin for an application is to specify a CSS file using a Style tag. The skin can be changed later by modifying the CSS file without the need to modify the application source.

<?xml version="1.0" encoding="utf-8"?>
<FxApplication xmlns="http://ns.adobe.com/mxml/2009"
             width="800" height="600" >
...
<Style source="MyFlex4.css" />
...
</FxApplication>

The CSS file

The CSS file specifies the custom skin to use for the application.

MyFlex4
{
    skinClass: ClassReference("MyApplicationSkin");
    backgroundColor: #FFFFFF;
}

The Custom Skin

To make a custom skin, FxApplicationSkin.mxml was copied from FxApplicationSkin.mxml and a BitmapGraphic was added to the end of the skin. The BitmapGraphic is positioned in the bottom, right corner of the application.

<Skin xmlns="http://ns.adobe.com/mxml/2009">

    <Metadata>
    	[HostComponent("mx.components.FxApplication")]
    </Metadata> 
    
    <states>
    	<State name="normal" />
    	<State name="disabled" />
    </states>
    
	<!-- fill -->
    <Rect id="backgroundRect" left="0" right="0" top="0" bottom="0">
        <fill>
            <SolidColor color="{fxComponent.backgroundColor}" />
        </fill>
    </Rect>
        
    <Group id="contentGroup" left="0" right="0" top="0" bottom="0" />

    <BitmapGraphic source="@Embed('Nokia_6630.png')"
                   right="5" bottom="5" alpha="0.2"
                    />

</Skin>

Additional Implementation Details

None.

Prototype Work

FxApplication has been in the Gumbo for some time. Only incremental changes are being proposed.

Compiler Work

The compiler generates some style code for top-level applications. In Flex3 the style code was generated the the source file was a top-level application and subclasses the "LayoutContainer" class. The compiler will look to make the test for a Gumbo container more generic then testing for "FxApplication. The compiler team thinks the intent of the original tests are to test for a Flex Framework Application as opposed to a non-Framework Application. So instead of testing for "FxApplication" the compiler will test Gumbo applications to see if they implement ISimpleStyleClient.