Support multiple screen sizes and DPI values in a mobile application

You set the value of the applicationDPI property to 160, 240, or 320, depending on the approximate resolution of your target device. For example:

<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    firstView="views.DensityView1" 
    applicationDPI="320">

The following example sets the Spark Button control’s default fontSize style property to 12. If the device uses 240 DPI and is running on the Android operating system, the fontSize property is 10.

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_skins/MediaQueryValuesMain.mxml -->
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
     xmlns:s="library://ns.adobe.com/flex/spark" applicationDPI="320">
    
    <fx:Style>
        @namespace s "library://ns.adobe.com/flex/spark";
        @namespace mx "library://ns.adobe.com/flex/mx";

        s|Button {
            fontSize: 12;
        }

        @media (os-platform: "Android") and (application-dpi: 240) {
            s|Button {
                fontSize: 10;
            }
        }

    </fx:Style>
    
</s:ViewNavigatorApplication>

The application-dpi CSS property is compared against the value of the applicationDPI style property that is set on the root application. The following are valid values for the application-dpi CSS property:

• 160

• 240

• 320

The os-platform CSS property is matched to the value of the flash.system.Capabilities.version property of Flash Player. The following are valid values for the os-platform CSS property:

• Android

• iOS

• Macintosh

• Linux

• QNX

• Windows

The following example shows how to use some of these common operators:

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_skins/MediaQueryValuesMain.mxml -->
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
     xmlns:s="library://ns.adobe.com/flex/spark" applicationDPI="320">
    
    <fx:Style>
        @namespace s "library://ns.adobe.com/flex/spark";
        @namespace mx "library://ns.adobe.com/flex/mx";

        /* Every os-platform @ 160dpi */
        @media (application-dpi: 160) {
            s|Button {
                fontSize: 10;
            }
        }

        /* IOS only @ 240dpi */
        @media (application-dpi: 240) and (os-platform: "IOS") {
            s|Button {
                fontSize: 11;
            }
        }

        /* IOS at 160dpi or Android @ 160dpi */
        @media (os-platform: "IOS") and (application-dpi:160), (os-platform: "ANDROID") and (application-dpi: 160) {
            s|Button {
                fontSize: 13;        
            }
        }

        /* Every os-platform except Android @ 240dpi */
        @media not all and (application-dpi: 240) and (os-platform: "Android") {
            s|Button {
                fontSize: 12;
            }
        }    

        /* Every os-platform except IOS @ any DPI */
        @media not all and (os-platform: "IOS") {
            s|Button {
                fontSize: 14;        
            }
        }
    </fx:Style>
    
</s:ViewNavigatorApplication>

The following example loads a different image, depending on the DPI:

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_skins/views/MultiSourceView3.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" 
        title="Image with MultiDPIBitmapSource">

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    
    <fx:Script>
        <![CDATA[
            import mx.core.FlexGlobals;
            
            private function doSomething():void {
                /* The MultiDPIBitmapSource's source data. */
                myTA.text = myImage.source.getSource(FlexGlobals.topLevelApplication.applicationDPI).toString();            
            }
            
            
        ]]>
    </fx:Script>

    <s:Image id="myImage">
        <s:source>
            <s:MultiDPIBitmapSource
                    source160dpi="assets/low-res/bulldog.jpg"
                    source240dpi="assets/med-res/bulldog.jpg"
                    source320dpi="assets/high-res/bulldog.jpg"/>
        </s:source>
    </s:Image>

    <s:Button id="myButton" label="Click Me" click="doSomething()"/>
    <s:TextArea id="myTA" width="100%"/>

</s:View>

The Button control’s icon property also takes a class as an argument. As a result, you can also use a MultiDPIBitmapSource object as the source for the Button’s icon. You can define the source of the icon inline, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_skins/views/MultiSourceView2.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" title="Icons Inline">

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    
    <fx:Script>
        <![CDATA[
            import mx.core.FlexGlobals;
            
            private function doSomething():void {                
                /* The MultiDPIBitmapSource's source data. */
                myTA.text = dogButton.getStyle("icon").getSource(FlexGlobals.topLevelApplication.applicationDPI).toString();
            }
        ]]>
    </fx:Script>

    <s:Button id="dogButton" click="doSomething()">
        <s:icon>
            <s:MultiDPIBitmapSource id="dogIcons"
                    source160dpi="@Embed('../../assets/low-res/bulldog.jpg')"
                    source240dpi="@Embed('../../assets/med-res/bulldog.jpg')"
                    source320dpi="@Embed('../../assets/high-res/bulldog.jpg')"/>
        </s:icon>
    </s:Button>       
    <s:TextArea id="myTA" width="100%"/>

</s:View>

You can also define icons by declaring them in a <fx:Declarations> block and assigning the source with data binding, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_skins/views/MultiSourceView1.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:mx="library://ns.adobe.com/flex/mx"
        xmlns:s="library://ns.adobe.com/flex/spark" 
        title="Icons in Declarations">

    <fx:Declarations>
        <s:MultiDPIBitmapSource id="dogIcons"
                source160dpi="@Embed('../../assets/low-res/bulldog.jpg')"
                source240dpi="@Embed('../../assets/med-res/bulldog.jpg')"
                source320dpi="@Embed('../../assets/high-res/bulldog.jpg')"/>
    </fx:Declarations>

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    
    <fx:Script>
        <![CDATA[
            import mx.core.FlexGlobals;
            
            private function doSomething():void {                
                /* The MultiDPIBitmapSource's source data. */
                myTA.text = dogIcons.getSource(FlexGlobals.topLevelApplication.applicationDPI).toString();
            }
        ]]>
    </fx:Script>

    <s:Button id="dogButton" icon="{dogIcons}" click="doSomething()"/>    
    <s:TextArea id="myTA" width="100%"/>    
