by Joe Ward

Joe Ward

by Christian Cantrell

Christian Cantrell

Created

10 June 2010

Requirements
Prerequisite knowledge

General experience of building applications
with Flex Builder 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

Intermediate
 
The PixelPerfect sample application, shown in Figure 1, performs basic tasks on window objects. These tasks include creating, resizing, moving, and closing windows.
 
Pixel Perfect application
Figure 1. The PixelPerfect sample application.
 
The PixelPerfect application demonstrates how you can use the Adobe AIR window API to:
 
  • Open multiple windows
  • Obtain a reference to a window
  • Use mouse events to trigger operations on a window
  • Use the startResize() method of the NativeWindow class to resize a window
  • Use the constants of the NativeWindowResize class to specify how a window resize operation is completed
  • Use the startMove() method of the NativeWindow class to move a window
  • Use the close() method of the NativeWindow class to close a window
  • Use full screen mode
  • Keep a window in front of other windows
Note: This is a sample application provided, as is, for instructional purposes.
 
 
Important
The application descriptor file, PixelPerfect-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:
 
xmlns="http://ns.adobe.com/air/application/1.5"
Otherwise, you will not be able to test or package the application.
 

 
Testing the application

Download and install the PixelPerfect installer (PixelPerfect.air) file. To run in the application on Windows, double-click the desktop shortcut for the application or select the file from the Start menu. On Mac OS X, double-click the PixelPerfect application icon, which is installed in the Applications directory by default.
 

 
Understanding the code

PixelPerfect presents a simple user interface that lets users modify application windows. User interactions are implemented using the NativeWindow API. PixelPerfect supports the following user interactions:
 
  • Context menu: Right-click the window to open a menu of window commands.
  • Drag corners or sides to resize: The mouseDown event triggers application logic to run that calculates the mouse position and, if appropriate, makes a call to the NativeWindow.startResize() method.
  • Drag the middle to move: The mouseDown event triggers application logic that calculates the mouse position and, if appropriate, makes a call to the NativeWindow.startMove() method.
  • Arrow keys move one pixel at a time: The keyDown event triggers application logic that detects if an arrow key was pressed. If so, the NativeWindow x or y property is either increased or decreased by 1, depending on whether the arrow that was pressed was the Down Arrow key, the Up Arrow key, the Left Arrow key, or the Right Arrow key. This process occurs each time the user presses an arrow key.
  • Shift + arrow keys resize one pixel at a time: The keyDown event triggers application logic that detects if the Shift key was pressed in combination with an arrow key. If so, the NativeWindow width or height property is either increased or decreased by 1, depending on whether the arrow that was pressed was the Down arrow key, the Up arrow key, the Left arrow key, or the Right arrow key. This process occurs each time the user presses the Shift key in combination with an arrow key.
  • Mouse wheel changes opacity: The event listener that was created to detect activity from the mouse wheel makes a call to an event handler that determines the extent and direction in which the mouse wheel is turned. These values are used to modify the alpha property of the background, which affects the level of transparency.
  • Double-click to quit: The doubleClick event triggers application logic that makes an explicit call to the NativeWindow close() method.
  • Press Ctrl+N to create a window: The keyDown event triggers application logic that detects if the Ctrl+N keys are pressed. If so, a new instance of the Ruler class (which extends NativeWindow ) is created, displaying a new ruler window.
 
Creating a Window
To create a window, PixelPerfect instantiates a new Ruler object. The Ruler class extends the NativeWindow class. In the Ruler constructor, the NativeWindowInitOptions object is created and passed to the NativeWindow super class constructor:
 
public function Ruler(width:uint = 300, height:uint = 300, x:uint = 50, y:uint = 50, alpha:Number = .4) { var winArgs:NativeWindowInitOptions = new NativeWindowInitOptions(); winArgs.systemChrome = NativeWindowSystemChrome.NONE; winArgs.transparent = true; super(winArgs); //... }
The rest of the constructor initializes the properties of the new window and its members.
 
 
Resizing the application window
The startResize() method receives a constant value defined by the NativeWindowResize class that indicates the edge or corner of the window from which the user is dragging the window to resize it. The startResize() method triggers a system-controlled resizing of the window.
 
The application also explicitly sets the window bounds in response to keyboard events. In this case, no resize events are involved. The following code snippet sets the window bounds inside a switch statement:
 
switch (e.keyCode){ case Keyboard.DOWN: if (e.shiftKey) height += 1; else y += 1; drawTicks(bounds); break; case Keyboard.UP: if (e.shiftKey) height -= 1; else y -= 1; drawTicks(bounds); break; case Keyboard.RIGHT: if (e.shiftKey) width += 1; else x += 1; drawTicks(bounds); break; case Keyboard.LEFT: if (e.shiftKey) width -= 1; else x -= 1; drawTicks(bounds); break; case 78: createNewRuler(); break; }
This code snippet also shows the key events used to move the window and to create new windows.
 
 
Moving the application window
The startMove() method is used to begin a system-controlled move of the window. The PixelPerfect sample application uses this method when the mouse device controls the move.
 
When the arrow keys control the parameters of the move, PixelPerfect changes the window bounds, one pixel at a time, by incrementing or decrementing the x or y property of the window. (The code is included in the switch statement in the preceding code snippet.)
 
 
Changing the transparency of the application window
The visible background of the window is a Sprite object that was added to the ruler stage. The application changes the transparency of the background by adjusting the alpha property of the background sprite in response to mouse wheel events:
 
private function onMouseWheel(e:MouseEvent):void { var delta:int = (e.delta < 0) ? -1 : 1; if (sprite.alpha >= .1 || e.delta > 0) sprite.alpha += (delta / 50); } }
For a window to be transparent against the desktop, the window must be created with transparency enabled by setting transparent property to true in the NativeWindowsInitOptions object passed to the window constructor. The transparent property of a window cannot be changed once the window is created.
 
 
Closing the application window
When a doubleclick event is dispatched, PixelPerfect calls the close() method of the window.
 
private function onDoubleClick(e:Event):void { close(); }
A close event is dispatched after the window is closed, signaling the completion of the close process. After a window is closed, it cannot be reopened. Closing the window frees the resources associated with the window (unless they are referenced elsewhere) so that they can be garbage collected. However, the initial window created by AIR is never garbage collected. The application is responsible for closing its windows so that the associated resources can be freed. When the last window of an application is closed, the application also exits. This default behavior can be changed by setting the NativeApplication object autoExit property to false .
 
 
Using fullscreen mode
The contents of a window can be displayed fullscreen by setting the stage displayState property:
 
private function onFullScreenMenuItem(e:ContextMenuEvent):void { stage.displayState = (stage.displayState == StageDisplayState.NORMAL) ? StageDisplayState.FULL_SCREEN : StageDisplayState.NORMAL; }
 
Keeping a window in front of other windows
To keep a window in front of other windows (including those of other applications), set the window alwaysInFront property to true:
 
private function toggleAlwaysInFront(e:Event):void { this.alwaysInFront = !this.alwaysInFront; this.onTopMenuItem.checked = this.alwaysInFront; }
For more information about the methods and properties of the AIR windowing API, see the ActionScript 3.0 Language Reference.