About themes

A theme defines the look and feel of an application’s visual components. A theme can define something as simple as the color scheme or common font for an application, or it can be a complete reskinning of all the components used by the application.

The default theme for Flex 4 components is Spark. All controls in an application built with Flex 4 use the Spark theme. Even MX controls have a Spark look and feel in a Flex 4 application.

The Spark theme is a combination of styles and skin classes that define the appearance of the components in the spark.components package. This theme is defined in the defaults.css style sheet in the spark.swc file. Spark components use the skin classes in the spark.skins.spark.* package. MX components use the skin classes in the mx.skins.spark.* package.

For Flex 3, the default theme was called Halo. The components that used the Halo theme are in the mx.controls.* package. They are typically referred to as MX components. In Flex 4, however, the MX components use the Spark theme to define their appearance by default. This is set in the defaults.css file in the framework.swc file.

To use the Halo theme in a Flex 4 application, you can use the theme compiler option to point to the Halo theme SWC file, or you can set the compatibility-version compiler option to 3.0.0. If you use the Halo theme, then the Halo theme is applied only to MX components in your application. The Spark components continue to use the Spark theme unless you specifically override them.

Themes usually take the form of a SWC file. However, themes can also be a CSS file and embedded graphical resources, such as symbols from a SWF file. Theme SWC files can also be compiled into style SWF files so that they can be loaded at run time. For more information, see Using theme SWC files as run-time style sheets.

To apply a theme SWC file to your application, use the instructions in Using themes. To create your own theme, use the instructions in Creating a theme SWC file.

Flex also includes several other predefined themes that you can apply to your applications. For more information, see About the included theme files.

Using themes

Themes generally take the form of a theme SWC file. These SWC files contain style sheets and skinning assets. You use the assets inside theme SWC files for programmatic skins or graphical assets, such as SWF, GIF, or JPEG files. Themes can also contain just stand-alone CSS files.

Packaging a theme as a SWC file rather than as a loose collection of files has the following benefits:

  • SWC files are easier to distribute.

  • SWC files cannot be modified and reapplied to the application without recompiling.

  • SWC files are precompiled. This reduces application compile time, compared to compile time for skin classes that are not in a SWC file.

You apply a theme to your application by specifying the SWC or CSS file with the theme compiler option. The following example uses the mxmlc command-line compiler to compile an application that uses the BullyBuster theme SWC file:

mxmlc -theme theme/BullyBuster.swc MainApp.mxml

When compiling an application by using options in the flex-config.xml file, you specify the theme as follows:

<compiler> 
    <theme> 
        <filename>c:/theme/BullyBuster.swc</filename> 
    </theme> 
</compiler>

When you add a SWC file to the list of themes, the compiler adds the classes in the SWC file to the application’s library-path, and applies any CSS files contained in the SWC file to your application. The converse is not true, however. If you add a SWC file to the library-path, but do not specify that SWC file with the theme option, the compiler does not apply CSS files in that SWC file to the application.

For more information, see Flex compilers.

Themes are additive. You can specify more than one theme file to be applied to the application. If there are no overlapping styles, both themes are applied completely. The ordering of the theme files is important, though. If you specify the same style property in more than one theme file, Flex uses the property from the last theme in the list. In the following example, style properties in the Wooden.css file take precedence, but unique properties in the first two theme files are also applied:

<compiler> 
    <theme> 
        <filename>../themes/Institutional.css</filename> 
        <filename>../themes/Ice.css</filename> 
        <filename>../themes/Wooden.css</filename> 
    </theme> 
</compiler>
On the command line, you can use the += operator with the theme compiler option to apply themes additively. The following example applies the BullyBuster.swc theme, in addition to the default theme:
mxmlc -theme+=themes/BullyBuster.swc MainApp.mxml

Creating color schemes

One common way to use themes is to create a color scheme for your application. This color scheme can be used to blend your application into its surrounding website, or define its overall look and feel.

In Spark applications, most styles are inheritable styles. This means that you can set any style on any level of the containment hierarchy. The inheritable styles will be inherited by all controls that are within the container that you set it on. One common use of this is to set styles on the Application tag so that the entire application uses those styles.

The following table describes the color styles that you use most often to create a color scheme in Spark applications:

Property