</s:View>

For example, the spark.skins.mobile.ButtonSkin class uses a switch/case statement that selects FXG assets that are designed for particular DPI values, similar to the following:

switch (applicationDPI) { 
    case DPIClassification.DPI_320: { 
        upBorderSkin = spark.skins.mobile320.assets.Button_up; 
        downBorderSkin = spark.skins.mobile320.assets.Button_down; 
        ... 
        break; 
    } 
    case DPIClassification.DPI_240: { 
        upBorderSkin = spark.skins.mobile240.assets.Button_up; 
        downBorderSkin = spark.skins.mobile240.assets.Button_down; 
        ... 
        break; 
    } 
}

import mx.core.FlexGlobals; 
var curDensity:Number = FlexGlobals.topLevelApplication.runtimeDPI; 
var curAppDPI:Number = FlexGlobals.topLevelApplication.applicationDPI; 
var currentScalingFactor:Number = curDensity / curAppDPI;

You can use the calculated scaling factor to manually select assets. The following example defines custom locations of bitmap assets for each DPI value. It then loads an image from that custom location:

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_skins/DensityMain.mxml -->
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
     xmlns:s="library://ns.adobe.com/flex/spark" 
     firstView="views.DensityView1" 
     applicationDPI="240" initialize="initApp()">
    
    <fx:Script>
        <![CDATA[
                [Bindable]
                public var densityDependentDir:String;

                [Bindable]
                public var curDensity:Number;
                [Bindable]
                public var appDPI:Number;
                [Bindable]
                public var curScaleFactor:Number;
                
                public function initApp():void {
                    curDensity = runtimeDPI; 
                    appDPI = applicationDPI;
                    curScaleFactor  =  appDPI / curDensity;

                    switch (curScaleFactor) {
                        case 1: { 
                            densityDependentDir = "../../assets/low-res/"; 
                            break; 
                        } 
                        case 1.5: { 
                            densityDependentDir = "../../assets/med-res/"; 
                            break;
                        }
                        case 2: { 
                            densityDependentDir = "../../assets/high-res/"; 
                            break;
                        }                
                    }
                }   
        ]]>
    </fx:Script>
    
</s:ViewNavigatorApplication>

The view that uses the scaling factor is as follows:

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_skins/views/DensityView1.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" 
        title="Home" 
        creationComplete="initView()">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    
    <fx:Script>
        <![CDATA[
            import mx.core.FlexGlobals;

            [Bindable]
            public var imagePath:String;

            private function initView():void {
                label0.text = "App DPI:" + FlexGlobals.topLevelApplication.appDPI;
                label1.text = "Cur Density:" + FlexGlobals.topLevelApplication.curDensity;
                label2.text = "Scale Factor:" + FlexGlobals.topLevelApplication.curScaleFactor;         

                imagePath = FlexGlobals.topLevelApplication.densityDependentDir + "bulldog.jpg";
                
                ta1.text = myImage.source.toString();
            }
        ]]>
    </fx:Script>
    
    <s:Image id="myImage" source="{imagePath}"/>

    <s:Label id="label0"/>
    <s:Label id="label1"/>
    <s:Label id="label2"/>

    <s:TextArea id="ta1" width="100%"/>
</s:View>

The following example sets a custom DPI mapping for a device whose Capabilities.os property matches “Mac 10.6.5”:

package {
import flash.system.Capabilities;
import mx.core.DPIClassification;
import mx.core.RuntimeDPIProvider;

public class DPITestClass extends RuntimeDPIProvider {
    public function DPITestClass() {
    }
    
    override public function get runtimeDPI():Number {
        // Arbitrary mapping for Mac OS.
        if (Capabilities.os == "Mac OS 10.6.5")
            return DPIClassification.DPI_320;
        
        if (Capabilities.screenDPI < 200)
            return DPIClassification.DPI_160;
        
        if (Capabilities.screenDPI <= 280)
            return DPIClassification.DPI_240;
        
        return DPIClassification.DPI_320; 
    }
}
}

The following application uses the DPITestClass to determine a runtime DPI value to use for scaling. It points to the ViewNavigatorApplication class’s runtimeDPIProvider property:

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_skins/DPIMappingOverrideMain.mxml -->
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
     xmlns:s="library://ns.adobe.com/flex/spark" 
     firstView="views.DPIMappingView" 
     applicationDPI="160"
     runtimeDPIProvider="DPITestClass">
        
</s:ViewNavigatorApplication>

The following is another example of a subclass of the RuntimeDPIProvider class. In this case, the custom class checks the device’s x and y resolution to determine if the device is incorrectly reporting its DPI value:

package
{
import flash.system.Capabilities;
import mx.core.DPIClassification;
import mx.core.RuntimeDPIProvider;

public class SpecialCaseMapping extends RuntimeDPIProvider {
    public function SpecialCaseMapping() {
    }
    
    override public function get runtimeDPI():Number {
        /* A tablet reporting an incorrect DPI of 240. We could use
            Capabilities.manufacturer to check the tablet's OS as well. */
        if (Capabilities.screenDPI == 240 && 
            Capabilities.screenResolutionY == 1024 && 
            Capabilities.screenResolutionX == 600) {
            return DPIClassification.DPI_160;
        }
        
        if (Capabilities.screenDPI < 200)
            return DPIClassification.DPI_160;
        
        if (Capabilities.screenDPI <= 280)
            return DPIClassification.DPI_240;
        
        return DPIClassification.DPI_320; 
    }
}
}