Functional and Design Specification

Glossary

Halo The default skins used by Flex 2 and Flex 3
Spark The default skins used by Flex 4

Summary and Background

Styles for the Spark skins are designed to be simple, predictable, and consistent. You can change the entire appearance of an application with a few global style properties. This is a stark contrast to styling in Halo where you have many more knobs to adjust the appearance, and many of these knobs need to be set on individual components or type selectors.

The problem is many simple and common tasks that could be accomplished with styles in Halo now require re-skinning in Spark. This feature adds more styles to our Spark skins.

We are not striving for complete parity with Halo styles. The goal is to expose the most commonly requested styles. Skinning is still the "ultimate fallback" for customization that cannot be achieved through styling.

Usage Scenarios

Peter wants to change the appearance of his app to make the corners of Buttons more rounded, and to make the background of TextInput controls have some translucency. Previously this would require copying and pasting the entire skin files and tweaking the graphics markup accordingly. Now, thanks to this new feature, these tweaks can be done simply by styling.

Detailed Description

The new styles fall into two buckets:

• Global inheriting styles This is where all of the existing Spark styles live. This bucket is used to easily and consistently change the appearance of the entire application by simply setting a few global style properties. The default values for these styles are never defined on type selectors. They are always set on the single global selector.
• Local non-inheriting styles This is how many of the Halo styles are handled. These are typically defined on individual type selectors, although some may be defined globally.

An additional consideration is "backgroundColor" for the Spark Application, WindowedApplication, and Window components. This is currently a property, but will become a style.

Related features

Before digging into the new styles, let's take a look at some related features first.

Border

The Border component (working name) will be a new Spark SkinnableContainer subclass that supports most of the old Halo Container styles. Border is used to add borders, backgrounds, and drop shadows to content. We're still working on the details for this component, but we expect it to support all of the common Container styles like borderThickness, cornerRadius, backgroundColor, backgroundAlpha, borderColor, backgroundImage, and dropShadowVisible. Alternatively you can set the stroke and fill objects directly for even more control over the appearance. This component is not yet available.

Advanced CSS

There are many Halo styles that exist purely to style sub-components or states of a component. Examples of sub-component styles include headerStyleName on Accordion, dropDownStyleName on ComboBox and verticalScrollBarStyleName on List. Examples of state-specific styles include textRollOverColor, disabledIcon, and selectedTabTextStyleName.

The new advanced CSS features in Flex 4 obviate the need for these types of styles. Here are some examples of using the new CSS syntax:

<fx:Style>
    @namespace s "library://ns.adobe.com/flex/spark";

    <!-- Using an id selector to set the font size for Panel title -->
    s|Panel #titleDisplay {
        fontSize: 20;
    }

    <!-- Using descendant selectors to set the chromeColor for scroll bars inside TextAreas -->
    s|TextArea s|ScrollBar {
        chromeColor: #CCCCDD;
    }

    <!-- Using pseudo selectors to change the color of the checkbox checkmark in the "downAndSelected" state -->
    s|CheckBox:downAndSelected {
        symbolColor: #FFFF00;
    }

    <!-- These can all be combined as needed. Here is a silly example that sets the chromeColor of the down state
         of the increment button in a scroll bar inside a text area. Whew! -->
    s|TextArea s|ScrollBar #incrementButton:down {
        chromeColor: #FF0000;
    }
    
</fx:Style>

As you can see, the new advanced CSS features provide far more flexibility and styling options than the old Halo styles. For more information about advanced CSS, see the CSS Advanced Selectors Spec.

Existing Spark style properties

The existing Spark style properties are chromeColor, contentBackgroundColor, focusColor, and symbolColor (Spark skins also share the alternatingItemColors, color, rollOverColor, and selectionColor styles with Halo, along with all text related styles). See the Styling Gumbo Components spec for details.

New proposed Spark style properties

Here is a list of new style properties for the Spark skins.

Global inheriting styles

Local non-inheriting styles

The List styles also apply to subclasses of List: Tree, DataGrid, HorizontalList, TileList

Note about cornerRadius

The cornerRadius style is a single value. Each skin is responsible for rounding the appropriate corners. For example, the NumericStepper skin picks rounds the right corners of the spinner buttons, but no the left corners. There are no styles for individual corner rounding.

Halo styles and Spark counterparts

This table shows several MX components along with their Halo style properties and Spark style counterparts. There are many styles not listed here, including text styles, constraints, and layout-related styles. These are theme-agnostic styles that will work regardless of the skin or theme applied to the component.

Button

List

Slider

Adding support for binding to getStyle()

In order for the compiler to handle binding to getStyle(), support for a new Bindable metadata variant will be added:

[Bindable(style="true")]

This will be put on UIComponent's and TextGraphicElement's getStyle(). When the compiler finds a function in a data binding expression marked with this metadata, it generates a FunctionReturnWatcher without the requirement that child watchers exist and it sets the isStyle constructor parameter to true. The isStyle parameter signals to the FunctionReturnWatcher that is should listen for style change events.

In conjunction with the FunctionReturnWatcher changes, UIComponent.stylesChanged() will be updated to dispatch "<style>Changed" events or "allStylesChanged" events when all the styles for a component have changed.

Adding support for picking up the backgroundColor style off of the root Application, even if it is defined in CSS.

