by Joe Ward

Joe Ward


24 February 2008

Prerequisite knowledge

General experience of building applications
with Flex Builder or the Flex SDK is
suggested. For more details on getting
started with this Quick Start, refer to
Building the Quick Start sample
applications with Flex
Required products

Sample files

User level

When placing or moving windows, you often need to know the dimensions and relative placement of the desktop screens. Adobe AIR provides access to this information through the Screen class. The Screens example application, shown in Figure 1, illustrates how to use the Screen API.
Screens example application
Figure 1. The Screens example application leverages the Screen API in AIR.
Note: This is a sample application provided, as is, for instructional purposes.
This sample application includes the following files:
  • The main application file; includes the code discussed in this article
  • Screens-app.xml: The AIR application descriptor file
  • Sample AIR icon files
The application descriptor file, Screens-app.xml, uses the AIR 1.0 namespace. If you are compiling the application using Flex Builder 3.0.2 or Flex SDK 3.2 or later, edit the file to use the AIR 1.5 namespace:
Otherwise, you will not be able to test or package the application.

About the virtual desktop

The virtual desktop is composed of one or more discrete screens. A main screen is designated (by the operating system) and the origin of the virtual desktop is placed at the top-left-hand corner of this screen. Positive values are to the right and down, as you would expect on a computer display. Screens positioned above and to the left of the main screen have negative coordinates.
The usable area of a screen excludes any task bars, menu bars, dock bars, sidebars, or other bars that are always drawn in front of any windows. The Screen class reports dimensions for both the entire screen and the usable area.

The Screens example application

The Screens application draws a representation of the screens on the virtual desktop, including a scaled down version of its own window. The usable area of each screen is shown in blue. The area that is within the screen, but outside the usable area is shown in gray. A lighter blue highlight is displayed on the screen the application window is on.
To test Screens, download and launch the application's installer (Screens.air) file. You can move the application window around, change monitor resolution and color depth, and change the size and location of task bars to observe the effects on the screen information reported by the AIR Screen API. Use the arrow keys to jump the window from screen to screen (if your computer system has multiple monitors).

Understanding the code

