by Robert L. Dixon

Robert L. Dixon
  • Content architect
  • Adobe

Created

10 June 2010

This article documents the sample application WeatherStation, shown in Figure 1. The WeatherStation application window is partially transparent and it does not use system chrome, so it displays rounded and irregular borders instead of the usual rectangular frame. It also displays images that extend beyond the visual border of the application. The application queries weather forecast data from the Yahoo! Weather service based on a U.S. ZIP code. Data is returned from the service as XML and the application then parses, formats, and displays the data.

This sample application demonstrates the following Adobe AIR features:

  • A window with a transparent background and a non-rectangular border
  • Window control buttons for minimizing and closing the window
  • Moving the window by responding to the "move" event

The WeatherStation sample also shows how some powerful Flash Player features can be used within an Adobe AIR application, including:

  • Calling an HTTP service to retrieve weather forecast data
  • Storing and retrieving application settings using a SharedObject

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

This sample application includes the following files:

  • WeatherStation.mxml: The main application file in MXML for Flex; includes the code discussed in this article
  • WeatherServices.mxml: An MXML file that defines the HTTPService call and its parameters.
  • WeatherStation-app.xml: The AIR application descriptor file
  • close_icon.png/minimize_icon.png: Images used for the window custom chrome buttons
  • Sample AIR icon files

Important

The application descriptor file, WeatherStation-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.

About transparent window applications

Adobe AIR supports both opaque and transparent application windows. Transparent windows let the operating system's desktop show through, while opaque windows obscure the desktop area behind them.

An AIR window can use the borders, title bar, menu bar, and window control buttons (known collectively as system chrome ) that are standard for the operating system. Your application uses the standard system chrome elements when the <systemChrome> element in the application descriptor file is set to standard (the default setting). A window that uses system chrome is always opaque.

The Flex WindowedApplication component provides an alternate set of window chrome elements and a rectangular window frame. The WindowedApplication component's window is always opaque as well.

If you want your application to be transparent, it should not use system chrome or the WindowedApplication component. This means that the application must provide its own mechanisms for controlling the window and its background.

Understanding the code

The WeatherStation application performs other interesting functions such as communicating with a remote HTTP service, parsing an XML result using the new ActionScript 3.0 E4X syntax, and storing and retrieving settings data using a SharedObject. For more information about these functions, see the ActionScript 3 Developer's Guide.

Note: This article does not describe all of the Flex components used in the MXML code for the file. For more information, see the ActionScript 3 Reference for the Adobe Flash Platform.

Setting the window transparency

The transparency of the application window is controlled in two places.

First, the application descriptor file for the application contains two elements that affect window transparency: the <systemChrome> element and the <transparent> element. The <transparent> element must be set to true . The <systemChrome> element should be set to none or else the standard system window title bar and buttons are used, and the application background will be opaque.

The following example shows these elements within the <initialWindow> element of the WeatherStation application descriptor file:

<initialWindow> <title>WeatherStation</title> <content>WeatherStation.swf</content> <systemChrome>none</systemChrome> <transparent>true</transparent> <!-- additional settings... --> </initialWindow>

Second, the CSS styles that are applied to the Flex Application component can affect how that component's background is displayed and whether it is opaque or transparent. To make sure that the background is transparent, the WeatherStation.mxml file includes the following CSS style declaration:

<mx:Style> Application { background-color:""; background-image:""; padding: 0px; } /* additional style declarations... */ </mx:Style>

Moving the application window

A user can move the WeatherStation window around on the desktop by clicking anywhere in the background of the window, holding the mouse down, and dragging the window to another location. To trigger the window-moving process, the application monitors and responds to the MouseEvent.MOUSE_DOWN event.

First, the Application declaration specifies that the initApp() method handles the creationComplete event.

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*" usePreloader="false" creationComplete="initApp()" layout="absolute" width="250" paddingRight="0" paddingLeft="0">

After the application is loaded, the initApp() method sets up mouseDown event listeners on the two visible VBox components. When the user presses the mouse button while the cursor is over one of these VBox components, the onMouseDown() method is loaded.

// adds mouseDown listeners so a click and drag on the background or the // display area lets you move the window this.bgBox.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown); this.tempBox.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);

The onMouseDown() method shows how simple it can be to start the window moving sequence:

private function onMouseDown(evt:MouseEvent):void { stage.nativeWindow.startMove(); }

Calling the NativeWindow.startMove() method results in the window moving around the desktop in response to mouse movements until the mouse button is released. You don't need to write additional code to control the window moving and stopping sequence; it is handled automatically.

Minimizing and closing the application window

The WeatherStation application uses small Button components to let the user minimize or close the application.

Each button's click event is set to trigger an appropriate method, as follows:

<mx:Button id="minimizeBtn" icon="@Embed('assets/minimize_icon.png')" width="16" height="16" click="onMinimize(event)" /> <mx:Button id="closeBtn" icon="@Embed('assets/close_icon.png')" width="16" height="16" click="onClose(event)" />

When the minimize button is clicked, the onMinimize() method calls the NativeWindow.minimize() method:

private function onMinimize(evt:MouseEvent):void { stage.nativeWindow.minimize(); }

When the close button is clicked, the onClose() method calls the NativeWindow.close() method:

private function onClose(evt:MouseEvent):void { stage.nativeWindow.close(); }

The NativeWindow.close() method terminates the application. It does so asynchronously, and a close event is started when the application is about to stop. The application can listen for the close event and perform various clean-up or housekeeping functions before the application stops.

Casting a shadow on the desktop

The WeatherStation window appears to cast a shadow on the desktop as if it was floating above it. In fact, the drop shadow is not applied to the window itself. It is applied to the bgBox VBox component that's used as a background element, and it casts a shadow on the applications window's transparent background. This makes it seem like the shadow is falling on the desktop instead.

To achieve this effect, the application first defines an instance of the flash.filters.DropShadowFilter class:

public var shadowFilter:DropShadowFilter;

The initApp() method then sets the parameters of the filter and applies the filter to the bgBox component and a number of other components, as follows:

// creates a generic drop shadow to use on components that don't accept CSS shadow styles shadowFilter = new DropShadowFilter(); shadowFilter.color = 0x000000; shadowFilter.alpha = 0.4; shadowFilter.blurX = 5; shadowFilter.blurY = 5; shadowFilter.distance = 5; // 'external' shadows addShadow(this.bgBox); addShadow(this.largeImage); // 'internal' shadows addShadow(this.locationTxt); addShadow(this.tempTxt); addShadow(this.conditionTxt); addShadow(this.additionalTxt);

Because the largeImage Image object extends beyond the boundaries of the bgBox component's background, it also needs a shadow to make the illusion complete. The other display components are only given shadows because they seem to stand out better that way.

The same DropShadowFilter instance is applied to each of the components in the addShadow() method:

/** * Adds a standard drop shadow to a display object. */ public function addShadow(comp:DisplayObject):void { comp.filters = [this.shadowFilter]; }

Each component is passed as an argument to this method and treated as a DisplayObject instance (so the same method could be used for DisplayObject instances that are not Flex UIComponent instances too). Each object's filters array is then set to an array containing the one shadowFilter object.

Requirements

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.

User level

Intermediate