XML Reference
This tutorial documents the XML representation of the user interface definition, or GUIKitXML for short.
Element | Description |
| <widget src=fileclass:className><widget class=className> | |
| create a new widget | |
| <widget ref=id> | look up an existing widget |
| <group> | add custom layout features to how widgets will display |
| <args> | specify constructor arguments |
| <string> | create a new string object or look one up |
| <property name=name> | set or get a widget property |
| <bindevent> | bind an event from one widget to a listener or to a script |
| <invokemethod name=method> | call a widget method |
| <script> | define a script to be used elsewhere, either on load or during an event |
| <expose ref=id> | add a widget from an inner XML file to the registry of accessible widgets in the parent XML file |
DTD
This is a DTD representing the current GUIKit XML definitions.
<?xml encoding="UTF-8"?>
<!--
GUIKit` XML Markup Language, GUIKitXML DTD
Copyright 2004, Wolfram Research, Inc.
-->
<!ENTITY % common-elems "widget|group|string|integer|double|null|true|false|invokemethod|property|script|space|fill|align">
<!ENTITY % invokemethod-valued-elems "%common-elems;">
<!ENTITY % bindevent-valued-elems "widget|script|invokemethod|property|bindevent">
<!ENTITY % stmt-elems "%common-elems;|bindevent">
<!-- layout can exist as either a simple attribute or as a subelement
on widget and group. The subelement trumps the attribute if
both exist
-->
<!ELEMENT widget (layout?,args?,expose*,(%stmt-elems;)*)>
<!ATTLIST widget
src NMTOKEN #IMPLIED
ref CDATA #IMPLIED
class NMTOKEN #IMPLIED
id CDATA #IMPLIED
layout CDATA #IMPLIED>
<!ELEMENT group (layout?,(%stmt-elems;)*)>
<!ATTLIST group
layout CDATA #IMPLIED
id CDATA #IMPLIED
root CDATA #IMPLIED>
<!-- value should be in integer pixel units -->
<!ELEMENT space EMPTY >
<!ATTLIST space
value CDATA #REQUIRED>
<!ELEMENT fill EMPTY >
<!-- ref should be a widget reference string
from and to can be either "Before" or "After"
-->
<!ELEMENT align EMPTY >
<!ATTLIST align
ref CDATA #IMPLIED
from CDATA #IMPLIED
to CDATA #IMPLIED>
<!ELEMENT layout (grouping?,alignment?,stretching?,spacing?,border?)>
<!-- grouping either specifies a simple attribute type of
None, Automatic, Column, Row, Grid or a
subelement that resolves to a Java layout manager widget
equivalent to just using a "layout" property on the container
-->
<!ELEMENT grouping (%common-elems;) >
<!ATTLIST grouping
type CDATA #IMPLIED>
<!-- alignment type can be Automatic, Left, Center, Right, Top or Bottom
and can specify different values for both axes such as
"Automatic, Top" or "Left,Center"
-->
<!ELEMENT alignment EMPTY >
<!ATTLIST alignment
type CDATA #REQUIRED>
<!-- stretching type can be Automatic, None, WidgetAlignments, True, Maximize
and can specify different values for both axes such as
"None,True"
-->
<!ELEMENT stretching EMPTY >
<!ATTLIST stretching
type CDATA #REQUIRED>
<!-- value should be in integer pixel units -->
<!ELEMENT spacing EMPTY >
<!ATTLIST spacing
value CDATA #REQUIRED>
<!ELEMENT border (((border+)|%common-elems;)?) >
<!ATTLIST border
type CDATA #IMPLIED
title CDATA #IMPLIED
left CDATA #IMPLIED
right CDATA #IMPLIED
top CDATA #IMPLIED
bottom CDATA #IMPLIED>
<!-- Versions:
Create and configure a widget:
<widget src="filename | URL" [id="name-to-register-as"]> ... </widget>
<widget src="class:a.b.C" [id="name-to-register-as"]> ... </widget>
<widget class="a.b.C" [id="name-to-register-as"]> ... </widget>
src="class:className" is identical to using class="className".
The arguments define the constructor args.
The arguments to the inner GUIKitXML file can be accessed via the names:
"#1", "#2", ..., "#n".
Configure an existing widget:
<widget ref="name-to-look-up" [class="a.b.C"] > ... </widget>
The class attrib is optional because the API does not need it,
but a possible compiler may.
If id attribute is present then register the widget.
-->
<!-- constructor arguments -->
<!ELEMENT args (%common-elems;)*>
<!ATTLIST args
ref CDATA #IMPLIED>
<!-- Versions:
<args ref=""/> provides a way of referencing a
vector or collection of widgets to use as arguments.
Most importantly, used with <args ref="##"/>
to specify that the array of arguments passed to the script
should be used as arguments to the constructor of the wrapping widget.
A useful pattern for building reusable GUIKit widgets in
self-contained files.
-->
<!ELEMENT property (%common-elems;)?>
<!ATTLIST property
target CDATA #IMPLIED
name NMTOKEN #REQUIRED
index NMTOKEN #IMPLIED
value CDATA #IMPLIED
id CDATA #IMPLIED
invokeThread NMTOKEN #IMPLIED
invokeWait NMTOKEN #IMPLIED>
<!-- Versions:
Get: <property [target="t"] name="foo" [index="num"] [id="name"]/>
Set: <property [target="t"] name="foo" [index="num"] [id="name"]>
some-element
</property>
or
<property [target="t"] name="foo" [index="num"] value="stuff"
[id="name"]/>
where stuff is either one of the valid elements.
If index is given, then property is an indexed property.
XML and the Wolfram Language is 1-based, Java is 0-based
Set version of property returns nothing (i.e., void) and hence only
makes sense as a direct child of <widget>. If id attribute is present
then register the property value. -->
<!ELEMENT bindevent (%bindevent-valued-elems;)+>
<!ATTLIST bindevent
target CDATA #IMPLIED
name NMTOKEN #REQUIRED
filter NMTOKEN #IMPLIED
id CDATA #IMPLIED
invokeThread NMTOKEN #IMPLIED
invokeWait NMTOKEN #IMPLIED>
<!-- Versions:
<bindevent [target="t"] name="e" [filter="f"]>
<widget ... />
</bindevent>
This is the conventional event binding. The target t is the
target of the binding, not the target of the actual firing of
the event. Bind the child widget as a listener for e events from
target t. The child widget must implement the appropriate listener
interface. The filter f is optional and used in rare cases only if (e = propertyChange or
vetoableChange) as that allows property
and vetoable change listeners to register for specific properties
rather than any property. The filter will name a property in
these cases.
name="mouse" filter="mouseEntered" can instead just be specified by name="mouseEntered" now
Missing target attribute makes the context widget be
the target.
<bindevent [target="t"] name="e" [filter="f"]>
<script [language="mathematica"]>
...
</script>
</bindevent>
When event e occurs in source, process the script. If
filter is specified, then only events delivered which match
that filter cause the script to be processed. In general, the
filter attribute is used to name a method in a listener type
that has multiple methods (e.g., WindowEvent in AWT). For event
name = propertyChange or vetoableChange, the filter is the name
of the property for which the binding should be done. JDK1.2
has direct support for these types of property and vetoable
change listeners, but others will require the
propchange/vetochange event processor to do the filtering work.
Missing target attribute makes the context widget be the target.
See the <script> element for a description of how to access the
arguments to the script (such as an event widget, or any
arbitrary list of event arguments).-->
<!ELEMENT script (#PCDATA|%stmt-elems;)*>
<!ATTLIST script
language NMTOKEN #IMPLIED
src NMTOKEN #IMPLIED>
<!--
The script contained in the element is processed by a scripting
engine capable of processing the language described by the language
attribute. The value of the language attribute can be anything
supported by the widget scripting framework. The src attribute can
give a URL or relative file from which the script is to be loaded.
The arguments to the <script> element can be accessed via the names:
"#1", "#2", "#3", ..., "#n"
Example:
<widget class="java.awt.Button">
<bindevent name="action">
<script>
<invokemethod target="demomgr" name="load">
<property target="#1" name="actionCommand"/>
</invokemethod>
**************************************************
above will call the "load" method of the widget named
"demomgr" with the "actionCommand" property of the
actionevent widget generated by the event source.
Note that the widget "#0" in this case will be
java.lang.String("actionPerformed"), which is the
name of the method via which the event was delivered.
**************************************************
</script>
</bindevent>
</widget>
-->
<!-- call a method -->
<!ELEMENT invokemethod (%invokemethod-valued-elems;)*>
<!ATTLIST invokemethod
target CDATA #IMPLIED
name NMTOKEN #REQUIRED
id CDATA #IMPLIED
invokeThread NMTOKEN #IMPLIED
invokeWait NMTOKEN #IMPLIED>
<!-- The arguments to the method are the children widgets and the signature
of the method to call is defined by the children's types.
If id attribute is present then register the return value. -->
<!ELEMENT string (#PCDATA)>
<!ATTLIST string
value CDATA #IMPLIED
id CDATA #IMPLIED>
<!-- treat the pcdata as a string. empty <string/> is 'new String("")'.
If id attribute is present then register the string. -->
<!ELEMENT integer (#PCDATA)>
<!ATTLIST integer
value CDATA #IMPLIED
id CDATA #IMPLIED>
<!-- treat the pcdata as a integer.
If id attribute is present then register the integer. -->
<!ELEMENT double (#PCDATA)>
<!ATTLIST double
value CDATA #IMPLIED
id CDATA #IMPLIED>
<!-- treat the pcdata as a double.
If id attribute is present then register the double. -->
<!ELEMENT null (#PCDATA)>
<!ATTLIST null
class CDATA #IMPLIED
id CDATA #IMPLIED>
<!-- null. If id attribute is present then register the Null. -->
<!ELEMENT true EMPTY>
<!-- Boolean.TRUE -->
<!ELEMENT false EMPTY>
<!-- Boolean.FALSE -->
<!ELEMENT expose EMPTY >
<!ATTLIST expose
ref CDATA #REQUIRED
as CDATA #IMPLIED>
<!-- expose can be child elements of <widget class="*.xml"> to expose
widgets registered in the child xml document to the parent documents
widget registry, optionally using a different ref than the child by
specifying an attribute. -->
<args>
Use the <args> element to specify that the containing widgets should be used as arguments to the parent <widget> new instance object constructor.
This is a very common use of the <args> element to specify the set of widgets to use based on a widget name reference.
Here you specify the title of a frame using an argument to the object's constructor.
<bindevent>
Use the <bindevent> element to associate script code or other method calls to occur when an event is triggered from the targeted widget. Here are two forms of associating code with an event action.
When event e occurs, process the script. If the filter is specified, then only events delivered that match that filter cause the script to be processed. In general, the filter attribute is used to name a method in a listener type that has multiple methods (e.g., WindowEvent in AWT). For event name="propertyChange" or name="vetoableChange", the filter is the name of the property for which the binding should be done. With a missing target attribute, the wrapping context <widget> is the target. See the <script> element for a description of how to access the arguments to the script; this includes special names in the widget registry, such as "##" and "#1", "#2", and so forth.
In the previous case, the <widget> must resolve to a widget that implements the appropriate listener interface.
In the following example, the script makes use of the specially registered event objects that are defined every time a script within a <bindevent> element is triggered, such as "#", which resolves to a MouseEvent instance.
<widget src="MathCanvas" id="canvas">
<bindevent name="mouseDragged">
<script>
mouseDraggedFunc[
WidgetReference["#"] @ getX[],
WidgetReference["#"] @ getY[] ];
</script>
</bindevent>
</widget>
Here you bind a simple script to the common Button action event.
<widget src="Button">
<bindevent name="action">
<script>incrementFieldValue[];</script>
</bindevent>
</widget>
<invokemethod>
Use the <invokemethod> element to make a method call on a widget. It can be a simple no-argument call where the method is specified only with a name attribute, or it could include child elements representing the arguments to the method.
Here is a simple no-argument method call.
Here is an example that requires child elements to specify the arguments to the method call. If no target attribute exists, then the target of the method call is the wrapping widget instance of the <invokemethod>.
<invokemethod target="frame" name="setSize">
<integer value="400"/>
<integer value="400"/>
</invokemethod>
<expose>
Use the <expose> element when you want to allow external access to widgets from within included interface definitions. Normally only the root widget is automatically available when wrapping other definitions. <expose> allows you to not only percolate up access to other widgets, but also redefine the widget reference name by which they can be found in the wrapping interface. Renaming references is especially handy when exposing them if there is a need to expose multiple instances of the same interface, but provide access to each instance with a different name.
In this example definition, normally only the top-level component referenced by "frame" would be available to users of this definition. Knowing that the external definition "progressbar2base" also contains another widget referenced by the ID "bar", you can use an <expose> element in this definition to also allow users access to the widget in "progressbar2base" found using the name "bar".
<?xml version="1.0"?>
<widget src="progressbar2base" id="frame">
<args>
<string value="Wrapped Progress" />
<string value="Wrapped complete:" />
<integer value="20" />
</args>
<expose ref="bar"/>
</widget>
You could also choose to expose the "bar" widget with a different name using the optional as= attribute, such as allowing access to the widget with the name "progressBar".
<?xml version="1.0"?>
<widget src="progressbar2base" id="frame">
<args>
<string value="Wrapped Progress" />
<string value="Wrapped complete:" />
<integer value="20" />
</args>
<expose ref="bar" as="progressBar"/>
</widget>
<group>
The <group> element is used to nest widget groups and customize how the interface will be displayed. More examples will be forthcoming.
<group>
<widget src="Button">
<property name="label" value="++"/>
</widget>
<widget src="Button">
<property name="label" value="--"/>
</widget>
</group>
<widget>
The <widget> element is used both for defining a new instance to be created based on the contents of the <widget> element or alternatively to specify a reference to an existing widget instance by using the ref="name" attribute.
Here are some patterns used when creating new instances.
<widget src="filename | URL" [id="name-to-register-as"]>
...
</widget>
<widget src="class:a.b.C" [id="name-to-register-as"]>
...
</widget>
<widget class="a.b.C" [id="name-to-register-as"]>
...
</widget>
The two forms src="class:a.b.C" and class="a.b.C" are simply alternate forms of the same functionality.
Here are patterns used for configuring or looking up existing widget instances.
This definition creates a new widget instance using the src attribute to find the resource that defines what eventual widget class is created.
Here you refer to another widget in this definition named "frame" as an argument when constructing a new instance of the FileDialog.
<widget src="FileDialog">
<args>
<widget ref="frame"/>
<string value="Save As"/>
<property target="class:java.awt.FileDialog" name="SAVE"/>
</args>
</widget>
<property>
Use the <property> element to get a widget property value or to set a property value. You use the <property> element along with child elements or the value="" attribute to set a property value.
Here is the pattern for getting a property value.
Either of these two patterns can be used to set a property value.
<property [target="t"] name="foo" [index="num"] [id="name"]>
some-element
</property>
<property [target="t"] name="foo" [index="num"] value="stuff" [id="name"]/>
If the target attribute is absent, the target of the property request is the wrapping widget instance.
Note that indices in the Wolfram Language and XML widget definitions are 1-based, while Java and direct calls to Java objects using J/Link follow the 0-based Java convention.
Here you set the text property of a text field using the value attribute.
In this case, the value for the "layout" property is created from the child elements of the <property> element.
<script>
Use the <script> element to associate scripting code either as general code to be executed when the widget definition is read in, or, if bound to a specific event, to be executed each time the event occurs. By default, the language of a <script> element is Wolfram Language code unless an alternate language is specified. You can use language="xml" to specify that GUIKitXML child elements of the <script> element define the code to execute.
Since scripting language code is usually not XML compliant syntax, consider wrapping the text content of the <script> element with a CDATA section.
In this case you define a top-level <script> that sets up a function definition when the widget is instantiated.
<widget src="Frame">
<property name="layout">
<widget src="GridLayout"/>
</property>
<script><![CDATA[
incrementFieldValue[] :=
SetPropertyValue[{"textField", "text"},
ToString[ ToExpression[PropertyValue[{"textField", "text"}]] + 1, InputForm] ]
]]></script>
</widget>
Here you bind some script code to execute each time the button's action is triggered.
<widget src="Button">
<bindevent name="action">
<script>incrementFieldValue[];</script>
</bindevent>
</widget>
<string>
The <string> element is available to provide convenient ways of defining string instances, both as child PCDATA or with a value attribute. The use of <string/> is equivalent to "".
Here are two alternate forms of the same string instance.
Making a <string> element available eliminates the use of the <widget> element just to define a string as well as issues that arise by trying to have the <args> element take both PCDATA and other elements, along with the sensitivity issues of whitespace.