The Screen application uses several graphics functions not specific to AIR. For more information about these functions, see the ActionScript 3.0 Language Reference.
Computing the virtual bounds
A bounds rectangle describes both location and dimension. The virtual desktop bounds rectangle is the bounding box that encloses all of the screens. To compute this bounding box, the Screens application loops through each screen in the array of Screen objects provided by the static Screen.screens property and compares each side of the screen to the current side of the bounding box. If the screen value is further out than the current bounding box value, the bounding box value is pushed out to match the screen. The result is a bounding rectangle that encloses all the screens.
private function computeVirtualBounds(screens:Array):Rectangle{ var bounds:Rectangle = new Rectangle(); for each (var screen:Screen in screens){ if(bounds.left > screen.bounds.left){bounds.left = screen.bounds.left;} if(bounds.right < screen.bounds.right){bounds.right = screen.bounds.right;} if( >{ =;} if(bounds.bottom < screen.bounds.bottom){bounds.bottom = screen.bounds.bottom;} } return bounds; }
Resizing the application window proportionally to the screen
Once the size of the virtual desktop is computed, the size of the application window can be determined. The width of the window is set at 60% of the width of the main screen (plus a little extra for a border). The height of the window is resized proportionally to the virtual desktop so that the window is tall enough to display the entire scaled down representation of the desktop:
var scale:Number = (Screen.mainScreen.bounds.width * .6)/virtualScreenBounds.width; stage.stageWidth = (Screen.mainScreen.bounds.width * .6) + (border * 2); stage.stageHeight = (virtualScreenBounds.height * scale) + (border * 2);
The Screen object for the operating-system designated main screen can be accessed using the static mainScreen property of the Screen class.
Drawing a representation of the desktop
Since the Screens application class extends the Sprite class, sprite graphics functions are used to draw the representation of the desktop. The screens in the desktop are drawn at full size using the screen coordinates. A transformation matrix on the main sprite translates and scales the desktop representation to fit into the display area of the window.
The transformation matrix is created with the Matrix class createBox() method. This method takes the horizontal and vertical scale factors as parameters. The same scale is used for both parameters and is computed by dividing the display area of the window by the total width of the virtual desktop. The createBox() method also takes parameters for how much to shift (or translate) the representation so that it lines up properly on the window.
The redraw() method computes the transformation matrix, assigns it to the matrix property of the main sprite transform object and then calls the functions that draw the elements of the desktop representation. The redraw() method is called in response to the enterFrame event.
private function redraw(event:Event):void{ virtualScreenBounds = computeVirtualBounds(Screen.screens); var scale:Number = (stage.nativeWindow.width - border * 2)/virtualScreenBounds.width; virtualScreenToWindowTransform.createBox(scale, scale, 0, border - (virtualScreenBounds.x * scale), border - (virtualScreenBounds.y * scale)); transform.matrix = virtualScreenToWindowTransform; graphics.clear(); drawScreenRepresentation(); highlightScreens(); drawWindowModel(); }
To draw the desktop, the drawScreenRepresentation() method loops through the screens array of the Screen class. For each screen, the routine draws one rectangle for the entire screen and another for the usable area:
with(graphics){ //Draw screen rectangle beginFill(screenColor,.5); drawRect(screen.bounds.left,, screen.bounds.width, screen.bounds.height); endFill(); //Draw rectangle for usable screen area beginFill(usableScreenColor,.5); drawRect(screen.visibleBounds.left,, screen.visibleBounds.width, screen.visibleBounds.height); endFill(); //...
The method also draws several labels. The labels are drawn into a bitmap with the BitmapData.draw() method. The resulting label bitmaps are drawn to the main sprite using a bitmap fill.
Using bitmap fills
One surprising aspect of using a bitmap fill is that the fill is registered to the origin of the sprite, not the top-left corner of the area to be filled. For repeating textures this may not be an issue, but when used for a label, this can leave the words far outside the filled area. The solution is to use another transformation matrix to move the label bitmap to the filled area. The following lines draw a bitmap containing the words "Main Screen" to the center of the main screen:
//Draw label to show which screen is the "main" screen var mainLabelBitmap:BitmapData = drawLabel("Main Screen"); labelTransform = new Matrix(1, 0, 0, 1, (Screen.mainScreen.visibleBounds.width - mainLabelBitmap.width)/2, (Screen.mainScreen.visibleBounds.height - mainLabelBitmap.height)/2); with(graphics){ beginBitmapFill(mainLabelBitmap,labelTransform,false); drawRect((Screen.mainScreen.visibleBounds.width - mainLabelBitmap.width)/2, (Screen.mainScreen.visibleBounds.height - mainLabelBitmap.height)/2, mainLabelBitmap.width, mainLabelBitmap.height); endFill(); mainLabelBitmap = null; }
Moving a window between screens
The Screens application lets you jump the window from screen to screen using the arrow keys. To figure out where to move the window, the application must determine which screen it is currently on and which, if any, screens lie in the chosen direction.
The current screen can be determined using the static Screen.getScreensForRectangle() method. This method returns an array of all screens with which the rectangle intersects. The following function passes the window bounds into the getScreensForRectangle() method and returns the first screen in the resulting array:
private function getCurrentScreen():Screen{ var current:Screen; var screens:Array = Screen.getScreensForRectangle(stage.nativeWindow.bounds); (screens.length > 0) ? current = screens[0] : current = Screen.mainScreen; return current; }
If the window is somehow off any screen, the main screen is returned.
To find the proper screen to which to move the window, the array of screens is sorted vertically or horizontally and then the relevant coordinates are compared by walking through the sorted array. The following method moves the window to the left:
/*Moves the window to the next screen to the left*/ private function moveLeft():void{ var currentScreen:Screen = getCurrentScreen(); var left:Array = Screen.screens; left.sort(sortHorizontal); for(var i:int = 0; i < left.length - 1; i++){ if(left[i].bounds.left < stage.nativeWindow.bounds.left){ stage.nativeWindow.x += left[i].bounds.left - currentScreen.bounds.left; stage.nativeWindow.y += left[i] -; } } }
The sort method called above uses the following sorting function to compare screen coordinates:
private function sortHorizontal(a:Screen, b:Screen):int{ if (a.bounds.left > b.bounds.left){ return 1; } else if (a.bounds.left < b.bounds.left){ return -1; } else {return 0;} }