Interacting with a window

Back to: Apollo Documentation home page

The PixelPerfect sample application creates a transparent pixel ruler on the operating system desktop. The pixel ruler is represented by a window that can be moved, resized, and changed with respect to display state.

Note: This is a sample application provided, as is, for instructional purposes.

The PixelPerfect application demonstrates how you can use the Apollo 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

To install the application:

Double-click the PixelPerfect.air file.
The PixelPerfect Installer window is displayed.
Click the Continue button.
The Apollo runtime installs the application.

To run the application:

On the Windows operating system, double-click the desktop shortcut for the application or select the file from the Start menu.
On the Mac operating system, double-click the PixelPerfect application icon, which is installed in the Applications subdirectory of the user directory by default.

Contents
Files used to build the application Installing the source files in Flex Builder Understanding the code Modifying window display state and bounds based on user input Creating a Window Resizing the application window Moving the application window Changing the transparency of the application window Closing the application window

Files used to build the application

The application includes the following source files:

File	Description
PixelPerfect.as	An ActionScript class that launches a new ruler window and then exits. This code is described in the topic entitled Understanding the code.
Ruler.as	The ruler window class. Extends the NativeWindow class. Located in package: `com.adobe.pixelperfect`.
PixelPerfect-app.xml	The Apollo application descriptor file.
icons/ApolloApp_128.png	Sample Apollo icon file.

To download the source files for this example, click here (69K).

For help on building this quick start sample application, see How to build the quick start sample applications.

Installing the source files in Flex Builder

To create the PixelPerfect project as a Flex application:

Open Flex Builder.
On the File menu, select New and then select Apollo Project.
The New Apollo Project wizard opens. By default, the Basic data access option is selected for the project to be created.
Click Next.
The wizard advances to a page where you can specify the project name and directory location.
In the Project Name text box, type PixelPerfect. In Project Contents, the Use default location option should be selected.
Advance to the Application XML Properties page.
Fill in the Name, Publisher, Description, and Copyright text boxes.
Click Finish.
Your project is created.
Copy the source files into the project folder (maintaining the package folder structure).
Since the runnable application file for the project is ActionScript not MXML, you must change the project properties:

From the Project menu, select the Properties command.
The Properties For PixelPerfect is displayed.
Select Apollo Applications in the property type list.
The Apollo Applications property page is shown.
Select PixelPerfect.mxml in the list of runnable application files.
Click Remove.
The PixelPerfect.mxml file created for the project by default is removed.
Click Add.
Using the Add Application Files dialog, locate the PixelPerfect.as file in the project folder.
Select the file and click Ok.
PixelPerfect.as is added to the list of runnable application files.
Select PixelPerfect.as.
Click Set as Default.
Click Ok.

Understanding the code

The PixelPerfect sample application performs basic tasks on window objects. These tasks include creating, resizing, moving, and closing windows. The remainder of this document describes how the PixelPerfect uses the Apollo windowing API to complete these tasks.

Modifying window display state and bounds based on user input

PixelPerfect presents a simple user interface that lets users access the NativeWindow API to modify application windows. The following table lists the user interaction that PixelPerfect supports and describes the process that is associated with each of them:

Instruction	Process
Context menu	Right-click on 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 to run 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 it was, the `NativeWindow.x` or `NativeWindow.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 such a key combination was pressed, the `NativeWindow.width` or `Window.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, which affects the level of transparency that is applied to the background color.
Double-click to quit	The `doubleClick` event triggers application logic that makes an explicit call to the `Window.close()` method.
Shift+n to create a new window	The `keyDown` event triggers application logic that detects if Shift-N was pressed. If so, a new instance of the `Ruler` class (which extends `NativeWindow`) is created, displaying a new ruler window.

The following topics describe how the window operations that involve the Apollo window API are completed in the PixelPerfect application.

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 are 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(false, 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 does this inside a switch statement:


switch (e.keyCode)
    {
        case Keyboard.DOWN:
            if (e.shiftKey)
                height += 1;
            else
                y += 1;
            drawTicks();
            break;
        case Keyboard.UP:
            if (e.shiftKey)
                height -= 1;
            else
                y -= 1;
            drawTicks();
            break;
        case Keyboard.RIGHT:
            if (e.shiftKey)
                width += 1;
            else
                x += 1;
            drawTicks();
            break;
        case Keyboard.LEFT:
            if (e.shiftKey)
                width -= 1;
            else
                x -= 1;
            drawTicks();
            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 move is controlled by the mouse device.

When the parameters of the move are controlled by the arrow keys, 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 above.)

Changing the transparency of the application window

The visible background of the window is a Sprite object that has been 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 transparency state 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();
}

When a windows's close() method is called, the NativeWindow object does not dispatch a closing event. If you want to allow cancellation of the close operation, you can dispatch the closing event in your event handler:

private function onDoubleClick(e:Event):void
    var closing:Event = new Event(Event.CLOSING,true,true);
    dispatchEvent(closing);
    if(!closing.isDefaultPrevented()){
        close();
    }
}

A close event is dispatched after the window is closed, signaling the completion of the close process. Once a window is closed, it cannot be reopened. Closing the window explicitly frees the resources that are associated with the window so that they can be garbage collected. It is the responsibility of the application to close 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 Shell object autoExit property to false.

For more information about the methods and properties of the Apollo windowing API, see the Apollo ActionScript 3.0 Reference. For more information about how to use the Apollo windowing API, see Working with windows.

Back to: Apollo Documentation home page