Flex SDK Wiki

Flex is now being developed at the Apache Software Foundation

Brought to you by: adobeadmin, aharui, arijitchatt, mayurkansal, and 3 others

Open @ Adobe

View More Projects

Dynamic Splash Screen Improvements

Authors:

Dynamic Splash Screen Improvements - Functional and Design Specification

Summary and Background

In Flex Hero, the framework introduced a SplashScreen preloader that allowed a developer to display an image at startup for Flex Mobile applications. This splash screen preloader works well in some cases, but fails to allow developers to create a high quality startup experience on all platforms at launch. This is because dpis vary from device to device, and as a result, an image that looks well on one may not look well on another. Scaling doesn't necessarily solve this problem because pixelation and stretching can occur. The ideal solution would be to allow a developer to display a different splash screen image per dpi and orientation. This would allow the developer to better customize the start up experience of their application.

Goals

Per-dpi, per-aspect ratio, per-form-factor Splash Screen images

Non-Goals

Animated Splash Screens

Usage Scenarios

Jay is building a Flex AIR application that will run across various phone and tablet devices. He uses the splashScreenImage property on his main Application tag to declare an image to display at startup. But when running on higher resolutions and dpi devices, the image is scaled which causes the image to look less than desirable. Instead, Jay would like to define a different image per dpi and orientation. To accomplish this, Jay creates a new [#SplashScreenImage] component and populates it with a series of \[``[#SplashScreenImageSource]``\] objects, one for each device configuration he would like to support. Once this is complete, Jay sets the splashScreenImage property on the Application to his custom #SplashScreenImage component. Now when run on device, a different splash screen is displayed on each device. Jay retires with the profits and he lives happily ever after.

Jane is inheriting the support of the applicaiton Jay created. Her boss wants Jane to now add different images for iOS vs. Android. Jane overrides the getImageClass method in the custom #SplashScreenImage component and voila. She too, retires with the profits and lives happily ever after.

Best Practices

Typically to create a good splash screen experience, developers need to take care of the various factors of the platform.

Zoom or center scaling
To minimize the number of images, can create square images with enough background to be clipped in landscape/portrait mode. If need to customize for landscape / portrait then create one set for each.
Always set one of the images as default (no explicit settings) so something is always shown
Provide images for 160 dpi for low-dpi phones to avoid down-scaling artifacts
Provide images for 240 / 320 dpi to target the high-resolution devices and avoid pixellization
Use minResolution = 960 for example to provide a separate set for tables in order to avoid too much empty space around the image in the center (for example running on iphone 3gs vs. ipad)
Test the Splash Screen on different devices and/or in ADL. Set splashScreenMinimumDisplayTime to some high value when testing.

Detailed Description

SplashScreenImage

Developer defines a a href="%23SplashScreenImage">#SplashScreenImage component in a separate MXML file and sets the name of the component as the value of the Application's splashScreenImage property (see Usage section).
Developer describes the different images (classes) to be displayed at different settings as a series of one or more a href="%23SplashScreenImageSource">#SplashScreenImageSource children of the a href="%23SplashScreenImage">#SplashScreenImage.
The a href="%23SplashScreenImage">#SplashScreenImage has a method that picks best matching a href="%23SplashScreenImageSource">#SplashScreenImageSource for particular set of device configurations - dpi, resolution (max of stageWidth, stageHeight) and aspectRatio (portrait/landscape based on stage dimensions).
The a href="http://opensource.adobe.com/wiki/display/flexsdk/Mobile%2BSplash%2BScreen">SplashScreen preloader calls that method when it needs an image/class to display an instance of. For example, initially at startup and also on orientation change / stage resize while the application is loading.
Developers can override the method to have custom logic picking the image/class to be displayed.

SplashScreenImageSource

Used as a child in the MXML of a href="%23SplashScreenImage">#SplashScreenImage
Has a "source" property of type Class - this is the class to be displayed. Usually an embedded image/asset.
Has a dpi, aspectRatio and minResolution properties.

Property Name
Description

dpi
The desired dpi of the device

aspectRatio
The aspect ratio of the device.

minResolution
The minimum size the stage width or height needs to be to use the source. This allows a developer to define a different splash screen on devices with the same dpi but drastically different resolutions. For example, an iPhone 3GS and an iPad.

source
The source to use if the device matches the capabilities defined by the object

Default Matching Logic of the a href="http://opensource.adobe.com/wiki/display/flexsdk/Mobile%2BSplash%2BScreen">#SplashScreenImage] - Based on dpi, aspectRatio and resolution (max of stage.stageWidth, stage.stageHeight) passed in by the [SplashScreen preloader.

Find all the a href="%23SplashScreenImageSource">#SplashScreenImageSource that match all of the settings.
1. We consider a "match" for a setting if the a href="%23SplashScreenImageSource">#SplashScreenImageSource didn't have that setting explicitly defined or
2. if the setting is dpi or aspectRatio and that has the same value as the one passed in or
3. if the setting is minResolution and that is greater or equal to the passed in resolution.
If there's more than one match, then
1. Pick the one with biggest number of explicit settings or
2. If there's more than one, pick the one with highest minResolution value or
3. If there's more than one, pick the first in the order of their definition inside the a href="%23SplashScreenImage">#SplashScreenImage class (the order they were defined in MXML).

API Description

Additions to MXML Language and ActionScript Object Model

Include the relevant API for this feature using the following example as a guideline. Make sure you indicate whether APIs are public or protected. You do not need to present private or mx_internal APIs here.

package spark.preloaders
{

/**
* SplashScreenImageSource specifies a Class to be displayed
* as splash screen at a particular device configuration such as
* DPI, orientation and resolution.
*
* Developers typically use one or more <code>SplashScreenImageSource</code>
* objects to define a <code>SplashScreenImage</code> class in MXML
* and set the Application's <code>splashScreenImage</code> property to that class.
*
* @see spark.preloaders.SplashScreenImage
* @see spark.components.Application#splashScreenImage
*/
public class SplashScreenImageSource
{
//--------------------------------------------------------------------------
//
// Constructor
//
//--------------------------------------------------------------------------

/**
* Constructor.
*
*/
public function SplashScreenImageSource()
{
}

//--------------------------------------------------------------------------
//
// Properties
//
//--------------------------------------------------------------------------

//----------------------------------
// aspectRatio
//----------------------------------

<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bportrait%2Clandscape%26quot%3B%29">Inspectable(category="General", enumeration="portrait,landscape")</a>

/**
* The required aspectRatio of the device.
* Can be either StageAspectRatio.PORTRAIT or StageAspectRatio.LANDSCAPE.
*
* <p>If not set <code>SplashScreenImage</code> ignores this.</p>
*/
public var aspectRatio:String = null;

//----------------------------------
// dpi
//----------------------------------

<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3B160%2C240%2C320%26quot%3B%29">Inspectable(category="General", enumeration="160,240,320")</a>

/**
* The required dpi of the device.
*
* <p>A value of NaN is ignored by <code>SplashScreenImage</code>.</p>
*
* @default NaN
*/
public var dpi:Number;

//----------------------------------
// minResolution
//----------------------------------

/**
* The required minimum size of the device resolution needed to display the image.
* The device resolution is the maximum of the stage width and height, in pixels.
*
* This property can be used to display different images based on the pixel
* resolution of a device.
*
* <p>A value of NaN is ignored by the <code>SplashScreenImage</code>.</p>
*
* @default NaN
*/
public var minResolution:Number;

//----------------------------------
// source
//----------------------------------

/**
* The image class for the splash screen to use for the defined
* device configuration. Typically you set this property to an
* embedded resource.
*
* For example:
*
* <pre>source="&#64;Embed('Default.png')"</pre>
*
* @see spark.preloaders.SplashScreenImage
*
* @default null
*
*/
public var source:Class;
}
}



package spark.preloaders
{

<a href="DefaultProperty%28%26quot%3BmxmlContent%26quot%3B%29">DefaultProperty("mxmlContent")</a>

/**
* Use the SplashScreenImage class to specify different splash screen
* images per device configurations like DPI, orientation, resolution.
*
* <p>Developers typically define a <code>SplashScreenImage</code> class
* in a separate MXML file. The different image choices and corresponding
* device configutaions are defined in that MXML file as <code>SplahsScreenImageSource</code>
* children. The Developers set the Application's <code>splashScreenImage</code>
* property to the name of the <code>SplashScreenImage</code> definition.</p>
*
* <p>Note, this class can't be set inline in the Application MXML, it needs
* to be defined in a separate MXML file and referenced from the Application's
* <code>splashScreenImage</code> property.</p>
*
* @see spark.preloaders.SplashScreenImageSource
* @see spark.components.Application#splashScreenImage
*/
public class SplashScreenImage
{
//--------------------------------------------------------------------------
//
// Constructor
//
//--------------------------------------------------------------------------

/**
* Constructor.
*/
public function SplashScreenImage()
{
}

//--------------------------------------------------------------------------
//
// Properties
//
//--------------------------------------------------------------------------

//----------------------------------
// mxmlContent
//----------------------------------

<a href="ArrayElementType%28%26quot%3Bspark.preloaders.SplashScreenImageSource%26quot%3B%29">ArrayElementType("spark.preloaders.SplashScreenImageSource")</a>

/**
* The <code>SplashScreenImageSource</code> sources for this
* <code>SplashScreenImage</code>.
*
* Typically developers don't use this method directly, instead they
* define the <code>SplashScreenImageSource</code> inline in MXML.
*/
public function get mxmlContent():Array
public function set mxmlContent(value:Array):void


//--------------------------------------------------------------------------
//
// Methods
//
//--------------------------------------------------------------------------

/**
* Returns the Class of the SplashScreenImageSource that matches best
* the specified device parameters.
*
* Developers don't call this method directly, it is called internally by Flex.
*
* Developers may override this method in a subclass if they want to override
* the default Flex logic of picking the best matching SplashScreenImageSource.
*
* @param aspectRatio The current aspectRatio of the device.
* @param dpi The dpi of the device.
* @param resolution The resolution of the device's bigger dimension, in pixels.
* @return The Class for the image to be displayed as a splash screen image.
*/
public function getImageClass(aspectRatio:String, dpi:Number, resolution:Number):Class

}
}

B Features

Detail features here that are to be considered for B Feature time.

Examples and Usage

Specifying a #SplashScreenImage

The Application File:

<?xml version="1.0" encoding="utf-8"?>
<s:Application ...
splashScreenImage="MySplashScreen"
splashScreenMinimumDisplayTime="10000"
>

The MySplashScreenImage.as

<?xml version="1.0" encoding="utf-8"?>
<s:SplashScreenImage xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark">

<!-- no settings, so this acts as default -->
<s:SplashScreenImageSource source="@Embed('assets/splash1.png')"/>

<!-- specific settings -->
<s:SplashScreenImageSource source="@Embed('assets/splash1.png')"
dpi="240" aspectRatio="portrait"/>

<s:SplashScreenImageSource source="@Embed('assets/splash1.png')"
dpi="160" aspectRatio="portrait" minResolution="960"/>

<s:SplashScreenImageSource source="@Embed('assets/360flex-perf-tips-QnA.png')"
aspectRatio="landscape"/>

</s:SplashScreenImage>

Overriding the #SplashScreenImage default matching logic

<?xml version="1.0" encoding="utf-8"?>
<s:SplashScreenImage xmlns:fx="http://ns.adobe.com/mxml/2009"
                     xmlns:s="library://ns.adobe.com/flex/spark">

    <fx:Script>
        <![CDATA[

            <a href="Embed%28%26quot%3Bassets/360flex-perf-tips-QnA.png%26quot%3B%29">Embed("assets/360flex-perf-tips-QnA.png")</a>
            private var iosImage:Class;

            override public function getImageClass(aspectRatio:String, dpi:Number, resolution:Number):Class
            {
                // Are we running on iOS ?
                if (Capabilities.version.indexOf("IOS") == 0)
                    return iosImage;

                return super.getImageClass(aspectRatio, dpi, resolution);
            }
        ]]>
    </fx:Script>

    <!-- no settings, so this acts as default -->
    <s:SplashScreenImageSource source="@Embed('assets/splash1.png')"/>

    <!-- specific settings -->
    <s:SplashScreenImageSource source="@Embed('assets/splash1.png')"
                               dpi="240" aspectRatio="portrait"/>

    <s:SplashScreenImageSource source="@Embed('assets/splash1.png')"
                               dpi="160" aspectRatio="portrait" minResolution="960"/>

    <s:SplashScreenImageSource source="@Embed('assets/360flex-perf-tips-QnA.png')"
                               aspectRatio="landscape"/>

</s:SplashScreenImage>

Additional Implementation Details

Enter implementation/design details for the feature here. This section may be updated after the spec signs off.

Compiler Work

Cross-Form-Factor Considerations

The "minResolution" property allows developers to target splash screen sources at different form factors.

Cross-Platform Considerations

Backwards Compatibility

N/A

Accessibility

Performance

none

Globalization

N/A

Localization

N/A

Issues and Recommendations

Enumerate open issues needing resolution, along with recommended solutions, if any.

Wiki: Flex 4.6