ActionScript.org Flash, Flex and ActionScript Resources - http://www.actionscript.org/resources
Creating AIR widgets using SPAS 3.0 and Flash
http://www.actionscript.org/resources/articles/875/1/Creating-AIR-widgets-using-SPAS-30-and-Flash/Page1.html
Pascal ECHEMANN
I'm an ActionScript developer in the French Riviera.
I've created the Swing Package for ActionScript 3.0 (SPAS 3.0) which helps Flash developers to easily create RIAs with the Flash Platform and both Flash and Flex:
http://www.flashapi.org/ 
By Pascal ECHEMANN
Published on April 9, 2009
 
In this tutorial we will see how it is easy to create AIR widgets using SPAS 3.0 "uiobjects" and the Flash IDE.

Taken time: 30 min.
Difficulty: intermediate

Creating AIR widgets using SPAS 3.0 and Flash

1. Introduction

SPAS 3.0 Clock Widget

In this tutorial we will see how it is easy to create AIR widgets using SPAS 3.0 “uiobjects” and the Flash IDE. If you have never used the Flash IDE to make AIR applications, you can see the video tutorial by Lee Brimelow called “Developing AIR in Flash”. (You can get this tutorial at the following URL: “http://www.gotoandlearn.com/index.php?as=3”.)

The code in this tutorial is based on SPAS 3.0 alpha 2.1 release.
We assume that you are familiar with external files programming and that you already have downloaded SPAS 3.0.
You can download SPAS 3.0 alpha 2.1 release at: http://www.flashapi.org/

2. Creating the analog clock widget

First, create a Flash AIR application called “clock” and set the class path to your SPAS 3.0 folder. Then, open the “Action” panel to start coding the clock widget.

The base procedure to work with SPAS 3.0 from the Flash main timeline is always the same. So, you should be familiar with the lines of code below if you have already read the tutorial “Creating widgets fast and easily with SPAS 3.0”:

[as]import org.flashapi.swing.*;
UIManager.initialize(this);[/as]

The UIManager's initialize method is used by SPAS 3.0 to access the root document class and get a reference of the stage object. Now we have initialized the UIManager, we can create all SPAS 3.0 “uiobjects” exactly as we do inside an “org.flashapi.swing.Application” class instance.

To put current OS time on the desktop, we can use the AnalogClock class, that creates a visual analog clock object. But instead of simply put it on the desktop, we can add it into a ReactivePanel instance. ReactivePanels can automatically interact with mouse actions to create nice mouse effects. This class had specially been developed to wrap AIR widgets and to apply them a Vista-like widget appearance.
So, here is the code that we have to write:
[as]// Creates an AnalogClock instance
var clock:AnalogClock = new AnalogClock();
// Creates a ReactivePanel instance
var panel:ReactivePanel = new ReactivePanel();
// Adds the clock to the panel's display list
panel.addElement(clock);
// Displays the panel on the top of the stage
panel.display();[/as]

3. Visually improving the widget

Now, if you compile the project, you will see that the reactive panel do not displays the entire clock. To fix that, we can set the panel's “autoSize” property to “true”. When set to true, this property resizes the uicontainer to fit its content.

[as]// Creates an AnalogClock instance
var clock:AnalogClock = new AnalogClock();
// Sets the clock's margin to 4px
clock.margin = 4;
// Adds a shadox effect to the clock
clock.shadow = true;
// Creates a ReactivePanel instance
var panel:ReactivePanel = new ReactivePanel();
// Adds the clock to the panel's display list
panel.addElement(clock);
// Sets the panel's padding to 0px
panel.padding = 0;
// Resizes the panel to fit its content
panel.autoSize = true;
// Displays the panel on the top of the stage
panel.display();[/as]

The preceding lines of code show that you can use all the properties from the UIObject class with both, AnalogClock and ReactivePanel classes.

4. Displaying time with the widget

Displaying the OS time is quite easy with the AnalogClock class. To do that, we only use two methods, as shown below:

[as]// Starts the clock
clock.start();
// Sets the clock's time by using the OS current time
clock.setCurrentLocalTime();[/as]

Unfortunately, the clock's time can be distorted due to the fact that Flash objects use the resources of the unit process. To prevent that problem, we can synchronize the clock widget with the OS time. The following process calls the “onSynchronize” method each 5 minutes (5 ' is equal to 300''), and uses the clock.setCurrentLocalTime() method to synchronize the clock:

[as]// Calls the onSynchronize method each 300 seconds
clock.autoSynchronization = 300;
// Uses the setCurrentLocalTime method to synchronize the clock
clock.onSynchronize = clock.setCurrentLocalTime;[/as]

5. Moving the widget

With the AIR API, it is really easy to move application windows; we just have to use the NativeWindow startMove() method in combination with the UIMouseEvent “press” event. This event is fired by the ReactivePanel instance when you press the mouse left button over it. The startMove() method is used to begin a system-controlled move of the window. As we said before, we can start dragging the window when the mouse left button is pressed over the panel by adding a mouse event listener on it:

[as]// Adds the mouse press and move event
panel.addEventListener(UIMouseEvent.PRESS, doDrag);
function doDrag(e:UIMouseEvent):void {
stage.nativeWindow.startMove ();
}[/as]

For more information about the methods and properties of the AIR windowing API, such like closing and resizing methods, see the ActionScript 3.0 Language Reference:
http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/

6. The full code

Well, our clock widget is finished now! Your final code should look like this one:

[as]import org.flashapi.swing.*;
import org.flashapi.swing.event.*;

UIManager.initialize(this);

var clock:AnalogClock = new AnalogClock();
clock.margin = 4;
clock.shadow = true;
clock.start();
clock.setCurrentLocalTime();
clock.autoSynchronization = 300;
clock.onSynchronize = clock.setCurrentLocalTime;

var panel:ReactivePanel = new ReactivePanel();
panel.addElement(clock);
panel.padding = 0;
panel.autoSize = true;

panel.addEventListener(UIMouseEvent.PRESS, doDrag);
function doDrag(e:UIMouseEvent):void {
stage.nativeWindow.startMove ();
}

panel.display();[/as]

As you see, the SPAS 3.0 API needs very tiny code to create fun AIR applications. Of course, this is a basic example, and you can add as many functionalities as you want to extend the clock's abilities. For example, the commented source file provided with this tutorial uses a CloseButton instance to remove the AIR native window from the runtime application.

7. What next?

SPAS 3.0 is still shared as an alpha version. That is why you can find some bugs and have some strange behaviors. If you find something that does not work, you help us by reporting it to the bugs tracking system from the download manager. If you get suggestions about improvements and new useful functionalities, feel free to send them us; we answer all the emails we receive. And of course, feedbacks are welcome.

I hope you've enjoyed this tutorial.
You can find more resources and tutorials on the SPAS 3.0 Web site at: http://www.flashapi.org/