Skinning your UI components

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

Each UI component in the 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 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 made up 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 the qnx.fuse.ui.skins.SkinStates class. An asset uses nine 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 manages 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 create a skin class that implements the qnx.fuse.ui.skins.ISkin interface. The quickest way to create a custom skin is to extend qnx.fuse.ui.skins.ISkin. This gives your skin class a functional base for managing state changes and for associating skins with states. Each asset must be registered with the skin. To register assets, you must override the protected functioninitializeStates() in your skin class. You can then register each skin asset by associating an asset with the intended UI component state.

Change the default skin of a UI component

You can change the color scheme of a segmented control from light (default) to dark by changing the component's skin.

  1. Import the required classes.
    import flash.display.Sprite;
    
    import qnx.fuse.ui.buttons.SegmentedControl;
    import qnx.ui.data.DataProvider;
    import qnx.fuse.ui.skins.buttons.SegmentedControlSkinBlack;
    import qnx.fuse.ui.skins.buttons.RoundedButtonSkinBlack;
  2. Add the following statement to your class, directly before the class signature. This statement sets the stage width and height, the frame rate, and the background color of your application.
    [SWF(height="600", width="1024", frameRate="30", backgroundColor="#FFFFFF")]
  3. Create an application framework by extending Sprite.
    class SkinSample extends Sprite
    {
  4. Create a constructor for the class and invoke initializeUI().
         public function SkinSample()
         {	    
              initializeUI();
         }
  5. Create the initializeUI function to set up and initialize the UI controls.
         private function initializeUI():void
         {
  6. In the initializeUI function, create a SegmentedControl object instance.
              var buttonArray:Array=[];
              buttonArray.push({label:"Monday"});
              buttonArray.push({label:"Tuesday"});
              buttonArray.push({label:"Wednesday"});
              buttonArray.push({label:"Thursday"});
              buttonArray.push({label:"Friday"});
    
              var mySegment:SegmentedControl = new SegmentedControl();
              mySegment.x = 200;
              mySegment.y = 200;
              mySegment.width = 500;
              mySegment.height = 50;
        
              mySegment.dataProvider = new DataProvider(buttonArray);    
              mySegment.selectedIndex = 2;
        
              this.addChild(mySegment);
  7. In the initializeUI function, call the setBackgroundSkin method, passing in the SegmentedControlSkinBlack skin asset class. This changes the background skin of the SegmentedControl instance to the dark color scheme asset.
              mySegment.setBackgroundSkin(SegmentedControlSkinBlack);
  8. In the initializeUI function, call the setButtonSkin method, passing in the RoundedButtonSkinBlack skin asset class. This changes the skin of each button in the SegmentedControl instance to use the asset from the dark color scheme.
              mySegment.setButtonSkin(RoundedButtonSkinBlack); 
         }
    }

Post-requisites: For more information about the light and dark color scheme assets, see the SkinAssets class in the qnx.ui.skins package.

Create a custom button skin class

