ASUL Document

From MegaZine3
Jump to navigation Jump to search

ASUL documents (.asul) are XML files containing GUI definitions for the engine and its plugins. An ASUL document can contain any number of elements, and any number of style definitions.

An element must have an id to be usable in the engine / a plugin. The id is given in the attribute named id.


<box id="my_box"/>

This box can then be used inside the engine or within plugins.


Styles are template definitions of attribute values. The syntax is similar to CSS. Styles can be applied using the style attribute (analog to the class attribute in HTML).

button, box {
    x: 10;
    y: 20;
box.someclass progressbar {
    background: color(0xff00ff);

To use it inside an .asul file, pack the style inside a CDATA tag inside style tag:

<?xml version="1.0" encoding="utf-8"?>
    <!-- Copied from the megazine.asul -->
    button.common, togglebutton.common, togglebutton.common button {
        minwidth: 24;
        minheight: 24;
        maxwidth: 24;
        maxheight: 24;
        filter: dropshadow(2,45,0x000000,1,3,3,0.5,2);


  • Path: button, box, box.someclass progressbar
  • Class: {x:10;y:20}, {background:color(0xff00ff);}
  • Definition: x:10, y:20, background:color(0xff00ff)
  • Attribute: x, y, background
  • Value: 10, 20, color(0xff00ff)

Note: if there is some better suited naming, feel free to correct this. This is just what felt most natural to me.

All definitions made in a class will be used to set the attributes of elements the class' path to. This means that you can use all the attributes you could set directly on an object.

Weight / Overriding

The weight of classes differs, here is the basic order. The further down, the stronger the definition. Meaning that definitions will override all definitions listed above them, but be overridden by definitions below them. If two equally weighted classes exist, the last defined one will be stored.

  1. element type, e.g. button
  2. class, e.g. .myclass
  3. element bound class, e.g. button.myclass
  4. paths, e.g. box button (note that here, again, classes are stronger. I.e. this definition is weaker than box.otherclass button).
    The longer the path, the stronger it is. I.e. togglebutton box button is stronger than box button.
    A path must be fully matched to be applied.

There can be multiple style blocks in a document, they will be parsed one after the other, but effectively handled like one big block. If a definition is encountered twice, new attribute values are additionally stored, duplicate definitions will result in the later definition to be used (the one further down).

MegaZine3 specific

In the MegaZine3 engine, all style declarations from the megazine.asul file are made available in each plugin's ASUL definitions, where they can be used or overridden as needed. This allows a more centralized definition of commonly used styles, e.g. for buttons or other components.


{{#switch:left | left =

{{#switch:{{#if: | {{{smallimage}}} | }} | none =

| #default =

}} {{#if:{{#if: | {{{smallimageright}}} | }} | {{#ifeq:{{#if: | {{{smallimageright}}} | }}|none | | }} }}

| #default =

{{#switch: | none =

| #default =


{{#if: | {{#ifeq:|none

| }} }}



Elements are defined in the form of XML nodes, where the root node must have an id to be referenced to in the engine. All elements can be put into any other element. It is left up to the designer to decide what is most efficient and makes the most sense. Some elements define requirements or use for child nodes, sometimes of a special type. Those child nodes will have to be named as defined by the element. As a common convention, those names start and end with a $ character. On the example of the ProgressBar:

<progressbar id="loading_bar">
    <box name="$bar$"/>
    <text name="$text$"/>

Two child nodes are used, $bar$ for the loading bar graphic, and $text$ to textually display the progress. Either of the two could be omitted, even both of them, though. Furthermore, they could be nested deeper inside other childnodes, e.g.

<progressbar id="loading_bar">
    <box name="$bar$"/>
        <text name="$text$"/>

The engine could then access the progressbar using its id (loading_bar). Note, that usually a plugin defines a set of ids it requires / uses. Setting ids to something never used in the engine is obviously not very useful. The best reference is probably the set of ASUL documents that are released with the default plugins.

Those special child nodes are searched breadth-first.

The actual attributes of the elements, their design and layout, is in most cases irrelevant to the functioning of the engine, allowing the designer a lot of freedom to customize the GUI.

ASUL-related articles
Components Box · Button · ProgressBar · ScrollBar · ScrollPane · Text · ToggleButton · Window
Layouts Horizontal Flow Layout · Vertical Flow Layout
ASUL Articles ASUL Document · Editing the GUI · Layouting · ASUL scripting