The AbeLib library is a general purpose actionscript library. This library contains six distinct parts :

• The abe.com.mon and abe.com.patibility packages contains all the general utilities, interfaces and classes used by the rest of the library. In abe.com.patibility you can find all the codecs and the gettext implementation used by the rest of the library.

• The abe.com.mands and the abe.com.munication packages contains all the command pattern’s implementations and some concret implementations of commands dealing with server call and web services.

• The abe.com.motion and the abe.com.media packages contains the classes in charge of making things move.

• The abe.com.ponents package contains the complete sets of components I created, with their own interfaces, classes and utilities.

• The abe.com.prehension package contains example and demos.

• The abe.com.pile package contains the utilities to compile at runtime using Eval Hurlant.

The AbeLib library components set have many dependencies regarding different set of features and since conditionnal compilation can’t be used with import statements, even if you don’t use the these features you should link these dependencies in your project to avoid missing dependencies at compile time.

• The whole lib use signals from the AS3Signals library from RobertPenner.

• The spell checking in text components is performed with the Adobe Spelling SDK, the only *.swc required from the Adobe Spelling SDK is the AdobeSpellingEngine.swc file.

• Classes related to ressources loading and management make usage of the AS3SWF library to parse the bytecode of a *.swf file and extract its ressources.

• The EasingFunctionPicker component use Eval Hurlant to compile the easing function at runtime.

• The unit tests and the test runner are based on Flex Unit and Hamcrest AS3.

The AbeLib library make an heavy use of the actionscript’s conditionnal compilation feature. Conditionnal compilation is used to differenciate builds and to include or exclude functionnalities from the components.

The list and description of all the conditionnal compilation constant are available in the github wiki of this project. See also the patch-flex-config.xml for a standard configuration.

The AbeLib library use four custom metadatas tags :

• Skin

• SKinable

• Form

• FormList

• SettingsBackend

Those tags are mainly used by the components. The two first tags, Skin and Skinable, are used to declare and link styles to components. The following two tags, Form and FormList, are used to generate forms from objects by using the informations provided by these tags. The last one, SettingsBackend is used in combination with the ComponentFactoryPreload to specify the concret backend to use to handle the application settings management.

The list and description of all the custom metadata tags are available in the documentation annexes. See also the patch-flex-config.xml for a standard configuration.

The class documentation is mostly written in French, with some parts in English, I actually look for a way to translate the whole translation without having to change all the source code documentation but it doesn’t seems as easy as it’s sounds.

When generating the documentation using the TARGET::FLASH_10_1 or TARGET::FLASH_10 constant to true, the generation fail silently, without any informations regarding the reason of the failure. It seems it’s related to the menuContext declaration in the AbstractComponent class. But when I isolate that declaration, I can reproduce the ASDoc failure. In consequences, I recommend you to generate the documentation with the TARGET::FLASH_9 constant to true.

The components set is widely inspired by the Swing components from java but with some noticeable differences due to the specifity of the graphical layer of the Flash Player and the differences in both API.

• Components layout is performed on the same basis as in Swing. A layout object is responsible in computing the preferred size of the component and layout its content during the repaint process.

• The components repaint is performed using the same kind of centralized validation. Each invalidated components is registered in a RepaintManager that check the graphical structure to find the real validation root.

• Many components reuse the same kind of model object as in their Swing equivalent.

• Many interactive components such as Button, MenuItem, ListItem support the Action pattern as in Swing.

• The handling of keyboards shortcuts and accelerators is pretty much the same as in Swing, with the presence of a KeyStroke object which represent a combination of keys. To ensure that a KeyStroke for a combination is unique the KeyStroke class provide a static method to retreive the unique instance of KeyStroke for this combination.

• The Drag and Drop operations use the same kind of Transferable and DataFlavor patterns than Swing. Furthermore, the interfaces for DragSource and DropTarget are pretty identical to the Swing ones.

• The whole styling and skinning API is completely different than the Swing one. In the AbeLib lib, component’s skin can be declared as metatag directly in the component class or directly by in code, as instance of the ComponentStyle class. Furthermore, each component’s style is part of a styles tree that support style inheritance in a CSS like approach. For exemple, all the defaults component’s styles inherit from the DefaultComponent style declared in the skin manager. Additionnaly, component’s styles can be modified on a per component basis (as with the style attributes in CSS) by using the style property of any component.

• The process of painting a component is also completely different. In the AbeLib components, each component had three internal Sprites that represent respectively: the background decoration, the children container, the foreground decoration. A ComponentStyle instance compose two objects responsible of the component’s decoration repaint, those objects must implements the ComponentDecoration interface. Each component’s decoration object is like a graphical processor responsible for drawing into the corresponding Sprite the graphics for a component. These graphics can be vector based or bitmap based, it doesn’t matter.

• The components and their layouts doesn’t support neither minimal size nor maximal size, since it supposed an overload in the layout process for only two or three components that really need it.

• There’s nothing like the lighweight and heavyweight distinction between components. All the components are heavyweight components (that means all components are repainted only once per frame).

Below is a little snippet I use as base in most of my projects.

package

