Create a static cover

You can create a static cover, including a specific image, for your AIR app.

Use an image for a static cover

To create the content for a cover in AIR, using a specific image, you need to define an image, specify some listeners for the covers, and use the setCoverFromFile method.

  1. Create a cover image for your application. The cover image for the BlackBerry Z10 is 396 x 334 pixels. If your app also targets the BlackBerry Q10, you'd need another background image that is 310 x 211 px.
  2. Store the cover image on your BlackBerry 10 device. Take note of its location; you will need it later.
  3. Import the following packages to display your cover.
    import qnx.events.QNXCoverEvent;
    import qnx.system.QNXCover;
    import qnx.system.QNXCoverTransition;
  4. In the root of your class, create a String variable that points to the location of your image on your BlackBerry 10 device.
    private var my_cover : String = "<location of your image>";

    To access your image on the BlackBerry 10 device, make sure to set the access_shared permission in your application. For more information on setting application permissions, see Application permissions.

  5. In your constructor, set up event listeners to detect changes to your cover.
    //Setup some listeners for the covers.
    			
    QNXCover.qnxCover.addEventListener(QNXCoverEvent.COVER_SIZE, onCoverSize );	
    QNXCover.qnxCover.transition = QNXCoverTransition.NONE;	

    You can use QNXCoverTransition to define how your application transitions to the cover.

  6. Create a private function called onCoverSize that is called when the event listener is triggered. It uses the setCoverFromFile method to call your image as an application cover.
    //Creates and resizes the cover.
    private function onCoverSize( event:QNXCoverEvent ):void
    {
    	 QNXCover.qnxCover.setCoverFromFile( my_cover );
    }

Add text to a static cover

If you want to add text to your static cover, you will need to change how your application calls your image. In the previous section, you used setCoverFromFile to set your image as an application cover. In this section, you will use setCoverFromWindow to create a NativeWindow that you can use for your cover.

  1. Create a cover image for your application. The cover image for the BlackBerry Z10 is 396 x 334 pixels. If your app also targets the BlackBerry Q10, you'd need another background image that is 310 x 211 pixels.
  2. Import your cover image into your project.
  3. Import the following packages to display your cover.
    import flash.display.Sprite;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import qnx.fuse.ui.text.Label;
    import qnx.events.QNXCoverEvent;
    import qnx.system.QNXCover;
    import qnx.system.QNXCoverTransition;
    import qnx.display.IowWindow;
    import qnx.fuse.ui.text.TextFormat;
    import flash.display.Bitmap;
    import flash.display.NativeWindow;
    import flash.display.NativeWindowInitOptions;
    import flash.display.NativeWindowSystemChrome;
    import flash.display.NativeWindowType;
  4. In the root of your class, create variables for the cover, the cover label, and the cover bitmap.
    private var cover:NativeWindow;			
    private var coverlabel:Label;			
    private var coverbg:Bitmap;	
  5. In your constructor, set up event listeners to detect changes to your cover.
    //Setup some listeners for the covers.
    			
    QNXCover.qnxCover.addEventListener(QNXCoverEvent.COVER_SIZE, onCoverSize );	
    QNXCover.qnxCover.transition = QNXCoverTransition.NONE;	

    You can use QNXCoverTransition to define how your application transitions to the cover.

  6. Create an internal class, called Assets, this class will contain your image, embedded as the constant COVER.
    internal class Assets {
        [Embed(source="<imagename.jpg>")] public static const COVER:Class;
    }
  7. Create a private function called onCoverSize that is called when the event listener is triggered.
    //Creates and resizes the cover.
    private function onCoverSize( event:QNXCoverEvent ):void
    {
    }
  8. In the onCoverSize function, check to see if a cover has been created. If it has not been created, this function creates a NativeWindow to function as the cover.
    //Create a cover if you haven't already.
    if( cover == null )
    {
    	var windowOptions:NativeWindowInitOptions = new NativeWindowInitOptions();
    	windowOptions.systemChrome = NativeWindowSystemChrome.NONE;
    	windowOptions.type = NativeWindowType.LIGHTWEIGHT;
    				
    	cover = new NativeWindow(windowOptions);
    	//It is important that these next 3 lines come directly after creating the window.
    	var iow:IowWindow = IowWindow.getAirWindow(cover);
    	iow.group = null;
    	iow.numBuffers = 1;
    				
    	cover.stage.scaleMode = StageScaleMode.NO_SCALE;
    	cover.stage.align = StageAlign.TOP_LEFT;
    	cover.visible = false;
    
        // Import your image into coverbg as a Bitmap.
    
        // Create a label for your cover
    
        // Define the format of your label
    
        // Add the label to the cover
    }
    // resize the cover
    // activate the cover
     
  9. In the onCoverSize function, inside the if(cover==null) statement, import your image into the coverbg variable as a bitmap.
     // Import your image into coverbg as a Bitmap.
    coverbg = (new Assets.COVER as Bitmap);
    cover.stage.addChild( coverbg );
    
  10. After you have imported your image, create a label for your cover and use TextFormat to define its style.
    	
    // Create a label for your cover
    coverlabel = new Label();
    coverlabel.text = "The app is running"; 
    
    // Define the format of your label
    var format:TextFormat = coverlabel.format;
    format.color = 0xFA9922;
    format.size = 50;
    coverlabel.maxLines = 0;
    coverlabel.format = format;
    	
    // Add the label to the cover
    cover.stage.addChild( coverlabel );
  11. In the onCoverSize function, outside of the if(cover==null) statement, resize the cover and activate it.
    	
    //resize the cover.
    cover.width = QNXCover.qnxCover.coverWidth;
    cover.height = QNXCover.qnxCover.coverHeight;
    coverlabel.height = cover.height;
    coverlabel.width = cover.width;
    coverbg.height = cover.height;
    coverbg.width = cover.width;
    
    //activate the cover.
    cover.activate();