GUI Customizing

This page explains how to customize a GUI generated by Apollon. Default generated Swing code consists in text fields (javax.swing.JTextField) used to fill the #PCDATA and attributes values; Customizing the generated code with other graphical representation helps to fit the finally produced XML editor.

The demo sample

A description of the Apollon model and Java constraints is available below. Let us first consider an example based on the demo.dtd

The build/xml/demo.Apollon file is the Apollon model in charge of customizing the GUI for our demonstration :


<apollon>
  <mapattribute name="contentref" brickref="contents list"/>
  <brick id="contents list" javaclass="org.objectweb.apollon.gui.bricks.ChoiceList">
    <buildparam value="org.objectweb.apollon.framework.IndexTable.getIdList(&quot;content&quot;)"/>
  </brick>
</apollon>

This model establishes a mapping for any attribute named "contentref" in the demo.dtd definition. The graphical representation to be used is named "contents list", which is a brick defined in the model.

The contents list brick is based on a Java class, which package is provided by Apollon itself, since this is a demonstration. The model also defines a constructor parameter (<buildparam>) to be used for the brick instantiation. The value for this parameter is here the result of a static method. Note the translation of the " character in " : this is mandatory since we are using the XML language.

Any content should be used in this constructor parameter. This is of the developer's tasks to ensure that the parameter provided will be understood by its own graphical widget.

The visual result of this definition is a Swing combo box (implemented in the ChoiceList class), which content is to be taken from the XML IDs found in the whole editor at runtime.

Now let's detail the Apollon model's usage.

The Apollon Model

The Code Generation achieved with the apollon_run.xml ANT file generates all frameworks from the given DTD. This behaviour also involves a default Apollon model, located in the build/xml/ directory and whose filename is attended to be <DTD root name>.Apollon.
In case such a file can not be found; the GUI generator falls back to text fields.

To customize your generated GUI, you have to create the attented model in the build/xml/ directory. The directory already contains sample model files which are provided to help the understanding of the GUI customization.

The bricks definitions

An Apollon model is an XML file based on the apollon.dtd file. It defines bricks, which can be affected to mapelement or mapattribute elements to tune their graphical representation. A <brick> element has following definition :


<!ELEMENT brick
    ( buildparam*
    , brick*
    ) >
<!ATTLIST brick
    id              ID              #REQUIRED
    javaclass       CDATA           "org.objectweb.apollon.gui.bricks.TextField"
    feedmethod      CDATA           "set"
    retrievemethod  CDATA           "get"
    display         (true | false)  "true"
    inparent        (true | false)  "false"
    displaylabel    (true | false)  "true"
    childrenview    CDATA           "org.objectweb.apollon.gui.ApollonPanel"
>

The default values map the standard behaviour of the generator. When providing your own javaclass, you have to specify the public methods that would access the represented value with the feedmethod and retrievemethod attributes.
The display, inparent and displaylabel attributes tune the appareance of the brick itself. A false display will generate a visually empty brick. A true inparent will make the editor handle a sub-element as an attribute.

The mapelements and mapattributes definitions

A defined <brick> can be identified with its id attribute. This id can then be referenced during the mapping of elements and attributes, to specify the brick that will represent them. <mapelement> and <mapattribute> have following definitions :


<!ELEMENT mapelement
    ( mapattribute*
    | info?
    ) >
<!ATTLIST mapelement
    name            CDATA           #REQUIRED
    brickref        IDREF           #IMPLIED
>

<!ELEMENT mapattribute EMPTY >
<!ATTLIST mapattribute
    name            CDATA           #REQUIRED
    brickref        IDREF           #REQUIRED
>

An attribute can be customized globally if the relevant <mapattribute> is not encapsulated in any <mapelement> element.
the brickref attributes in <mapelement> and <mapattribute> are references to existing <brick> IDs.

Providing parameters to your bricks

For very specialized graphical bricks, you may need to provide them parameters. The best example is to authorize a selection amongst pre-defined values, which are not in the original DTD used for code generation.

The Apollon model enables such customization with a <buildparam> element to be defined under a <brick> element. Its definition is quite simple :


<!ELEMENT buildparam EMPTY >
<!ATTLIST buildparam
    value CDATA ""
>

The value attribute for this <buildparam> should contain the Java parameter to be provided during the brick construction.

The org.objectweb.apollon.gui.bricks package

This packages holds basic GUI elements shipped with the Apollon software. They can be used in models definitions, but considered as samples to develop your own custom graphical widgets as well.

AbstractBrick
BrowseLine
ChoiceList
TextArea
TextButton
TextField
TextLabel

Any new brick HAS TO inherit from the org.objectweb.apollon.gui.bricks.AbstractBrick class. It provides basic behaviour and ensures that the Apollon GUI frame could hold the given custom widget (this AbstractBrick extends javax.swing.JPanel).