From MegaZine3
(Redirected from GUI)
Jump to navigation Jump to search

ASUL is an XML based GUI framework. This means that it is possible to define GUI components / using an XML document. This allows a most flexible way of customizing GUI elements, as it is not necessary to hard-code anything (well, almost).

ASUL stands for ActionScript User Interface Language and is a very bad pun on XUL... furthermore it will never offer competing functionality, of course, as it'll always just do as much as it needs to. It was primarily developed for the rewrite of the MegaZine3 engine, but can be used in other contexts, too (as there are no direct dependencies, only on the utility classes).

The original reason for not using MXML was that Asul is not meant to be as complex. I.e. the basic intent was to rebuild the GUI components from 1.x in a more dynamic fashion, nothing more, nothing less. Asul did get a bit bigger than intended, but is still rather small. For more involved endeavors it is strongly recommended not to rely on ASUL, but MXML instead. A Flex bridge is planned, basically consisting of a plugin and a wrapper class, allowing easier interaction.


ASUL consists of a set of given component types, such as simple containers, buttons and so on. Based on this set of components it is possible to build more complex structures by nesting elements. All objects allow child nodes / child components. Some components even require certain child objects for full functionality.

The basic components available can be looked up in this category.

Nested definitions are possible, i.e. it is possible to define child objects in the form of child nodes in the XML structure. E.g.:


will create a box within a box.

ASUL objects will behave like any other Sprite, with the difference that setting their width and height will only change the size of the background of the object (backgrounds may be fully transparent, though). In turn, child nodes will be asked to layout themselves, or be positioned by the container (see Layouting). Also, the returned width and height are the actual visible width and height of the element (read on).

Every ASUL object has two layers: one for the background, and one for the elements. The element layer is furthermore masked, so that children can never exceed the bounds of the parent (one can change this setting, though, but the default setting is children to be cut off).



All components must be set up using attributes in their XML definition. The available attributes vary by type, but there are some common attributes which are defined in the top level object. These include the behavior common to all objects, such as position, size and layouting, but also background and filters. For example, a Box might be set up like this:

<box width="100" height="100" background="color(0xFF0000)"/>


Some components require child nodes to define parts of them for full or any functionality at all. These child nodes must be named as defined in the object's documentation. Such names follow the naming convention that they are encapsulated in $ characters, e.g. $foobar$.

Those child nodes will normally have to be of a specific kind, which will be described in the documentation of the object. For example, the ProgressBar object requires a $bar$ child of any type, and / or a $text$ child of type Text. A XML description may look like this:

<progressbar width="200" height="30" background="color(0x000000)" value="0.5">
    <box name="$bar$" anchors="5,5,pw-5,ph-5" background="color(0xFFFFFF)"/>


This is a demonstration SWF which can be used to experiment with ASUL by creating elements for which the definition is entered into the textbox.
The defined ASUL elements are shown in the window, the "sandbox". It is set to width= 100% and height = 600; and best works with browser zoom set to 100% in Chrome or Safari.
Use the gray bar on top to drag the control window.
The create button tries to instantiate the ASUL component defined in the text field and add it to the stage.
Use the clear button to remove all created elements from the stage.

The text area is not meant as an editor. Use an external text editor (e.g. Notepad++) to write your ASUL definition, then copy-paste it into the text area to see how it looks.
As a first example you can copy-pasting the definition of the box and the progressbar above (you will have to move the control window to see the instances).

More detailed example: These ASUL definitions draw two boxes, a blue one on the left, and directly aside that blue box a green one, but at a different height:

<box width="200" height="500" anchors="0,100!400" background="color(0x0000ff)"/>
<box width="200" height="600"  anchors="200,100?400" background="color(0xff000)"/>

The blue box is positioned at x=0 and y=400. The bigger value of 100,400 is used because of the MAX operator "!".
The green one is positioned at x=200 (which is the width of the first box) and y=100, because 100 is the smaller value and the MIN operator "?" uses the smaller one of 100,400

Copy these 2 definitions into the sandbox and hit create: the 2 boxes will appear.

You now can play with the settings: change the sizes, posositions, formulas.
Best is to clear the sandbox before updating it with create.

Helpful to know are these definitions:

pw, ph       :   width and height of the parent, i.e. the dimension of the container the element is placed in; in this case the sandbox.
w, h         :   width and height of the element itslef; in this case the boxes
pagew, pageh :   width and height of the a single page
!            :   MAX operator
?            :   MIN operator

Another example is:

<box width="100" height="300" anchors="300,ph-h" background="color(0xff0000)"/>

This positions a red box within the green box, starting in the middle of the container:

  y = container height(600px) - box height (300px) = 300px; which is 600 / 2

To prove that you can draw another little yellow box on the red box, and position it to the middle of the container; right aligned with the red box:

<box width="50" height="10" anchors="350,ph/2" background="color(0xffff00)"/>

The y position is calculated using the hight of both the container and the element, and positions the box always at the bottom of the container.

If you change the zoom factor of the browser, you'll notice that the red box always stays at the bottom, and the yellow box always is in the middle. Whereas the y position of the green and blue boxes vary.

{{#if: |


Results in the following:
}}<swf width="100%" height="600">{{#if: | |xml={{{xml}}} }}{{#if: true | |gui=true }} </swf>


The ASUL project is licensed under the MIT License, which means anyone can use it. It does not depend one any of the MegaZine3 classes, so it is completely independent of the main project. You will need a few classes from the other packages, though. Get the sources from the repository.


This category has only the following subcategory.