{ import abe.com.mon.logs.Log; import abe.com.ponents.utils.ToolKit; import flash.display.Sprite; public class MyClass extends Sprite { public function MyClass () { // Register the root of the application to get a global access from anywhere // and generates the debug tools if CONFIG::DEBUG is true // The extra argument define the initial visibility of the debug tools ToolKit.initializeToolKit(this, true); try { // Your code here } catch( e : Error ) { // Log.error automatically handle Error objects Log.error( e ); } } } }

The ToolKit class is a component dedicated utility class. Its first role is to setup the stage in order to the component set to work properly. In detail, the ToolKit.initializeToolKit method will do the following :

• Setup the StageUtils class. The StageUtils class is a core utility class which provide, when initialized properly, a global access to the stage. In addition to the global access to the stage, the StageUtils class provides some static methods to setup the stage with some presets. The ToolKit class will set the stage as flexible (no scaling and aligned to top-left).

• Setup the KeyboardControllerInstance event provider to allow keyboard controls.

• Creating seven sprites and place them as children of the display list root. These sprites are :

  1. mainLevel : This is where you should add your application content. Its the lowest layer of the toolkit.

  2. mouseCatcherLevel : This is where mouse catcher of the PopupUtils are placed.

  3. toolLevel : You can use this level to display some stuff that should be displayed above the content and popups but below the cursors and the tooltips (such as the selection rectangle of a select tool).

  4. popupLevel : This is where the PopupUtils class will add the Dialog or Window when added to the display list. It ensure that all the popups and windows are displayed above the application content.

  5. dndLevel : This is where the Drag and Drop renderers will display the drag process.

  6. tooltipLevel : This is where the ToolTip instance reside.

  7. cursorLevel : This is where the custom cursors display object are added.

• Initialize the Cursor class with the corresponding level if the compilation constant FEATURES::CURSOR is enabled.

You’ll encounter errors with some components if you try to instanciate them before the toolkit initialization.

As pointed in the section about conditionnal compilation, there’ll be a minimal setup to do in order to compile this example properly. There’s two approach :

1. Using the -define+=NAMESPACE::CONSTANT,value compiler option.

2. Using a custom flex-config.xml file and the -load-config=FILE compiler option.

The first one is more convenient when you have a really specific features configuration for your file, the second is more convenient in the daily work. My way of doing it is to create a bunch of predefined flex config file for some general configuration (debug, release, with server, etc…), and use the first approach if I need to change some settings towards the default ones.

Since Flex 4.5, the compiler allow to override a constant defined in a flex-config file, then it’s now possible to modify only the constants which differ for each file.

Let’s take a look to the first one. Below, an example of a compilation command line with all the conditionnal compilation constants defined as command line arguments :

mxmlc -source-path+=PATH_TO_THE_ABE_LIB_SRC_FOLDER \ -library-path+=PATH_TO_THE_SQUIGGLY_SWC \ \ -define+=CONFIG::DEBUG,true \ -define+=CONFIG::RELEASE,false \ -define+=CONFIG::WITH_DISTANT_SERVER,false \ -define+=CONFIG::WITH_LOCAL_SERVER,false \ -define+=CONFIG::WITHOUT_SERVER,true \ \ -define+=TARGET::WEB,true \ -define+=TARGET::AIR,false \ -define+=TARGET::FLASH_10_1,true \ -define+=TARGET::FLASH_10,false \ -define+=TARGET::FLASH_9,false \ \ -define+=FEATURES::SPELLING,true \ -define+=FEATURES::AUTOCOMPLETION,true \ -define+=FEATURES::CURSOR,true \ -define+=FEATURES::DND,true \ -define+=FEATURES::TOOLTIP,true \ -define+=FEATURES::MENU_CONTEXT,true \ -define+=FEATURES::KEYBOARD_CONTEXT,true \ -define+=FEATURES::SETTINGS_MEMORY,true \ -define+=FEATURES::BUILDER,false \ \ -output=MyClass.swf \ – MyClass.as

Then, if you launch the compiled *.swf file in the Flash Player you can have a taste of the whole components set since many basic components are used to create the DebugPanel.

The FactoryPlayground file demonstrates a more complex usage of the component set. The FactoryPlayground inherit from the ApplicationMain class, use the ComponentFactoryPreload class as the factory frame, and use a CookieSettingsBackend to store the ui settings in a local shared object.

The compilation of the FactoryPlayground file will require that you set the MAIN_CLASS constant in the compilation command. That constant will tell the ComponentFactoryPreload which class is the main class to instanciate at startup. Note that the path to the main class must be in the getQualifiedClassName syntax.

mxmlc -source-path+=PATH_TO_THE_ABE_LIB_SRC_FOLDER \ -library-path+=PATH_TO_THE_SQUIGGLY_SWC \ \ -define+=CONFIG::DEBUG,true \ -define+=CONFIG::RELEASE,false \ -define+=CONFIG::WITH_DISTANT_SERVER,false \ -define+=CONFIG::WITH_LOCAL_SERVER,false \ -define+=CONFIG::WITHOUT_SERVER,true \ -define+=CONFIG::MAIN_CLASS,“abe.com.ponents.demos::FactoryPlayground” \ \ -define+=TARGET::WEB,true \ -define+=TARGET::AIR,false \ -define+=TARGET::FLASH_10_1,true \ -define+=TARGET::FLASH_10,false \ -define+=TARGET::FLASH_9,false \ \ -define+=FEATURES::SPELLING,true \ -define+=FEATURES::AUTOCOMPLETION,true \ -define+=FEATURES::CURSOR,true \ -define+=FEATURES::DND,true \ -define+=FEATURES::TOOLTIP,true \ -define+=FEATURES::MENU_CONTEXT,true \ -define+=FEATURES::KEYBOARD_CONTEXT,true \ -define+=FEATURES::SETTINGS_MEMORY,true \ -define+=FEATURES::BUILDER,false \ \ -output=FactoryPlayground.swf \ – PATH_TO_THE_ABE_LIB_SRC_FOLDER/abe/com/ponents/demos/FactoryPlayground.as