PreLink will be updated to search the root document's StyleContainer and the global StyleContainer for a class selector or type selector which specifies the backgroundColor. The same precedence rules as runtime lookup of the backgroundColor will apply. If found, it will be used in the same way as if the backgroundColor was set via the command line, -default-background-color. This includes setting the background color in the SWF using the SetBackgroundColor SWF tag and in HTML with the Embed tag.

API Description

See the Detailed Description section for information about which components honor these styles.

{
    //--------------------------------------------------------------------------
    //
    //  Inheriting styles
    //
    //--------------------------------------------------------------------------

    /**
     *  The alpha transparency for the content background of the component.
     *
     *  @default 1.0
     */
    [Style(name="contentBackgroundAlpha", type="Number", inherit="yes", theme="spark")]


    //--------------------------------------------------------------------------
    //
    //  Non-inheriting styles
    //
    //--------------------------------------------------------------------------

    /**
     *  The alpha transparency for the background of the component.
     *
     *  @default 1.0
     */
    [Style(name="backgroundAlpha", type="Number", inherit="no", theme="spark")]


    /**
     *  The color for the background of the component.
     *
     *  @default #FFFFFF
     */
    [Style(name="backgroundColor", type="uint", format="Color", inherit="no", theme="halo, spark")]


    /**
     *  The alpha for the border of the component.
     *
     *  @default 1.0
     */
    [Style(name="borderAlpha", type="Number", inherit="no", theme="spark")]


    /**
     *  The color for the border of the component.
     *
     *  @default #686868
     */
    [Style(name="borderColor", type="uint", format="Color", inherit="no", theme="halo, spark")]


    /**
     *  The visibility of the components border.
     *
     *  @default true
     */
    [Style(name="borderVisible", type="Boolean", inherit="no" theme="spark")]


    /**
     *  The radius of the corners of the component.
     *
     *  @default 2.0
     */
    [Style(name="cornerRadius", type="Number", inherit="no" theme="halo, spark")]


    /**
     *  The visibility of the components drop shadow.
     *
     *  @default true
     */
    [Style(name="dropShadowVisible", type="Boolean", inherit="no", theme="halo, spark")]


    /**
     *  The alpha of the focus ring.
     *
     *  @default 0.55
     */
    [Style(name="focusAlpha", type="Number", inherit="no", theme="halo, spark")]


    /**
     *  The blend mode of the focus ring.
     *
     *  @default "normal"
     */
    [Style(name="focusBlendMode", type="String", inherit="no", theme="halo, spark")]


    /**
     *  The thickness of the focus ring.
     *
     *  @default 2
     */
    [Style(name="focusThickness", type="Number", inherit="no", theme="halo, spark")]


    /**
     *  The bottom padding for this component.
     *
     *  @default 3
     */
    [Style(name="paddingBottom", type="Number", inherit="no", theme="spark")]


    /**
     *  The left padding for this component.
     *
     *  @default 3
     */
    [Style(name="paddingLeft", type="Number", inherit="no", theme="spark")]


    /**
     *  The right padding for this component.
     *
     *  @default 3
     */
    [Style(name="paddingRight", type="Number", inherit="no", theme="spark")]


    /**
     *  The top padding for this component.
     *
     *  @default 5
     */
    [Style(name="paddingTop", type="Number", inherit="no", theme="spark")]
}

B Features

None.

Examples and Usage

Setting the contentBackgroundAlpha for all components

<fx:Style>
    global {
        contentBackgroundAlpha: 0.6;
    }
</fx:Style>

Setting the padding for all TextInput controls

<fx:Style>
    @namespace s "library://ns.adobe.com/flex/spark";

    s|TextInput {
        paddingLeft: 10;
        paddingRight: 10;
        paddingTop: 4;
        paddingBottom: 4;
    }
</fx:Style>

Setting cornerRadius on an individual Button

<s:Button label="Submit" cornerRadius="5" />

Setting the chromeColor for all Buttons to red using ActionScript

<fx:Script>
    <[CDATA[

    var cssR:CSSStyleDeclaration = StyleManager.getStyleDeclaration("spark.components.Button");
    cssR.setStyle("chromeColor", "red");
]]>
</fx:Script>

Additional Implementation Details

In order to simplify the implementation we are adding binding support to the getStyle() function. This means you will be able to bind directly to style properties in your markup:

<s:Rect ...>
        <s:stroke>
            <s:SolidColorStroke color="{getStyle('borderColor')}" ... />
        </s:stroke>
    </s:Rect>

Prototype Work

Geometry altering styles like borderVisibility need to be prototyped to determine the best plan for implementation.

Compiler Work

• Adding support for binding to getStyle()
• Adding support for picking up the backgroundColor style off of the root Application, even if it is defined in CSS.

Web Tier Compiler Impact

None.

Flex Feature Dependencies

The new components and skins planned for 4+ need to be accounted for.

Backwards Compatibility

Syntax changes

None.

Behavior

None.

Warnings/Deprecation

None.

Accessibility

The focusBlendMode style is primarily for accessibility. This was supported by the Halo skins, and will now be supported by the Spark skins.

Performance

Need to make sure these additional styles don't have too much impact on performance and memory. Specifically, binding to getStyle() vs. pushing in style properties directly.

Globalization

None.

Localization

Compiler Features

None.

Framework Features

None.

Issues and Recommendations

None.

Documentation

Many of the styles behave identically to their Halo counterpart. There may be some differences that need to be called out in the documentation.

QA

All of the usual style testing guidelines apply here. Need to test global, type, and class selectors along with setting inline via MXML and ActionScript.