In the following task, you create a custom button skin and apply it to a set of buttons.

  1. Import the required classes.
    import qnx.fuse.ui.skins.SkinAssets;
    import qnx.fuse.ui.skins.UISkin;
    import qnx.fuse.ui.skins.SkinStates;
  2. Add the following statement to your class, directly before the class signature. This statement sets the stage width and height, the frame rate, and the background color of your application.
    [SWF(height="600", width="1024", frameRate="30", backgroundColor="#FFFFFF")]
  3. In your class signature, extend the UISkin class. The UISkin class implements the qnx.fuse.ui.skins.ISkin interface and provides the base functionality required for loading and registering your skin assets.
    public class CustomButtonSkin extends UISkin
    { 
  4. Create the constructor.
         public function CustomButtonSkin() 
         {
             super();
         }
  5. Override the initializeStates method. The initializeStates function is used to register your skin assets to associate them with UI component states.
         override protected function initializeStates():void 
         {
  6. Create variables for the skin assets. In the following code sample, you create skin assets for the up, down, selected, and disabled skin states.
             protected var upSkin:Sprite;   
             protected var selectedSkin:Sprite;   
             protected var disabledSkin:Sprite;   
             protected var downSkin:Sprite;
  7. In the initializeStates function, create the skin assets. Each skin is instantiated as a Sprite object. Each skin is filled using a different hexadecimal color code to create a unique look for each button state. The drawRoundRect method is used and each button skin has a rounded edge.
          		 upSkin = new Sprite();
             upSkin.graphics.beginFill(0xFF6600);
             upSkin.graphics.drawRoundRect(0,0,50,50, 10,10);
             upSkin.graphics.endFill();
    
             downSkin = new Sprite();
             downSkin.graphics.beginFill(0x333333);
             downSkin.graphics.drawRoundRect(0,0,50,50, 10,10);
             downSkin.graphics.endFill();
    
             disabledSkin = new Sprite();
             disabledSkin.graphics.beginFill(0xCC0000);
             disabledSkin.graphics.drawRoundRect(0,0,50,50, 10,10);
             disabledSkin.graphics.endFill();
    
             selectedSkin = new Sprite();
             selectedSkin.graphics.beginFill(0x000000);
             selectedSkin.graphics.drawRoundRect(0,0,50,50, 10,10);
             selectedSkin.graphics.endFill();
  8. In the initializeStates function, register your skin assets by calling the setSkinState method for each skin asset. The setSkinState method takes a skin state constant and a skin asset. It associates the skin asset with the UI component state, such that when a button is pressed, or a list is rendered, the appropriate skin asset is displayed. In the following code sample, each skin asset is associated with the proper state.
    		 setSkinState(SkinStates.UP, upSkin);
             setSkinState(SkinStates.SELECTED,selectedSkin);
             setSkinState(SkinStates.DISABLED, disabledSkin);
             setSkinState(SkinStates.DOWN, downSkin);
  9. In the initializeStates function, set the default skin state by calling the showSkin method.
    		 showSkin(upSkin);
         }
    } 

Apply a custom button skin

This example assumes that you created the custom button skin class CustomButtonSkin in the same project as the following sample application. Otherwise, you'd need to import the class into your sample application.

  1. Import the required classes.
    import qnx.fuse.ui.buttons.Button;
    import qnx.fuse.ui.buttons.LabelButton;
  2. Add the following statement to your class, directly before the class signature. This statement sets the stage width and height, the frame rate, and the background color of your application.
    [SWF(height="600", width="1024", frameRate="30", backgroundColor="#FFFFFF")]
  3. Create an application framework by extending Sprite.
    class ButtonSample extends Sprite
    {
  4. Create a constructor for the class and invoke initializeUI().
         public function ButtonSample()
         {
             initializeUI();
         }
  5. Create the initializeUI function to set up and initialize the UI controls.
         private function initializeUI():void
         {
  6. In the initializeUI function, create a toggle button that calls the setSkin method. In the following code sample, the setSkin method takes the name of the custom skin class.
    	        var myToggleButton:Button;
        
             myToggleButton = new Button();
             myToggleButton.setPosition(200, 200);
             myToggleButton.setSize(100, 50);			
             myToggleButton.toggle = true;
             myToggleButton.setSkin(CustomButtonSkin);
    
             addChild(myToggleButton);
  7. In the initializeUI function, create a label button that calls the setSkin method.
             var myLabelButton:LabelButton;  
             myLabelButton = new LabelButton();
             myLabelButton.setPosition(200, 300);
             myLabelButton.setSize(150, 50);			
             myLabelButton.label = "My Label Button";
             myLabelButton.setSkin(CustomButtonSkin);
        
             addChild(myLabelButton);
         }
    }
  8. Build and run the application. The buttons are rounded and the colors appears as you defined them the custom skin class. Notice that when you click the buttons, each button state is also skinned.