Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Adobe AIR Development

Power Management - Application and System States

by BlackBerry Development Advisor on ‎03-17-2011 11:11 AM - edited on ‎07-20-2011 03:55 PM by Retired (6,239 Views)



This article applies to the following:

  • BlackBerry® Tablet OS





All applications are sent messages to inform them of the state of the application and the system; the messages indicate if each is in active use. When the application is not in active use, it should reduce its resource use so as not to interfere with the foreground application. When the system is not in use, the application should throttle back even more to conserve battery power.


The Adobe® AIR® runtime provides automatic handling of these messages and for some applications this will suffice. However, the runtime tends to err on the side of turning things off when told it is not active. This is done on the basis that a developer will likely notice their application is not behaving properly but might not notice that it is consuming resources when it shouldn't.


Application State


An application can be in two states, activated and deactivated. when an application is activated, it means it is in active use by the user and it is reasonable for it to use resources as it sees fit. Conversely, when it is deactivated, it is not being used, it is likely that the user is not even able to see the application's window so the application should do as little as possible.


An application window has three states. There are:



The application window is full screen on the device and is active.



Your application window has been now a thumbnail. This would happen if the user swiped up from the bottom to minimize the application or swiped from the left and right to toggle between applications.



Your application window is not visible on the screen at all. This usually means that there is another application which is full screen.


To detect application window changes, your code will look something like this:


var win:IowWindow = IowWindow.getAirWindow();
win.addEventListener(IowWindowEvent.WINDOW_STATE_CHANGED, stateChanged );

