Dynamic covers

Dynamic covers are quite useful as they can provide the user with specific information regardless of the current application context. For example, a calendar application might show details about the next event.

The image on the right shows an application cover that contains dynamic content. The content of the cover contains information about recent updates from a user's friends.

active_frame_fb

For a more advanced sample of a dynamic active frame, check out the ActiveFrameSample sample on GitHub.

Creating a dynamic cover

You can create a dyanic cover for your AIR application that updates the user on the state of the application, or on any information that changes while the application is minimized.This example creates a dynamic active frame that displays the time.

  1. 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.NativeWindow;
    	import flash.display.NativeWindowInitOptions;
    	import flash.display.NativeWindowSystemChrome;
    	import flash.display.NativeWindowType;
    	import qnx.system.QNXSystem;
    	import qnx.system.QNXSystemPowerMode;
    	import qnx.events.QNXSystemEvent;
  2. In the root of your class, create variables for the cover and a cover label.
    private var cover:NativeWindow;			
    private var coverlabel:Label;				
  3. In your constructor, set up event listeners to detect changes to your cover.
        //Setup some listeners for the covers.
    			QNXCover.qnxCover.transition = QNXCoverTransition.NONE;				
    			QNXCover.qnxCover.addEventListener(QNXCoverEvent.COVER_SIZE, onCoverSize );	
    			QNXCover.qnxCover.addEventListener(QNXCoverEvent.COVER_ENTER, onCoverEnter );
    			QNXCover.qnxCover.addEventListener(QNXCoverEvent.COVER_EXIT, onCoverExit );	

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

  4. In your constructor, set up an event listener to listen for an alarm to trigger when the app is minimized.
       //Create an event listener for the alarm when minimized.
    			QNXSystem.system.addEventListener(QNXSystemEvent.ALARM, onAlarm );	
  5. Create a private function called onCoverSize that is called when the COVER_SIZE event is triggered.
    //Creates and resizes the cover.
    private function onCoverSize( event:QNXCoverEvent ):void
    {
    }
  6. Using the onCoverSize function, check to see if a cover has been created. If that function does not find a cover, it creates a new NativeWindow to be 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;
    
        // Create a label for your cover
    
        // Define the format of your label
    
        // Add the label to the cover
    }
    // resize the cover
    // activate the cover
     
  7. Create a label for your cover and use TextFormat to define its style. In the coverlabel.text line, call the parseTime() function to update the time.
    	
    // Create a label for your cover
    coverlabel = new Label();
    coverlabel.text = parseTime();
    // 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 );
  8. 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();
    
    QNXCover.qnxCover.setCoverFromWindow( cover );
    
  9. Create the function onCoverExit(event:QNXCoverEvent) to cancel the alarm when the active frame closes.
    	
    //Stops the alarm when the cover is no longer visible.
    		private function onCoverExit( event:QNXCoverEvent ):void
    		{
    			QNXSystem.system.cancelAlarm(__alarmID);
    		}
    
  10. Create the function onCoverEnter(event:QNXCoverEvent) to trigger the alarm every second. Use QNXSystem.system.setAlarm() to set the alarm with a duration = 1000ms (1 second) and repeat = true.
    	
    		//Start the alarm when the cover is shown.
    		private function onCoverEnter( event:QNXCoverEvent ):void
    		{
    			//Updating covers frequently may cause some renders to be skipped.
    			__alarmID = QNXSystem.system.setAlarm( 1000, true );
    		}
    
  11. Create a function called parseTime() to create a string that parses the time to display on the cover.
    	
    		//Parse the time.
    		private function parseTime():String
    		{
    			var now:Date = new Date();
    			var mins:int = now.getMinutes();
    			var secs:int = now.getSeconds();
    			var str:String = now.getHours() + ":" + ((mins < 10 ) ? "0"+mins:mins) + ":" + ((secs < 10 ) ? "0"+secs:secs);
    			return( str );
    		}