qnx.ui.skins Summary

qnx.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.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.ui.skins.UISkin class. The qnx.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.ui.skins.ISkin interface. The quickest way to create a custom skin is to inherit from the qnx.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.ui.skins.UISkin. In order to determine what assets are associated with each state, each asset must be registered with the skin. To register assets, you must override the protected function initializeStates() in your skin class. You can then register each skin asset by associating an asset with the intended UI component state.

In the following code listing, the initializeStates() function registers each asset to a button state, with the assumption that each asset has been created and instantiated in the class prior to registration:

     
    override protected function initializeStates():void
    {
	setSkinState(SkinStates.UP, upSkin );
	setSkinState( SkinStates.SELECTED, selectedSkin );
	setSkinState( SkinStates.DISABLED, disabledSkin );
	setSkinState( SkinStates.DOWN, downSkin );
	 showSkin( upSkin );
    }
    

In the example above, the setSkinState() method is used to associate a skin asset with each button state. The following listing shows a complete, custom skin class for a basic button. In the overridden InitializeStates() function, the skin assets are instantiated as Sprites and are drawn using the Flash drawing API:

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


	import flash.display.Sprite;


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


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


		override protected function initializeStates():void
		{

		upSkin = new Sprite();
		upSkin.graphics.beginFill(0xFF6600);
		upSkin.graphics.drawRect(0,0,200,200);
		upSkin.graphics.endFill();

		downSkin = new Sprite();
		downSkin.graphics.beginFill(0x333333);
		downSkin.graphics.drawRect(0,0,200,200);
		downSkin.graphics.endFill();

	    	disabledSkin = new Sprite();
		disabledSkin.graphics.beginFill(0xCC0000);
		disabledSkin.graphics.drawRect(0,0,200,200);
		disabledSkin.graphics.endFill();

	    	selectedSkin = new Sprite();
		selectedSkin.graphics.beginFill(0x000000);
		selectedSkin.graphics.drawRect(0,0,200,200);
		selectedSkin.graphics.endFill();


		setSkinState(SkinStates.UP, upSkin );
		setSkinState(SkinStates.SELECTED,selectedSkin );
		setSkinState( SkinStates.DISABLED, disabledSkin );
		setSkinState( SkinStates.DOWN, downSkin );
		showSkin( upSkin );

		}
	}
  }

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
 SkinAssets The SkinAssets class defines the graphic assets that are used in the SDK.
 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.