Description

backgroundColor

The background color of the application.

chromeColor

The base color of the component. The default skins are based on various shades of gray. The chromeColor style is applied as a color transformation (tinting), which preserves all of the visual fidelity of the default appearance. Items colorized by other color style values are not affected by chromeColor.

color

The color of text in a component.

contentBackgroundColor

The color of the content area of components that contain content.

focusColor

The color of the focus glow.

rollOverColor

The background color of items when the mouse is positioned over the item.

selectionColor

The background color of selected items in a drop down list.

symbolColor

The color of symbols or glyphs. For example, the arrows on a scroll bar or the check mark in a CheckBox control.

The following example lets you toggle between two color schemes. It shows that the colors are inherited by all Spark controls in that application.
<?xml version="1.0" encoding="utf-8"?>
<!-- styles/SparkThemeColorExample.mxml -->
<s:Application
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">
    <fx:Script>
        <![CDATA[
            import mx.core.FlexGlobals;
            import mx.events.IndexChangedEvent;
            
            private function changeStyleSettings(e:Event):void {
                if (e.currentTarget.selectedItem == "Gray") {                    
                    FlexGlobals.topLevelApplication.setStyle("backgroundColor", 0x333333);                    
                    FlexGlobals.topLevelApplication.setStyle("chromeColor", 0x4C4C4C);
                    FlexGlobals.topLevelApplication.setStyle("color", 0xCCCCCC);
                    FlexGlobals.topLevelApplication.setStyle("contentBackgroundColor", 0x555555);
                    FlexGlobals.topLevelApplication.setStyle("symbolColor", 0xFFFFFF);
                    FlexGlobals.topLevelApplication.setStyle("rollOverColor", 0x666666);
                    FlexGlobals.topLevelApplication.setStyle("selectionColor", 0x999999);
                    FlexGlobals.topLevelApplication.setStyle("focusColor", 0xEEEEEE);
                } else {
                    FlexGlobals.topLevelApplication.setStyle("backgroundColor", 0xCCCC99);                                        
                    FlexGlobals.topLevelApplication.setStyle("chromeColor", 0x999966);
                    FlexGlobals.topLevelApplication.setStyle("color", 0x996600);
                    FlexGlobals.topLevelApplication.setStyle("contentBackgroundColor", 0xFFFFCC);
                    FlexGlobals.topLevelApplication.setStyle("symbolColor", 0x663300);
                    FlexGlobals.topLevelApplication.setStyle("rollOverColor", 0xFFEE88);
                    FlexGlobals.topLevelApplication.setStyle("selectionColor", 0xFFCC66);
                    FlexGlobals.topLevelApplication.setStyle("focusColor", 0xCC9900);                    
                }
            }
        ]]>
    </fx:Script>

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <s:Button label="Button"/>
    <s:ToggleButton label="Toggle Button"/>
    <s:CheckBox label="CheckBox" selected="true"/>
    <s:RadioButton label="RadioButton" selected="true"/>
    <s:NumericStepper/>
    <s:TextInput/>
    <s:TextArea/>
    <s:DropDownList id="myDropDown" selectedIndex="0" 
        change="changeStyleSettings(event);">
        <s:dataProvider>
            <s:ArrayList source="[Gray,Brown]"/>
        </s:dataProvider>
    </s:DropDownList>    
</s:Application>

The executing SWF file for the previous example is shown below:

You can affect the general coloring of MX components without creating a new theme or changing many of the style properties in the Halo theme. You do this with the themeColor property. For more information, see Creating a Halo theme.

A useful utility for developing color schemes is Kuler. This utility helps users create new color schemes and share them with other users. For more information, see the Kuler online application at http://kuler.adobe.com/.

About the included theme files

Flex includes several themes that you can use. Some are for version compatibility, some are for testing, and some are purely for visual appearance. Most themes are located in the sdk_install_dir/frameworks/themes directory for the SDK. For Flash Builder, the themes are located in the flash_builder_install_dir/sdks/sdk_version/frameworks/themes directory. Other themes are in the /sdk_version/samples/themes directory.

The following table describes these themes:

Theme

Description

Aeon Graphical

Contains the AeonGraphical.css file and the AeonGraphical.swf file. This is the graphical version of the Halo theme, which is only used by MX components.