function stateChanged(event:IowWindowEvent):void {
	switch( win.state ) {
		case IowWindowState.NORMAL:
			trace( "app is full screen" );
		case IowWindowState.THUMBNAIL:
			trace( "app is minimized" );
		case IowWindowState.HIDDEN:
			trace( "app is hidden" );


Note: The above code works per window in an application including your main window. The window on the HDMI display will have different states if you are not running in mirror mode.


System States


The system itself can be in two states, active and standby. When active, there is content displayed and the user is likely using the system. In standby, the user is either passively using the system, for example listening to music, or not using it at all. Ideally, the two states of using passively and not using at all would be distinguished, but that is not the case right now.


AIR fires events to signal when these various states are entered. In the case of the activated and deactivated states, the player uses the standard AIR events Event.ACTIVATE and Event.DEACTIVATE dispatched by the NativeApplication class. For the system states, the events QNXSystemEvent.ACTIVE and QNXSystemEvent.STANDBY are dispatched by the QNXSystem class. The QNXSystem class can also fire a third event QNXSystemEvent.INACTIVE to allow a distinction between a user passively using the system and not using it at all but this third event is currently not used.


Default State Change Behaviour


The default behaviour of the player in response to deactivated and system standby messages is to switch to a lower power mode and release resources such as the accelerometer and geolocation service. In many cases this the right thing to do though in cases where it is not, an application has full control. While likely undesirable an application can continue to operate as if it is the foreground application despite messages to signal it to behave otherwise.


AIR Power Modes


The AIR player in the BlackBerry Tablet OS supports the concept of power modes, different modes of operation that trade off battery consumption for degree of interactivity. To understand what these modes are it is necessary to have a basic understanding of how the player operates.


AIR has a periodic timer that runs at the frame rate. So for a typical application set to 30fps, AIR wakes up 30 times a second to see if there is something to do. In each frame, AIR first executes any ActionScript® code associated with expired timers and onEnterFrame event listeners and then if anything has changed on the stage, renders the area affected.


As well as this periodic timer, external events such as touch and keyboard input, input from the network and PPS objects can wake up AIR and perhaps have it execute ActionScript though normally do not perform rendering.

This is part of what makes AIR applications a little problematic as regards power consumption, even if the application is not doing anything there's still this pesky 30hz timer constantly waking it up just to discover it has nothing to do.


Power Modes


There are three power modes that work by modifying the rendering done by AIR and the frequency of the timers it uses. These modes are:



AIR operates as described in the previous section. This uses the most power but is the only mode in which AIR is really operating as it should.


In this mode, rendering is disabled and the periodic timer runs at a maximum of 4Hz. This means that ActionScript timers created using setInterval or setTimeout and onEnterFrame listeners will be executed no more frequently than this.


This is a special mode found only on the BlackBerry Tablet OS. In this mode, as well as rendering being disabled the AIR timer is stopped entirely. In this mode an AIR application may remain completely inactive for hours at a time. As we shall see though this does not have to mean it is totally lifeless.

ActionScript code can switch the power mode the player is operating in at any time. In addition, certain external events can automatically switch the mode making it possible to be a green application without expending a great deal of effort.


Don't think that just because your application is the active app, it has to be operating in normal power mode, there is nothing to stop it from switching to standby mode for example if it is simply sitting waiting for user input. If there is a call for it, AIR could automatically switch out of standby mode on user input to make this easier to program.


Automatic mode changes


AIR will automatically switch power modes in some circumstances. By default, when an application is deactivated, that is you swipe up from the bottom the power mode switches to the standby state and when you click on the app to make it active again it reverts to normal. This is why AIR applications freeze when they are put into the background.


You can however choose what power mode your application should go in by adding an entry to the qnx tag in the application descriptor file. For example, if you have:



in your application descriptor, the application will switch to throttled mode instead of standby.


Your application does not have to be frozen in whatever state it was in when the user swiped up. If you have a listener for the DEACTIVATE event you can update the stage and have it rendered on the screen before the new power mode takes effect. If you really need to make it fancy and have a transition into the inactive look, you can delay the move to the new power mode using the QNXSystem class described below.


QNXSystem class


AIR provides the qnx.system.QNXSystem class to allow control over power modes. All interaction with this class is through a singleton instance accessed through the static member system.

Changing power modes


To change the current power mode, you execute:


   QNXSystem.system.powerMode = QNXSystemPowerMode.NORMAL;
QNXSystem.system.powerMode = QNXSystemPowerMode.THROTTLED;
QNXSystem.system.powerMode = QNXSystemPowerMode.STANDBY;

If you switch from normal mode to any other, you always have a chance to render at least a frame before the change takes effect.


Delaying the switch out of normal power mode


If you need to have some visual effect when the power mode changes you won't get it if, as by default, you only get to render a single frame. Rather than having to manually set the power mode to normal, perform the effect and then switch to the lower power mode, you can have AIR do this for you. If you set the property transitionTime to a non-zero value, AIR will wait until there has been this duration (in ms) without a window update before changing modes.


So for example to have all changes out of normal mode wait for half a second of inactivity, you would execute:

   QNXSystem.system.transitionTime = 500;



When in standby mode, normal AIR timers don't fire. Well they might, but they'll be waiting for something to kick the normal AIR frame cycle and that might not happen for hours or days.


There is however a way out. The QNXSystem class has a setAlarm function that fires an event after a given time and unlike the normal AIR timers this is always active. The alarm can be one shot or it can be repeating and like the setTimeout and setInterval functions, it returns an alarm id that allows the alarm to be canceled.


Executing a normal AIR frame cycle


If you want to have AIR run through its normal frame cycle to allow standard AIR timers and onEnterFrame listeners to be invoked, you can just call the runFrameCycle to allow this to happen once.


Updating the window in low power modes


If you really need to update your window when your application is in a low power mode, you can just take advantage of the fact that any change from normal to another mode allows you to render a frame (or more if you set transitionTime). So to do this you execute something such as:


   QNXSystem.system.powerMode = QNXSystemPowerMode.NORMAL;
QNXSystem.system.powerMode = QNXSystemPowerMode.STANDBY;

where UpdateWindow is some function that changes the stage. If UpdateWindow is going to do a tween, you might instead change it to:


   QNXSystem.system.transitionTime = 200;
QNXSystem.system.powerMode = QNXSystemPowerMode.NORMAL;
QNXSystem.system.powerMode = QNXSystemPowerMode.STANDBY;

Requesting Resource


AIR will automatically release various resources when deactivated or the system goes into standby. For example, when the system goes into standby, AIR will cease to read from the accelerometer or geolocation sources. To change the default behaviour, the QNXSystem class provides the requestResource and releaseResource functions. These take the name of the resource and indicate that the resource is still needed or no longer needed. So, for example an application that performed GPS logging might request the geolocation resource. The currently defined resources are:



Indicates that the application requires networking.


Indicates that the application requires geolocation data.


Indicates that the application requires accelerometer data.


Indicates that instances if StageWebView and QNXStageWebView should not be deactivated.
Users Online
Currently online: 14 members 1,239 guests
Please welcome our newest community members: