Menu
▾
▴
Mobile Splash Screen
Mobile Splash Screen - Functional and Design Specification
Glossary
Preloader - this is short from preloader display class - one that extends IPreloaderDisplay For example the mx.preloaders.DownloadProgressBar is a preloader display. Not to be mistaken with the mx.preloaders.Preloader class which creates an instance of the preloader display and puts it on the display list.
Info object - this is a compiler generated object, part of the generated SystemManager class. This class is a dictionary of all application attributes and their values. Besides other uses, this class is used to pass parameters to the preloader classes. The compiler treats certain attributes in a special way. For example the "preloader" attribute has a default value defined by the compiler. Example of a generated info object:
override public function info():Object
{
if (!_info)
{
_info = {
applicationComplete: "appComplete()",
compiledLocales: <a href="%20%26quot%3Ben_US%26quot%3B%20"> "en_US" </a>,
compiledResourceBundleNames: [ "SharedResources", "collections",
"components", "core", "effects", "formatters", "layout", "skins",
"sparkEffects", "styles" ],
currentDomain: ApplicationDomain.currentDomain,
dummy: _mx_embed_resource__Default_png_,
mainClassName: "ComponentCatalog",
mixins: [ "_ComponentCatalog_FlexInit", "_ComponentCatalog_Styles",
"mx.managers.systemClasses.ActiveWindowManager" ],
preinitialize: "PerfReporterFactory.getPerfReporter().appPreInit(event)",
preloader: spark.preloaders.SplashScreen
}
}
return _info;
}
Summary and Background
Consider the start-up experience for a Mobile Flex application. Since Mobile Flex applications run on the AIR platform the swf is already present on the SD card and not being downloaded. Therefore the default DownloadProgressBar preloader doesn't seem that suitable for Mobile Flex applications. In addition, some Mobile Flex applications may take some time to boot so some kind of preloader is still desirable.
This feature - Mobile Splash Screen - provides a default SplashScreen preloader specifically for the Mobile Flex applications.
Goals
- Support for splash screens for AIR mobile apps.
- Ability to specify embedded resource.
- Resize options for the image - no scale, scale to fit, letterbox fit
- Works both in full-screen and normal application mode.
Non-Goals/Limitations
- Support for splash screens for browser apps.
- Loading external resources (we'll support only embedded images).
- DPI-specifics resources.
- Orientation-specific resources.
- Platform-specific resources (Android vs. WinMo device for example).
- Progress/busy animation during start-up sequence along with the splash screen.
- Tooling support for generating images/resources.
Usage Scenarios
Mr. Jono is creating a Flex Mobile Application. He notices that upon application start-up the screen is filled with the application background color. He wants to customize the start-up experience by adding a splash screen.
He gets the "piratesCupcakeClub.png" from his designer and copies it to his Flex project. Then he adds an attribute to the <application> or <viewnavigatorapplication> tag (whichever he's using for this project) like this: <application splashscreenimage="@Embed('piratesCupcakeClub.png')" ...="">. Jono compiles and runs - now at the start of the application he can see the splash screen image. Cool!
</application></viewnavigatorapplication></application>
He notices that the image by default doesn't cover the whole screen. But actually his dog doesn't like the way it looks and barks very loud at him. Jono decides to try a "zoomed" image for the splash screen so he sets the other attribute that controls the splash screen: <application splashscreenscalemode="zoom">. Now the image is still centered, but also zoomed .
</application>
A third option is "letterbox" - the image will be scaled up until it fits, with letterbox bands either top/bottom or left/right.
A foruth option is "stretch" where the image will cover the entire stage, but may be distorted.
Detailed Description
Changes Summary
- New preloader class - spark.preloaders.SplashScreen
- Tweaks to the mx.preloaders.Preloader class to show the preloader instance as soon as possible.
- Additional attributes on the <application> root tag (through compiler changes)
- splashScreenImage
- splashScreenScaleMode
- splashScreenMinimumDisplayTime
- New compiler option for specifying default preloader - "preloader"
- Updated air-mobile-config.xml to set the default preloader to the spark.preloaders.SplashScreen
- Support for "@Embed()" values for root attributes (i.e. splashScreenImage) when generating the SystemManager info object. This support to be added through compiler changes.
SplashScreen
A new preloader class will be added - spark.preloaders.SplashScreen:
- Reads the two parameters from the SystemManager's info object - splashScreenImage and splashScreenScaleMode (these are specified on the application root tag, see next section for details).
- If splashScreenImage is non-null, then creates an instance of the image and adds it as a child.
- The splashScreenScaleMode controls size/position of the image
- none - this is the default - the image is centered within the stage, at its original pixel size. It is only DPI scaled (through the Density Independence feature). The uncovered parts of the stage will be filled with the application backgroundColor.
- stretch - scales to fill the entire stage, potentially changing aspect ratio. The image is centered.
- letterbox - the image is scaled, preserving aspect ratio, until it touches the edges of the stage. The image is still centered. The uncovered parts of the stage will be filled with the application backgroundColor.
- zoom - the image is scaled, preserving aspect ratio, until the whole stage is covered. In cases where the image aspect ratio is different from the stage's aspect ration, parts of the image will be cropped outside of the stage. The images is still centered withing the stage.
- The splashScreenMinimumDisplayTime allows the developer the specify min. amount of time the splash screen will be showing. This property has no effect when there's no splashScreenImage. The default value is 1000 ms.
- There's no extra work to support full-screen / normal application modes as the image position logic is keyed off of the stage size.
Tweaks to the "mx.preloaders.Preloader" Class
Currently the Preloader class runs a timer to monitor download progress. As soon as all the bytes are in, it dispatches an event to the SystemManager to advance to the next frame. While this works well for desktop/browser scenarios, it results in sub-optimal experience for Flex Mobile application. In a Flex Mobile application, in order to display the splash screen as soon as possible, we need to put the image on the display list, then wait a frame so that the runtime has the chance to render before we dispatch an event to the SystemManager causing the loading of all the code form frame 2.
The tweak to the mx.preloaders.Preloader class will be to ensure that the runtime renders at least one frame between adding the preloader display class to the display list (i.e. spark.preloaders.SplashScreen) and dispatching an event to the SystemManager that kicks-off the application start-up sequence.
This tweak actually apply to all types of Flex project/application as it will have no noticeable effect for non-Flex Mobile applications.
Additional Attributes on the <application> Root Tag</application>
Three additional attributes on the Application tag will be enabled:
- splashScreenImage
- splashScreenScaleMode
- splashScreenMinimumDisplayTime
Example:
<s:ViewNavigatorApplication
xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
width="100%" height="100%"
splashScreenImage="@Embed('Default.png')"
splashScreenScaleMode="none"
splashScreenMinimumDisplayTime="2000">
Since the attributes are used to parametrize the preloader class, we only need the attribute values in the info class. For the purpose of ASDocs, metadata & hinting, we'll add them as public vars to the spark.Application class with the splashScreenImage being a property. Additional change in the compiler will be required to disable generation of setter code in the generated application code. The way to do this is by making the splashScreenImage as "special" - see DocBuilder.java "specialAttributes2009" for example.
public class Application extends SkinnableContainer
{
//----------------------------------
// splashScreenImage
//----------------------------------
<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%29">Inspectable(category="General")</a>
/**
* The image class for the SplashScreen preloader.
*
* Typically developers set to an embedded resource,
* i.e. splashScreenImage="@ Embed('Default.png')".
*
* <p><b>Note:</b> The property has effect only when the preloader is
* set to <code>spark.preloaders.SplashScreen</code>.
* The <code>spark.preloaders.SplashScreen</code> class is the default
* preloader for Mobile Flex applications.
* This property cannot be set by ActionScript code; it must be set in MXML code.</p>
*
* @see splashScreenScaleMode
* @see splashScreenMinimumDisplayTime
*/
public function get splashScreenImage():Class
public function set splashScreenImage(value:Class):void
//----------------------------------
// splashScreenScaleMode
//----------------------------------
<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bnone%2Cletterbox%2Cstretch%2Czoom%26quot%3B%2C%20defaultValue%3D%26quot%3Bnone%26quot%3B%29">Inspectable(category="General", enumeration="none,letterbox,stretch,zoom", defaultValue="none")</a>
/**
* The splash screen image scale mode.
*
* <p>A value of "none" implies that the image size is set to match its intrinsic size.
*
* A value of "stretch" sets the width and the height of the image to the
* stage width and height, possibly changing the content aspect ratio.
*
* A value of "letterbox" sets the width and height of the image as close to the
* stage width and height
* as possible while maintaining aspect ratio. The image is stretched to a maximum
* of the stage bounds, with spacing added inside the stage to maintain the aspect
* ratio if necessary.
*
* A value of "zoom" is similar to "letterbox", except that "zoom" stretches the
* image past the bounds of the stage, to remove the spacing required to maintain aspect ratio.
* This has the effect of using the entire bounds of the stage, but also possibly
* cropping some of the image.
*
* <b>Note:</b> The portion of the stage that is not covered by the image will
* show in the Application's <code>backgroundColor</code>.</p>
*
* <p><b>Note:</b> The property has effect only when the <code>splashScreenImage</code>
* property is set
* and the preloader is <code>spark.preloaders.SplashScreen</code>.
* The <code>spark.preloaders.SplashScreen</code> class is the default preloader for
* Mobile Flex applications.
* This property cannot be set by ActionScript code; it must be set in MXML code.</p>
*
* @default "none"
* @see splashScreenImage
* @see splashScreenMinimumDisplayTime
*/
public var splashScreenScaleMode:String;
//----------------------------------
// splashScreenMinimumDisplayTime
//----------------------------------
<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%29">Inspectable(category="General")</a>
/**
* Minimum amount of time, in milliseconds, to show the splash screen image.
*
* <p><b>Note:</b> The property has effect only when the <code>splashScreenImage</code>
* property is set
* and the preloader is <code>spark.preloaders.SplashScreen</code>.
* The <code>spark.preloaders.SplashScreen</code> class is the default preloader for
* Mobile Flex applications.
* This property cannot be set by ActionScript code; it must be set in MXML code.</p>
*
* @default 1000
* @see splashScreenImage
* @see splashScreenScaleMode
*/
public var splashScreenMinimumDisplayTime:Number;
}
New Compiler Option for Default Preloader
While generating the info object, the compiler treats certain attributes specially. For example if the "preloader" attribute is not explicitly specified at the application root tag then a default value is selected and used while generating the info object. The value is based on the Flex version and is either mx.preloaders.DownloadProgressBar or mx.preloaders.SparkDownloadProgressBar. This value is used at run-time to create and instance of the preloader class.
In order to support a different default preloader class for Mobile Flex applications, we'll extend the compiler by adding a new optional configuration option - preloader. When this option is specified, its value will be used as the default value for the preloader while generating the info object (explicitly specified preloader on the Application tag still wins.) If not specified, the compiler will fall back to the previous default behavior.
The help string for this option is listed in the localization section of the spec below.
Taking advantage of that change, the preloader default for the Mobile Flex projects will be set to "spark.preloaders.SplashScreen" in the airmobile-config.xml file:
<flex-config>
<!-- Specifies the minimum player version that will run the compiled SWF. -->
<target-player>10.1.0</target-player>
<compiler>
<!-- Specify the default preloader. -->
<preloader>spark.preloaders.SplashScreen</preloader>
...
</compiler>
...
</flex-config>
Support for "@Embed()" Values at Root Attributes
The info object is the mechanism through which attribute values from the mxml <application> tag are passed through to the preloader class (since the preloader class is instantiated in frame 1, before the Application class which is instantiated in frame 2).</application>
Currently, while generating the info object, the compiler treats "@Embed…" attribute values as string literals with no special meaning. In order to support the scenario of passing embedded images as parameters to the preloader the compiler will have to treat these tags in a special way.
The compiler will be modified to recognize "@Embed" attributes and generate embedded resource variables in the generated SystemManager and its respective info object:
<s:ViewNavigatorApplication ... splashScreenImage="@Embed('Default.png')" >
Will result in the following generated code:
public class _ComponentCatalog_mx_managers_SystemManager
extends mx.managers.SystemManager
implements IFlexModuleFactory, ISWFContext
{
...
<a href="Embed%28source%3D%26%2339%3BDefault.png%26%2339%3B%29">Embed(source='Default.png')</a>
private var _mx_embed_resource_splashScreenImage_Default_png_:Class;
/**
* @private
*/
private var _info:Object;
override public function info():Object
{
if (!_info)
{
_info = {
splashScreenImage: _mx_embed_resource_splashScreenImage_Default_png_,
...
}
}
return _info;
}
...
}
compared with the code generated by the current compiler version:
public class _ComponentCatalog_mx_managers_SystemManager
extends mx.managers.SystemManager
implements IFlexModuleFactory, ISWFContext
{
...
/**
* @private
*/
private var _info:Object;
override public function info():Object
{
if (!_info)
{
_info = {
splashScreenImage: "@Embed('Default.png')",
...
}
}
return _info;
}
...
}
API Description
package spark.preloaders
{
/**
* The SplashScreen class is the default preloader for Mobile Flex applications.
*
* Developers can specify image class and resize mode through the Application properties
* <code>splashScreenImage</code>, <code>splashScreenScaleMode</code> and
* <code>splashScreenMinimumDelayTime</code>.
*
* @see spark.Application#splashScreenImage
* @see spark.Application#splashScreenScaleMode
* @see spark.Application#splashScreenMinimumDisplayTime
*/
public class SplashScreen extends Sprite, implements IPreloaderDisplay
{
}
}
public class Application extends SkinnableContainer
{
//----------------------------------
// splashScreenImage
//----------------------------------
<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%29">Inspectable(category="General")</a>
/**
* The image class for the SplashScreen preloader.
*
* Typically developers set to an embedded resource, i.e. splashScreenImage="@Embed('Default.png')".
*
* <p><b>Note:</b> The property has effect only when the preloader is set
* to <code>spark.preloaders.SplashScreen</code>.
* The <code>spark.preloaders.SplashScreen</code> class is the default preloader
* for Mobile Flex applications.
* This property cannot be set by ActionScript code; it must be set in MXML code.</p>
*
* @see splashScreenScaleMode
* @see splashScreenMinimumDisplayTime
*/
public function get splashScreenImage():Class
public function set splashScreenImage(value:Class):void
//----------------------------------
// splashScreenScaleMode
//----------------------------------
<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bnone%2Cletterbox%2Cstretch%2Czoom%26quot%3B%2C%20defaultValue%3D%26quot%3Bnone%26quot%3B%29">Inspectable(category="General", enumeration="none,letterbox,stretch,zoom", defaultValue="none")</a>
/**
* The splash screen image scale mode.
*
* <p>A value of "none" implies that the image size is set to match its intrinsic size.
*
* A value of "stretch" sets the width and the height of the image to the
* stage width and height, possibly changing the content aspect ratio.
*
* A value of "letterbox" sets the width and height of the image as close to the stage
* width and height
* as possible while maintaining aspect ratio. The image is stretched to a maximum of
* the stage bounds,
* with spacing added inside the stage to maintain the aspect ratio if necessary.
*
* A value of "zoom" is similar to "letterbox", except that "zoom" stretches the
* image past the bounds of the stage, to remove the spacing required to maintain aspect ratio.
* This has the effect of using the entire bounds of the stage, but also possibly cropping
* some of the image.
*
* <b>Note:</b> The portion of the stage that is not covered by the image will show
* in the Application's <code>backgroundColor</code>.</p>
*
* <p><b>Note:</b> The property has effect only when the <code>splashScreenImage</code>
* property is set
* and the preloader is <code>spark.preloaders.SplashScreen</code>.
* The <code>spark.preloaders.SplashScreen</code> class is the default preloader for
* Mobile Flex applications.
* This property cannot be set by ActionScript code; it must be set in MXML code.</p>
*
* @default "none"
* @see splashScreenImage
* @see splashScreenMinimumDisplayTime
*/
public var splashScreenScaleMode:String;
//----------------------------------
// splashScreenMinimumDisplayTime
//----------------------------------
<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%29">Inspectable(category="General")</a>
/**
* Minimum amount of time, in milliseconds, to show the splash screen image.
*
* <p><b>Note:</b> The property has effect only when the <code>splashScreenImage</code>
* property is set
* and the preloader is <code>spark.preloaders.SplashScreen</code>.
* The <code>spark.preloaders.SplashScreen</code> class is the default preloader for
* Mobile Flex applications.
* This property cannot be set by ActionScript code; it must be set in MXML code.</p>
*
* @default 1000
* @see splashScreenImage
* @see splashScreenScaleMode
*/
public var splashScreenMinimumDisplayTime:Number;
}
New compiler options:
- "preloader" - a default for the preloader - value is of type Class, i.e. "mxmlc -preloader=spark.preloaders.SplashScreen".
B Features
N/A
Compiler Work|WorkYesYes. See the "Detailed Description" section.
Behavior
- Application attributes with "@Embed" values specified will generate embedded resources for the SystemManager's info class where before they were generating a string literal values for that class.
Performance
Application start-up with the SplashScreen preloader should be at least as good as with the DownloadProgressBar for a reasonable sized .png screen (snapshot of the application first screen for example).
Globalization
N/A
Localization
Compiler Features
Command-line help descriptions should be added to sdk/modules/compiler/src/java/flex2/configuration_en.properties and configuration_ja.properties.
compiler.preloader=
specifies the default value for the Application's preloader attribute.
If not specified, the default preloader value is
mx.preloaders.SparkDownloadProgressBar for -compatibility-version >= 4.0 and
max.preloader.DownloadProgressBar for -compatibility-version < 4.0.
Error/warning messages that are related to the compiler core (flex2.compiler.* packages) should be added to sdk/modules/compiler/src/java/flex2/compiler_en.properties and compiler_ja.properties.
N/A
Error/warning messages that are related to the linker (flex2.linker.* packages) should be added to sdk/modules/compiler/src/java/flex2/linker_en.properties and linker_ja.properties.
N/A
