Functional and Design Specification

Glossary

• Spark components - The new Flex 4 components.
• Spark theme - The default skins for Flex 4. It includes skins for the Spark components and the MX components, because not all the MX components will have Spark replacements for Flex 4.
• MX components - The Flex 3 components.
• Halo theme - The default skins for the MX components when compatibility-version=3.

Summary and Background

When developers are using Spark components with the Spark theme, we want the compiler to report errors/warnings when Halo specific styles are used. Conversely, we want the compiler to report errors/warnings when Spark theme specific styles are used with MX components.

Usage Scenarios

• A developer uses the Spark theme with the Spark components and defines a Halo specific style in an MXML tag. For example:

  <fx:Application themeColor="red"/>

  The compiler will report an error.

• A developer uses the Halo theme with the MX components and defines a Spark specific style in an MXML tag. For example:

  <mx:Application baseColor="blue"/>

  The compiler will report an error.

• A developer uses the Spark theme with the Spark components and defines a Halo specific style in a CSS selector, which has an associated type. For example:

  <mx:Style>
      @namespace "library://ns.adobe.com/flex/spark";
  
      Button
      {
  	themeColor: red;
      }
    </mx:Style>

  The compiler will report a warning.

• A developer uses the Halo theme with the MX components and defines a Spark specific style in an MXML tag. For example:

  <mx:Style>
      @namespace "library://ns.adobe.com/flex/halo";
  
      Button
      {
  	baseColor: red;
      }
    </mx:Style>

  The compiler will report a warning.

• A developer uses a Halo derived custom theme, like halo-wooden.css, and defines a Halo specific style in an Mxml tag. The compiler will allow this.
• A developer uses a Halo derived custom theme, like halo-wooden.css, and defines a Spark specific style in an Mxml tag. The compiler will report an error.
• A developer uses a Spark derived custom theme, like spark-wireframe.css, and defines a Spark specific style in an Mxml tag. The compiler will allow this.
• A developer uses a Spark derived custom theme, like spark-wireframe.css, and defines a Halo specific style in an Mxml tag. The compiler will report an error.
• A developer uses a custom theme, which is not derived from Halo or Spark, and defines a style for which there is no Style metadata, in a class selector. The compiler will allow this.
• A developer uses a custom theme, which is not derived from Halo or Spark, and defines a style, for which there is no Style metadata, in an Mxml tag. The compiler will report an error.

Detailed Description

Defaults

The compiler will set the theme to <FLEX_HOME>/frameworks/themes/Spark/spark.css by default and flex-config.xml will contain a commented out example showing the default:

<!-- The default theme -->
<!-- not set -->
<!--
<theme>
    <file>themes/Spark/spark.css</file>
</theme>
-->

Style metadata

For this release, the Halo and Spark components will only have Style metadata with a theme attribute of "spark" or "halo". When no theme attribute is specified, the style applies to all themes. The compiler will use the theme attribute to validate styles defined in MXML and CSS. Here is an example of the Style metadata:

[Style(name="baseColor", type="uint", format="Color", inherit="yes", theme="spark")]

It is valid to specify multiple values for the theme attribute. For example:

[Style(name="backgroundColor", type="uint", format="Color", inherit="yes", theme="halo,spark")]

Configuring the theme name(s)

The theme name(s) will be configured by a naming scheme where the first word prefix specifies the theme name or the base theme name. For example, halo.swc and halo-wooden.css mean the theme name will be halo and spark.swc and spark-wireframe.css mean the theme name will be spark.

In the future, if we move Style metadata to the skins and add support to the compiler and tools for looking up Style metadata in the skinClass, then the naming scheme will no longer be necessary.

CSS validation

Only CSS selectors with an associated type will be validated. An associated type is required in order for the compiler to lookup Style metadata. CSS selectors with an associated type include fully qualified type selectors, in addition to id and descendant selectors with a fully qualified subject. Class selectors, the universal selector, and unqualified type selectors do not have an assoicated type. For examples, see CSS Advanced Selectors.

Unknown styles defined in defaults.css files and themes will be excluded from validation, because this allows custom themes to define new styles.

Warnings and Errors

For MXML validation, errors will be reported. For example:

The style 'dropShadowEnabled' is excluded by type 'mx.containers.ApplicationControlBar'.

The style 'baseColor' is only supported by the theme(s) 'halo'.

For CSS validation, warnings will be reported. For example:

The style 'borderColor' is only supported by the theme(s) 'spark'.

The style 'myColor' was not declared by type 'spark.components.Button'.

The style 'dropShadowEnabled' is excluded by type 'mx.containers.ApplicationControlBar'.

There will be a new configuration option, -show-invalid-css-property-warnings, for disabling the CSS warnings. The MXML errors will always be enabled.

Custom themes

• To set a derived custom theme, the user should do something like this in flex-config.xml (note: the default is specified to avoiding being overridden):

  <theme>
    <file>themes/Spark/spark.swc</file>
    <file>spark-derivedTheme.swc</file>
  </theme>

  or like this from the command line (note: the use of plus-equals to avoid overriding the default theme):

  -theme+=spark-derivedTheme.swc

• To set a repackaged custom theme, the user should do something like this in flex-config.xml (note: the prefix):

  <theme>
    <file>spark-repackagedTheme.swc</file>
  </theme>

  or like this from the command line (note: the prefix):

  -theme=spark-repackagedTheme.swc

• To set a completely new custom theme, which is not Spark or Halo based, the user should do something like this in flex-config.xml (note: the default is overriden):

  <theme>
    <file>myCustomTheme.swc</file>
  </theme>

  or like this from the command line (note: the equals to override the default):

  -theme=myCustomTheme.swc

API Description

N/A

B Features

None.

Examples and Usage

See "Usage Scenarios".

Additional Implementation Details

Prototype Work

A prototype of Plan A was completed, but we are not going to use it. A prototype of the current plan has also been implemented.

Web Tier Compiler Impact

N/A

Dependencies on other Flex features.

Backwards Compatibility

Syntax changes

N/A

Behavior

When compatibility-version=3, the compiler will change the default theme to <FLEX_HOME>/frameworks/themes/Halo/halo.swc.

Warnings/Deprecation

N/A

Accessibility

N/A

Performance

It's not expected that this feature will noticeably affect performance.

Globalization

N/A

Localization

Compiler Features

New errors and warnings will be added to compiler_en.properties.

Framework Features

N/A

Issues and Recommendations

• This feature will only support the Halo and Spark themes, because it relies on the Style metadata in the Spark and MX components. In order for the compiler to support additional themes, the Style metadata would need to be updated and the components would need to be recompiled. It has been proposed that the Style metadata be moved to the skins and the compiler be updated to resolve the skins at compile time. This would allow for other themes to declare a different set of styles. A compiler prototype of this has been implemented, but there is not enough time in this release's schedule for the tools to add support for this proposal.

• The Spark theme is currently included in spark.swc. It needs to be extracted into spark.swc for the naming scheme to work.

Documentation

QA

See "Usage Scenarios".