The source FLA file for the graphical assets is in the AeonGraphical Source directory. You change the graphical assets in this file by using the Flash IDE. You must ensure that you export the SWF file, which is used by the theme in Flex.

Halo

The Halo theme uses the halo.swc theme file and the classes in the mx.skins.halo package. For more information about the default theme assets, see About the default style sheets.

Ice

Contains the Ice.css file.

Institutional

Contains the Institutional.css file.

Mobile

Contains the defaults.css file for mobile applications. For more information, see Mobile theme.

Sample themes

The themes in the samples/themes directory include arcade, cobalt, and graphite. These theme files should be considered sample quality. Before you use them in production applications, be sure to test them thoroughly.

Smoke

Contains the Smoke.css file and a background JPEG file.

Wireframe

An alternate theme for the Spark components. This theme gives a simple, wireframe appearance to an application. It might be appropriate to use it when developing a prototype or “proof of concept” application. This theme is also useful as a starting point to write custom skins, particularly if they are not styleable. This is because the skin classes in the Wireframe theme file are simpler than their Spark counterparts.

Wooden

Contains the Wooden.css file and a background JPEG file.

To apply a theme to an application, you use the theme compiler option, as the following example shows:
mxmlc -theme=c:\Flex\frameworks\themes\Halo\halo.swc MyApp.mxml

In addition to the basic themes, Flex also includes the MXFTEText.css theme file. This file is located in the frameworks directory. You use this theme if you want to use embedded fonts with MX controls in your Flex 4 applications. For more information, see Embedding fonts with MX components.

Another theme file, MXCharts.css, is meant to be used with MX-only applications that contain charting components.

Creating a theme SWC file

To build a theme SWC file, you create a CSS file, and include that file plus the graphical and programmatic assets in the SWC file. To do this, you use the include-file option of the compc utility.

A good starting point for creating a new theme is to customize the default CSS files for the Spark and MX components. For Spark components, customize the defaults.css file in the spark.swc file. For MX components, customize the defaults.css file in the framework.swc file. The following sections describe these steps in detail.

Creating a theme style sheet

A theme typically consists of a style sheet and any assets that the style sheet uses. These assets can be graphic files or programmatic skin classes. For the Spark theme, the assets are skin classes that use a combination of MXML and FXG syntax to draw the skin. For the Halo theme, the assets are typically ActionScript class files that extend Halo skin classes.

To add MXML skins to a Spark theme file, you use a ClassReference statement to specify the class name (not the file name) for each component. You must also specify a namespace and the Spark skin class for that component. The following is a typical CSS file that defines a small Spark theme:
@namespace s "library://ns.adobe.com/flex/spark"; 
s|Button { 
    skinClass: ClassReference("ButtonTransitionSkin"); 
} 
s|CheckBox { 
    skinClass: ClassReference("CheckBoxTransitionSkin"); 
}

To add programmatic skin classes to a Halo theme’s CSS file, you specify a class for each of the component’s states, as the following example shows:

@namespace mx "library://ns.adobe.com/flex/mx"; 
mx|Button { 
    upSkin:ClassReference('myskins.ButtonSkin'); 
    downSkin:ClassReference('myskins.ButtonSkin'); 
    overSkin:ClassReference('myskins.ButtonSkin'); 
}

For information about creating custom Spark skins, see Spark Skinning. For information about creating custom Halo skins, see Creating programmatic skins for MX components.

To add graphic files to the theme’s CSS file, which is a common task for the Halo theme, you use the Embed statement. The following example defines new graphical skins for the Button class:

@namespace mx "library://ns.adobe.com/flex/mx"; 
mx|Button { 
    upSkin: Embed("upIcon.jpg"); 
    downSkin: Embed("downIcon.jpg"); 
    overSkin: Embed("overIcon.jpg"); 
}

The name you provide for the Embed keyword is the same name that you use for the skin asset when compiling the SWC file.

The CSS file can include any number of class selectors, as well as type selectors. Style definitions for your theme do not have to use skins. You can simply set style properties in the style sheet, as the following example shows:

@namespace mx "library://ns.adobe.com/flex/mx"; 
mx|ControlBar { 
    color:red; 
}

For more information about the default style sheets, see About the default style sheets.

