Would you like to tell us how we are doing?

You bet No thanks
qnx.fuse.ui.skins Summary

qnx.fuse.ui.skins

Interfaces  | Classes


Understanding skins

The BlackBerry Tablet OS contains a set of skin classes that provide a customizable and consistent, look and feel for your application. The BlackBerry Tablet OS defines two distinct color themes: light and dark. The tablet uses the light themed component skins by default.

Each UI component in the BlackBerry Tablet OS was designed to enable a specific user-interaction. For example, the picker is useful for inputting complex numbers such as dates or IP addresses. The user can expand the picker component in order to scroll through a set of vertical scrolling lists. Because UI components vary in their complexity, most UI components differ from one another in the way that they implement skinning. For example, a basic button component is simple to skin when compared to a section tile list or a picker, both of which are comprised of many parts.

Each skin object consists of one or more graphic assets, where a graphic asset provides the bitmap or vector data that is used to render each state of the skin. For example, a button skin should contain assets to define the up, down, selected, and disabled states that appear when the user interacts with the button. These component states are defined in qnx.fuse.ui.skins.SkinStates. An asset uses 9 slice scaling which allows it to be resized with little or no distortion.

Most skins in the SDK derive from the qnx.fuse.ui.skins.UISkin class. The qnx.fuse.ui.skins.UISkin class registers skins for certain states and handles the state changes so that the appropriate skin is associated with the current state. All skinnable UI component parts in the SDK use one of the following skin types:

Skin type Description
ICellRenderer The ICellRenderer class is used to render the cells in all list types. When you create a skin for the list class, your skin must implement ICellRenderer interface.
ISkin The ISkin class is the default skin for all components such as buttons and thumbs. When you create a skin for a button class, your skin must implement ISkin interface.

In order to create your own custom skin, you must (at the very least) create a skin class that implements the qnx.fuse.ui.skins.ISkin interface. The quickest way to create a custom skin is to inherit from the qnx.fuse.ui.skins.UISkin class to take advantage of the base functionality for handling state changes and for associating skins with states. To create a custom skin, create a class that extends qnx.fuse.ui.skins.UISkin. Assets for each state are created on demand as needed. This helps reduce the memory foot print of your application, as it doesn't create assets for states that the user may never see. Once an asset has been created, it is best practice to store that asset in a local variable and return it on further requests instead of re-creating the asset.

In the following code listing, the getSkinForState() function creates assets for the specified state on demand:

     
override protected function getSkinForState(state : String) : DisplayObject
{
	var asset : DisplayObject;

	switch (state)
	{
		case SkinStates.UP:
			if( upSkin == null )
			{
				upSkin = new Sprite();
				upSkin.graphics.beginFill(0xFF6600);
				upSkin.graphics.drawRect(0,0,200,200);
				upSkin.graphics.endFill();
			}
			asset = upSkin;
			break;
		case SkinStates.DOWN:
		case SkinStates.DOWN_SELECTED:
		case SkinStates.SELECTED:
			if( downSkin == null )
			{
				downSkin = new Sprite();
				downSkin.graphics.beginFill(0x333333);
				downSkin.graphics.drawRect(0,0,200,200);
				downSkin.graphics.endFill();
			}
			asset = downSkin;
			break;
		case SkinStates.DISABLED:
		case SkinStates.DISABLED_SELECTED:
			if( disabledSkin == null )
			{
				disabledSkin = new Sprite();
				disabledSkin.graphics.beginFill(0xCC0000);
				disabledSkin.graphics.drawRect(0,0,200,200);
				disabledSkin.graphics.endFill();
			}
			asset = disabledSkin;
			break;
	}
	return asset;
}
    

The following listing shows a complete, custom skin class for a basic button. In the overridden getSkinForState() function, the skin assets are instantiated as Sprites and are drawn using the Flash drawing API:

 
  package
  {
	import qnx.fuse.ui.skins.SkinAssets;
	import qnx.fuse.ui.skins.UISkin;
	import qnx.fuse.ui.skins.SkinStates;


	import flash.display.Sprite;

	
	public class CustomButtonSkin extends UISkin 
	{
		/**@private**/
		protected var upSkin:Sprite;
		/**@private**/
		protected var disabledSkin:Sprite;
	    /**@private**/
		protected var downSkin:Sprite;


		/**
		 *Create a custom button skin
		 */
		public function CustomButtonSkin() 
		{
			super( );
		}

	  
		override protected function getSkinForState(state : String) : DisplayObject
		{
			var asset : DisplayObject;

			switch (state)
			{
				case SkinStates.UP:
					if( upSkin == null )
					{
						upSkin = new Sprite();
						upSkin.graphics.beginFill(0xFF6600);
						upSkin.graphics.drawRect(0,0,200,200);
						upSkin.graphics.endFill();
					}
					asset = upSkin;
					break;
				case SkinStates.DOWN:
				case SkinStates.DOWN_SELECTED:
				case SkinStates.SELECTED:
					if( downSkin == null )
					{
						downSkin = new Sprite();
						downSkin.graphics.beginFill(0x333333);
						downSkin.graphics.drawRect(0,0,200,200);
						downSkin.graphics.endFill();
					}
					asset = downSkin;
					break;
				case SkinStates.DISABLED:
				case SkinStates.DISABLED_SELECTED:
					if( disabledSkin == null )
					{
						disabledSkin = new Sprite();
						disabledSkin.graphics.beginFill(0xCC0000);
						disabledSkin.graphics.drawRect(0,0,200,200);
						disabledSkin.graphics.endFill();
					}
					asset = disabledSkin;
					break;
			}
			return asset;
		}
	}
  }

Once you have created a custom skin, you can apply the skin to a UI component by calling the appropriate skinning method. For example, to apply a skin to a button, you can pass the skin class that you just created into the setSkin() method:

 
   		
myButton = new Button()
myButton.width = 100;
myButton.setSkin(CustomButtonSkin);
addChild(myButton);

For an example of a custom CellRenderer skin that is used to create a custom List, see the example in the AlternatingCellRenderer class documentation.

For a background on the skin assets that are shipped with this SDK, see Skin assets.



Interfaces

 InterfaceDescription
 ISkin The ISkin interface is the interface for component skins.

Classes

 ClassDescription
 SkinAssetConstants SkinAssetConstants contains a list of skin identifiers used to instantiate a component.
 SkinAssets Contains all the assets used by the White and Black themes for AIR SDK Components
 SkinStates The SkinStates class defines the skin states that are referenced by the skin classes.
 UISkin The UISkin class contains the base skin implementation for all UI component skins.



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus