Packagecom.soma.model
Classpublic class BackgroundManager
ImplementsIDisposable

Author: Romuald Quantin - www.soundstep.com

Information:
Blog page - SomaUI
How does it work - Soma Protest
Project Host - Google Code
Documentation - Soma ASDOC
Class version: 2.0
Actionscript version: 3.0

Copyright:

The contents of this file are subject to the Mozilla Public License
Version 1.1 (the "License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied.
See the License for the specific language governing rights and
limitations under the License.

The Original Code is Soma.
The Initial Developer of the Original Code is Romuald Quantin.
Initial Developer are Copyright (C) 2008-2009 Soundstep. All Rights Reserved.

Usage:
The BackgroundManager handles backgrounds in a Sprite layer underneath the site and provides an easy way to load, display and hide backgrounds. The backgrounds can automatically be loaded and/or instantiated from the XML Site Definition (nodes children of a backgrounds node).

The global background manager instance is accessible using: 

Soma.getInstance().background
The backgrounds container (Sprite) is accessible using: 
Soma.getInstance().background.container
The current background displayed is accessible using: 
Soma.getInstance().background.currentBackground
The backgrounds supported are the the ones supported by the NodeParser class (see link below), they can be image, bitmap, movieclip, video or your own custom classes, here are some examples: 
<video id="myVideo" url="video/video.flv" x="50" alpha=".5" verticalCenter="0" volume="0" />
<image id="myImage" file="image.png" scaleX=".5" scaleY=".5" blendMode="multiply" ratio="ratio_in"/>
<bitmap id="myBitmap" linkage="AssetClassNameBitmap" x="170" y="170" blendMode="multiply" scaleX=".3" scaleY=".3"/>
<movieclip id="myMovieClip" linkage="AssetClassNameMovieClip" x="170" y="280" scaleX=".3" scaleY=".3"/>
Soma provides commands to show and hide backgrounds using the attribute id of an asset node in the background node of the XML Site Definition. 
     new BackgroundEvent(BackgroundEvent.SHOW, "myBackgroundID").dispatch();
     new BackgroundEvent(BackgroundEvent.HIDE, "myBackgroundID").dispatch();
Two listeners can be added to Soma control the transitions (can be default prevented). 
  Soma.getInstance().addEventListener(BackgroundEvent.TRANSITION_IN, eventHandler);
  Soma.getInstance().addEventListener(BackgroundEvent.TRANSITION_OUT, eventHandler);

See also

Soma
BackgroundEvent
NodeParser
ParserEvent
SomaLoader
SomaLoaderEvent

Public Properties
 PropertyDefined by
  baseUI : BaseUI
[read-only] Get the BaseUI instance used if BaseUI properties have been found in the XML (such as ratio, alignX and so on).
BackgroundManager
  container : Sprite
[read-only] Get the Sprite container that contains the backgrounds, this container is by default on the index 0 in the display list (added to the main class).
BackgroundManager
  currentBackground : DisplayObject
[read-only] Get the current background displayed, returns a DisplayObject but you can cast the value returned to the proper type, example for a video node: 
<video id="myVideo" url="video/video.flv" x="50" alpha=".5" verticalCenter="0" volume="0" />
   var video:SomaVideo = Soma.getInstance().background.currentBackground as SomaVideo;
   video.volume = .5;
BackgroundManager
  loader : SomaLoader
[read-only] Get the SomaLoader instance used to load the backgrounds.
BackgroundManager
  parser : NodeParser
[read-only] Get the NodeParser instance used to parse the nodes and instantiate the backgrounds.
BackgroundManager
  REPLAY_BACKGROUND_VIDEO : Boolean = true
[static] Default value whether or not a background video will be played from the start when displayed.
BackgroundManager
  TRANSITION_EASING : Function
[static] Default easing equations used to hide and show the background.
BackgroundManager
  TRANSITION_IN_TIME : Number = 2
[static] Default time value in seconds used to show a background (alpha tween).
BackgroundManager
  TRANSITION_OUT_TIME : Number = 2
[static] Default time value in seconds used to hide a background (alpha tween).
BackgroundManager
Public Methods
 MethodDefined by
  
BackgroundManager()
Creates a BackgroundManager instance, the global BackgroundManager instance is accessible using Soma.getInstance().background.
BackgroundManager
  
dispose():void
Disposes the BackgroundManager instance.
BackgroundManager
  
getBackgroundByID(id:String):DisplayObject
Get a background in the container using its attribute id from the XML node.
BackgroundManager
  
hide():void
Method called from the BackgroundEvent.HIDE command to hide the current background displayed.
BackgroundManager
  
show(id:String):void
Method called from the BackgroundEvent.SHOW command to show a background using its id from the XML node.
BackgroundManager
  
start():void
Entry point of the BackgroundManager, it will create (and load) the backgrounds from the children nodes of the backgrounds node from the XML Site Definition.
BackgroundManager
Property detail
baseUIproperty
baseUI:BaseUI  [read-only]

Get the BaseUI instance used if BaseUI properties have been found in the XML (such as ratio, alignX and so on).

Implementation
    public function get baseUI():BaseUI
containerproperty 
container:Sprite  [read-only]

Get the Sprite container that contains the backgrounds, this container is by default on the index 0 in the display list (added to the main class).

Implementation
    public function get container():Sprite
currentBackgroundproperty 
currentBackground:DisplayObject  [read-only]

Get the current background displayed, returns a DisplayObject but you can cast the value returned to the proper type, example for a video node: 

<video id="myVideo" url="video/video.flv" x="50" alpha=".5" verticalCenter="0" volume="0" />
   var video:SomaVideo = Soma.getInstance().background.currentBackground as SomaVideo;
   video.volume = .5;

Implementation
    public function get currentBackground():DisplayObject
loaderproperty 
loader:SomaLoader  [read-only]

Get the SomaLoader instance used to load the backgrounds.

Implementation
    public function get loader():SomaLoader
parserproperty 
parser:NodeParser  [read-only]

Get the NodeParser instance used to parse the nodes and instantiate the backgrounds.

Implementation
    public function get parser():NodeParser
REPLAY_BACKGROUND_VIDEOproperty 
public static var REPLAY_BACKGROUND_VIDEO:Boolean = true

Default value whether or not a background video will be played from the start when displayed.

TRANSITION_EASINGproperty 
public static var TRANSITION_EASING:Function

Default easing equations used to hide and show the background.

TRANSITION_IN_TIMEproperty 
public static var TRANSITION_IN_TIME:Number = 2

Default time value in seconds used to show a background (alpha tween).

TRANSITION_OUT_TIMEproperty 
public static var TRANSITION_OUT_TIME:Number = 2

Default time value in seconds used to hide a background (alpha tween).

Constructor detail
BackgroundManager()constructor
public function BackgroundManager()

Creates a BackgroundManager instance, the global BackgroundManager instance is accessible using Soma.getInstance().background.

Method detail
dispose()method
public function dispose():void

Disposes the BackgroundManager instance. Removes listeners and destroys backgrounds, loader, parser and container.

getBackgroundByID()method 
public function getBackgroundByID(id:String):DisplayObject

Get a background in the container using its attribute id from the XML node.

Parameters
id:String

Returns
DisplayObject — A DisplayObject instance.
hide()method 
public function hide():void

Method called from the BackgroundEvent.HIDE command to hide the current background displayed.

show()method 
public function show(id:String):void

Method called from the BackgroundEvent.SHOW command to show a background using its id from the XML node.

Parameters
id:String — Attribute id of the XML node asset (in backgrounds node in the XML Site Definition).
start()method 
public function start():void

Entry point of the BackgroundManager, it will create (and load) the backgrounds from the children nodes of the backgrounds node from the XML Site Definition.




Soundstep - Soma