Compiling a theme SWC file

You compile a theme SWC file by using the include-file and include-classes options of the component compiler. This is the same compiler that creates component libraries and Runtime Shared Libraries (RSLs).

You invoke the component compiler either with the compc command line utility or when creating a Library Project in Adobe Flash Builder.

You use the include-file option to add the CSS file and graphics files to the theme SWC file. You use the include-classes option to add programmatic skin classes to the theme SWC file.

To simplify the commands for compiling theme SWC files, you can use configuration files. For more information, see Using a configuration file to compile theme SWC files.

Using the include-file option to compile theme SWC files

The include-file option takes two arguments: a name and a path. The name is the name that you use to refer to that asset as in the CSS file. The path is the file system path to the asset. When using include-file, you are not required to add the resources to the source path. The following command line example includes the upIcon.jpg asset in the theme SWC file:

-include-file upIcon.jpg c:/myfiles/themes/assets/upIcon.jpg 

You also specify the CSS file as a resource to include in the theme SWC file. You must include the .css extension when you provide the name of the CSS file; otherwise, Flex does not recognize it as a style sheet and does not apply it to your application.

You use the component compiler to compile theme assets, such as a style sheet and graphical skins, into a SWC file. The following example compiles a theme by using the compc command-line compiler:

compc -include-file mycss.css c:/myfiles/themes/mycss.css  
    -include-file upIcon.jpg c:/myfiles/themes/assets/upIcon.jpg  
    -include-file downIcon.jpg c:/myfiles/themes/assets/downIcon.jpg  
    -include-file overIcon.jpg c:/myfiles/themes/assets/overIcon.jpg  
    -o c:/myfiles/themes/MyTheme.swc

You cannot pass a list of assets to the include-file option. Each pair of arguments must be preceded by ‑include-file. Most themes use many skin files and style sheets, which can be burdensome to enter each time you compile. To simplify this, you can use the load-config option to specify a file that contains configuration options, such as multiple include-file options. For more information, see Using a configuration file to compile theme SWC files.

Using the include-classes option to compile theme SWC files

The include-classes option takes a single argument: the name of the class to include in the SWC file. You pass the class name and not the class filename (for example, MyButtonSkin rather than MyButtonSkin.as). The class must be in your source path when you compile the SWC file.

The following command-line example compiles a theme SWC file that includes the CSS file and a single programmatic skin class, MyButtonSkin, which is in the themes directory:

compc -source-path c:/myfiles/flex/themes 
    -include-file mycss.css c:/myfiles/flex/themes/mycss.css  
    -include-classes MyButtonSkin -o c:/myfiles/flex/themes/MyTheme.swc

You can pass a list of classes to the include-classes option by space-delimiting each class, as the following example shows:

-include-classes MyButtonSkin MyControlBarSkin MyAccordionHeaderSkin

For more information about creating skin classes, see Skinning MX components.

Using a configuration file to compile theme SWC files

Using a configuration file is generally more verbose than passing options on the command line, but it can make the component compiler options easier to read and maintain. For example, you could replace a command line with the following entries in a configuration file:

<?xml version="1.0"?> 
<flex-config> 
    <output>MyTheme.swc</output> 
    <include-file> 
        <name>mycss.css</name> 
        <path>c:/myfiles/themes/mycss.css</path> 
    </include-file> 
    <include-file> 
        <name>upIcon.jpg</name> 
        <path>c:/myfiles/themes/assets/upIcon.jpg</path> 
    </include-file> 
    <include-file> 
        <name>downIcon.jpg</name> 
        <path>c:/myfiles/themes/assets/downIcon.jpg</path> 
    </include-file> 
    <include-file> 
        <name>overIcon.jpg</name> 
        <path>c:/myfiles/themes/assets/overIcon.jpg</path> 
    </include-file> 
    <include-classes> 
        <class>MyButtonSkin</class> 
        <class>MyAccordionHeaderSkin</class> 
        <class>MyControlBarSkin</class> 
    </include-classes> 
</flex-config>

You can use the configuration file with compc by using the load-config option, as the following example shows:

compc -load-config myconfig.xml

You can also pass a configuration file to the Flash Builder component compiler. For more information on using the component compilers, see Flex compilers.