CSS Media Query - Functional and Design Specification

Glossary

media query - Part of the CSS spec that allows for styles based on media type and media features http://www.w3.org/TR/css3-mediaqueries/
density - The number of pixels per inch.
DPI - Acronym for number of Dots Per Inch, same as Pixels Per Inch

Summary and Background

Developers may wish to use different styles and assets when the application runs on different devices and device configurations such as devices with different screen densities (different DPI).

Usage Scenarios

Tina is developing a mobile theme and wants to control the exact font size for specific screen density ranges.

Tim is developing a mobile application and wants to use different font sizes on devices with lower screen densities because the default scaling behavior comes out to be a pixel taller than he would like.

Detailed Description

Flex applications will now be able to declare a range of densities they were designed for via the Application.applicationDPI property. The default behavior of Flex is to scale the entire stage when asked to render at a density other than the declared density. If no applicationDPI is specified, Flex does not scale. The scaling, plus the size of the ranges defined for Application.applicationDPI, plus discrepancies between the reported density and the actual physical density may result in less-than-perfect visuals. We want to provide a way to specify different styles for different density ranges. We will also leverage the same mechanism to allow developers to specify different styles for different operating systems (Android vs IOS).

We will introduce a limited subset of the CSS Media Query spec, and add custom media types and media features

Tina will create a theme with a defaults.css that specifies different media queries for the different density ranges. Then, if a developer uses the theme and specifies a particular applicationDPI the correct set of styles will be applied to the theme.

For Tim, he will not specify an applicationDPI because he wants to use the actual runtime density range to dictate which styles to use.

API Description

We will support the media type "screen". No other media types will match. We will not support any CSS media features, only the custom media features listed below.

We will add the custom media features:

• os-platform (allowed values are "Android", "IOS", "Macintosh", "Windows", "Linux". Other values are allowed and will be matched against the three character platform abbreviation in Capabilities.version in case new platforms become available).

• application-dpi (allowed values are the numbers: 160, 240, 320. It will be matched against the Application.applicationDPI property)

  IStyleManager2/StyleManagerImpl

  /**
   *  Used in media query handling.
   *  @param value normalized media query string
   *  @returns true if valid media
   */
  function acceptMediaList(value:String):Boolean;
  

B Features

None

Examples and Usage

Following is an example of some media queries. The first specifies "all" media types and a applicationDPI of 160. The second implies "all" media types and the IOS platform and that the applicationDPI is 240. The third implies "all" media types and the Android platform and a applicationDPI of 240.

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

        s|Button
        {
            fontSize: 12;
        }

        @media all and (application-dpi: 160)
        {
            s|Button
            {
                fontSize: 10;
            }
        }
        @media (application-dpi: 240) and (os-platform: "IOS")
        {
            s|Button
            {
                fontSize: 11;
            }
        }
        @media (application-dpi: 240) and (os-platform: "Android")
        {
            s|Button
            {
                color: 13;
            }
        }
    </fx:Style>

Additional Implementation Details

We will be relatively lenient on the allowed values for os-platform. It really should be a quoted string, but we'll let it go without quotes. Matching is case-insensitive.

Compiler Work

Apache Batik

The compiler currently uses a modified version of Apache Batik 1.6 to parse CSS syntax. Our copy of this third-party library will be updated to handle CSS Media Queries. Specifically, the CSS Parser will be extended to understand the CSS Media Query syntax as outlined in the W3C's Media Queries Candidate Recommendation. This will require modifying Batik's @media rule support (which currently only supports media types). We will add awareness of a potential list of media queries, with each query consisting of a potential chain of expressions that establish conditions for specific media features. Support for three new tokens, and, not and only will also be added, as will two new resolution units, dpi and dpcm.

Mxmlc/Compc

The compiler currently processes the set of rules discovered by the Batik CSS Parser and generates ActionScript code to register selectors with the framework's [StyleManager] implementation. The compiler will be updated to additionally process media rules. The generated <a href="ActionScript">ActionScript</a> code will be modified so that selectors from ``media rules will first check the result of the media query at runtime before registering the style declarations.

Media query selectors intended to override default behavior when certain runtime conditions apply should be declared after normal style-sheet level selectors to ensure they cascade correctly.

The generated ActionScript will need to be updated for inline-MXML <fx:Style> content, themes and default styles, and CSS modules, for both the direct-to-AST generation and legacy \-keep-generated-actionscript=true compilation modes.

We will not validate the semantics of any Media Query expression at compile time. While the string representation may be normalized in terms of whitespace or quote escaping for ActionScript, the framework code at runtime will interpret the query expressions.

The exact form of generated ActionScript code is not guaranteed and may change in future releases.

Backwards Compatibility

Syntax changes

None

Behavior

None

Warnings/Deprecation

None

Accessibility

None

Performance

None

Globalization

None

Localization

Compiler Features

Apache Batik's CSS Parser resource string file was updated to include a few additional messages for invalid CSS media queries.

See modules/thirdparty/batik/resources/org/apache/batik/css/parser/resources/Messages.properties

The localization team needs to update the translations for this file for each locale. It appears we ship French, German, Japanese, Chinese (Simplified), Korean and Russian versions of Batik's resource property files in jars in the Flex SDK /lib directory.

Framework Features

New API added to IStyleManager2 (acceptMediaList)

Cross-Platform Considerations

None

Issues and Recommendations

Should we add a custom media feature for scaling so styles and assets can be used with the reverse-scale? (flex-scaling: 2)