You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pivot.apache.org by gb...@apache.org on 2010/10/29 19:01:46 UTC
svn commit: r1028844 - /pivot/trunk/tutorials/www/bxml-primer.xml
Author: gbrown
Date: Fri Oct 29 17:01:46 2010
New Revision: 1028844
URL: http://svn.apache.org/viewvc?rev=1028844&view=rev
Log:
Draft updates to BXML Primer.
Modified:
pivot/trunk/tutorials/www/bxml-primer.xml
Modified: pivot/trunk/tutorials/www/bxml-primer.xml
URL: http://svn.apache.org/viewvc/pivot/trunk/tutorials/www/bxml-primer.xml?rev=1028844&r1=1028843&r2=1028844&view=diff
==============================================================================
--- pivot/trunk/tutorials/www/bxml-primer.xml (original)
+++ pivot/trunk/tutorials/www/bxml-primer.xml Fri Oct 29 17:01:46 2010
@@ -18,902 +18,933 @@ limitations under the License.
<document id="wtkx-primer">
<properties>
- <title>WTKX Primer</title>
+ <title>BXML Primer</title>
</properties>
<body>
<p>
- WTKX is an XML-based markup language used for building Apache Pivot applications. Though
- it is most commonly used for defining the structure of an application's user interface,
- it can be used to declaratively construct any type of Java object hierarchy.
+ BXML is an XML-based markup language for simplifying the construction of Java object
+ hierarchies. While it is most often used to define the user interface of an Apache Pivot
+ application, it is not limited to user interface construction, and can actually be used to
+ create hierarchies of any object type.
</p>
<p>
- This section introduces WTKX and explains how it can be used to create and configure a
- collection of Java objects. It assumes some familiarity with Pivot and Java programming
- in general. For an introduction to Pivot, please see the Pivot
- <a href="platform-overview.html">Platform Overview</a>.
+ This document introduces the BXML language and explains how it can be used to create and
+ configure a collection of Java objects. It also explains how to create BXML-compatible
+ classes for use in your own applications.
</p>
- <h2>Elements</h2>
- <p>
- In WTKX, an XML element may represent one of the following:
- </p>
-
- <ul>
- <li><p>A class instance</p></li>
- <li><p>A property of a class instance</p></li>
- <li><p>A processing directive to the WTKX serializer</p></li>
- </ul>
+ <h2>BXMLSerializer</h2>
<p>
- If an element's tag name begins with an uppercase letter, it is considered a class
- instance. Otherwise, it is treated as an instance property, unless the tag name begins
- with the reserved "wtkx" namespace prefix, in which case it is considered a
- serialization directive. These are discussed in more detail in later sections.
+ The <tt>org.apache.pivot.beans.BXMLSerializer</tt> class is used to load a structure
+ defined in a BXML file. This class implements the
+ <tt>org.apache.pivot.serialization.Serializer</tt> interface, which defines the
+ <tt>readObject()</tt> method for reading an object value from an input stream:
</p>
- <h3>Class Instance Elements</h3>
+ <source type="java">
+ <![CDATA[
+ public interface Serializer<T> {
+ public T readObject(InputStream inputStream)
+ throws IOException, SerializationException;
+ public void writeObject(T object, OutputStream outputStream)
+ throws IOException, SerializationException;
+ public String getMIMEType(T object);
+ }
+ ]]>
+ </source>
+
<p>
- When the WTKX serializer (an instance of <tt>org.apache.pivot.wtkx.WTKXSerializer</tt>,
- discussed below) encounters an element whose tag name begins with an uppercase letter,
- it considers the tag to be the name of a Java class and creates an instance of that
- class. The element's namespace is assumed to contain the name of the package that the
- class belongs to.
+ <tt>BXMLSerializer</tt> does not implement <tt>writeObject()</tt>, but does provide some
+ additional conveniece methods for reading BXML as well as for localizing the deserialized
+ structure using resource bundles.
</p>
<p>
- For example, the following WTKX would produce an instance of the
- <tt>org.apache.pivot.wtk.Label</tt> class populated with the text "Hello, World!" (like
- property elements, attributes can also be used to set property values, and are
- discussed in the next section):
+ For example, the following code snippet loads a Window object declared in a file named
+ "my_window.bxml":
</p>
- <source type="xml">
- <![CDATA[
- <Label text="Hello, World!"
- xmlns="org.apache.pivot.wtk" />
- ]]>
+ <source type="java">
+ <![CDATA[
+ BXMLSerializer bxmlSerializer = new BXMLSerializer();
+ Window window = (Window)bxmlSerializer.readObject(getClass().getResource("my_window.bxml"));
+ ]]>
</source>
+ <h2>Namespaces</h2>
+
<p>
- Note that the default namespace is defined as <tt>org.apache.pivot.wtk</tt>. This is
- fairly common practice in Pivot development, since WTKX is often used to construct
- user interfaces using components defined in this package.
+ In BXML, an XML namespace represents a Java package. Declaring a namespace associates the
+ namespace prefix with a Java package, similar to how the import keyword is used in Java.
</p>
<p>
- More complex examples may also use classes defined in other packages and will require
- multiple namespaces. Namespace prefixes can be used for this purpose. For example, the
- following WTKX assigns the <tt>org.apache.pivot.wtk.charts</tt> package to the
- <tt>charts</tt> namespace prefix, and sets an instance of
- <tt>org.apache.pivot.wtk.charts.BarChartView</tt> as the content of a <tt>Window</tt>:
+ For example, the following simple BXML associates the "com.foo" package with the "foo"
+ namespace prefix:
</p>
<source type="xml">
- <![CDATA[
- <Window xmlns="org.apache.pivot.wtk"
- xmlns:charts="org.apache.pivot.wtk.charts">
- <content>
- <charts:BarChartView/>
- </content>
- </Window>
- ]]>
+ <![CDATA[
+ <foo:Bar xmlns:foo="com.foo"/>
+ ]]>
</source>
- <h4>Dictionary vs. BeanAdapter</h4>
-
<p>
- In general, uppercase elements in a WTKX file will represent instances of Java bean
- classes. Internally, the WTKX serializer uses an instance of
- <tt>org.apache.pivot.beans.BeanAdapter</tt> to wrap the instantiated class and
- invoke its setter methods. However, if the class name represents an object that already
- implements the <tt>org.apache.pivot.collections.Dictionary</tt> interface (such as
- <tt>org.apache.pivot.collections.HashMap</tt>), it is not wrapped, and its dictionary
- methods are accessed directly. For example, the following WTKX creates an instance of
- <tt>org.apache.pivot.collections.HashMap</tt> and sets its "foo" and "bar" values to
- "123" and "456", respectively:
+ If this file were deserialized using <tt>BXMLSerializer</tt>, an instance of
+ <tt>com.foo.Bar</tt> would be returned by the call to <tt>readObject()</tt>. The following
+ BXML, which maps the <tt>com.foo</tt> package to the default namespace, would produce the
+ same results with slightly less verbose markup:
</p>
<source type="xml">
- <![CDATA[
- <HashMap foo="123" bar="456"
- xmlns="org.apache.pivot.collections"/>
- ]]>
+ <![CDATA[
+ <Bar xmlns="com.foo"/>;
+ ]]>
</source>
- <h3>Instance Property Elements</h3>
<p>
- Elements whose tag names begin with a lowercase letter represent instance properties. A
- property element may represent one of the following:
+ More complex examples may use classes defined in multiple packages; multiple namespace
+ prefixes can be used for this purpose.
</p>
- <ul>
- <li><p>A standard Java bean property setter</p></li>
- <li><p>A read-only sequence</p></li>
- <li><p>A read-only dictionary</p></li>
- <li><p>An event listener list</p></li>
- </ul>
+ <h3>The "bxml" Namespace</h3>
<p>
- The WTKX serializer uses a bean dictionary to obtain information about the type of the
- property so that it can process the element's contents correctly.
+ The reserved "bxml" namespace defines the following elements and attributes, which are
+ used for internal processing:
</p>
- <h4>Java Bean Property Setters</h4>
+ <ul>
+ <li>
<p>
- If the element represents a Java bean property setter, the contents of the element
- (which must be either a text node or a class instance element) are passed as the value
- to the setter for the property. For example, the following WTKX creates an instance of
- the <tt>Label</tt> class and sets the value of the label's "text" property to "Hello,
- World!":
+ The <tt>bxml:id</tt> attribute is used to assign a variable name to an element declared in
+ a BXML file. For example, the following markup would associate an instance of the
+ <tt>Foo</tt> class with the ID "myFoo". This variable is added to the document's variable
+ namespace (which is different from the XML namespace used to import Java packages), and
+ can then be referenced elsewhere in the file (or by the code that deserializes the file,
+ via the <tt>BXMLSerializer#getNamespace()</tt> method):
</p>
<source type="xml">
- <![CDATA[
- <Label xmlns="org.apache.pivot.wtk">
- <text>Hello, World!</text>
- </Label>
- ]]>
+ <![CDATA[
+ <Foo bxml:id="myFoo"/>
+ ]]>
</source>
+ </li>
+ <li>
<p>
- It produces the same result as the earlier example which used an attribute to set the
- "text" property:
- </p>
+ The <tt><bxml:include></tt> element is used to include external resources, including
+ nested BXML documents. For example, the following markup would embed the contents of the
+ "my_include.bxml" file in the current document:</p>
<source type="xml">
- <![CDATA[
- <Label text="Hello, World!"
- xmlns="org.apache.pivot.wtk"/>
- ]]>
+ <![CDATA[
+ <bxml:include src="my_include.bxml"/>;
+ ]]>
</source>
<p>
- This example creates an instance of <tt>ListView</tt> and sets the value of its
- "listData" property to an instance of <tt>org.apache.pivot.collections.ArrayList</tt>
- that has been populated with several instances of
- <tt>org.apache.pivot.wtk.content.ListItem</tt> (a data class recognized by the default
- list item renderer):
+ Includes are often used for partitioning content into manageable pieces (for example, when
+ working on large applications or with multiple developers, or when defining reusable
+ content templates). Each include is assigned its own variable namespace to avoid naming
+ collisions with ancestor documents.
</p>
+ </li>
- <source type="xml">
- <![CDATA[
- <ListView xmlns="org.apache.pivot.wtk"
- xmlns:collections="org.apache.pivot.collections"
- xmlns:content="org.apache.pivot.wtk.content">
- <listData>
- <collections:ArrayList>
- <content:ListItem text="A"/>
- <content:ListItem text="B"/>
- <content:ListItem text="C"/>
- </collections:ArrayList>
- </listData>
- </ListView>
- ]]>
- </source>
-
- <h4>Read-Only Sequences</h4>
+ <li>
<p>
- If the property represents a read-only sequence (a bean property whose getter returns
- an instance of <tt>org.apache.pivot.collections.Sequence</tt> and has no corresponding
- setter method), the contents of the element are added to the sequence. For example, the
- "tabs" property of the <tt>org.apache.pivot.wtk.TabPane</tt> class returns an instance
- of <tt>TabSequence</tt>, which implements <tt>Sequence<Component></tt>; tabs are
- added to a <tt>TabPane</tt> in WTKX as follows:
+ The <tt><bxml:script></tt> element is used to define a block of script code within
+ a BXML file. For example, the following script block defines a function named
+ <tt>foo()</tt>:
</p>
<source type="xml">
- <![CDATA[
- <TabPane xmlns="org.apache.pivot.wtk">
- <tabs>
- <Label text="Foo"/>
- <Label text="Bar"/>
- </tabs>
- </TabPane>
- ]]>
+ <![CDATA[
+ <bxml:script>
+ function foo() {
+ ....
+ }
+ </bxml:script>
+ ]]>
</source>
- <h4>Read-Only Dictionaries</h4>
<p>
- A property element may also represent a read-only dictionary (a bean property whose
- getter returns an instance of <tt>org.apache.pivot.collections.Dictionary</tt> but has
- no corresponding setter method). For example, the "userData" property of
- <tt>org.apache.pivot.wtk.Component</tt> (which the <tt>Label</tt> class in this example
- extends) represents a read-only dictionary:
+ By default, JavaScript is used as the scripting language in a BXML document, but any
+ JVM-compatible scripting language can be used. The <tt>language</tt> processing
+ instruction can be used to specify a different language; for example, the Groovy
+ scripting language:
</p>
<source type="xml">
- <![CDATA[
- <Label text="Hello, World!"
- xmlns="org.apache.pivot.wtk">
- <userData foo="123" bar="456"/>
- </Label>
- ]]>
+ <![CDATA[
+ <?language groovy?>
+ ]]>
</source>
<p>
- The attribute values are put into the dictionary using the attribute names as keys.
- </p>
-
- <h4>Listener Lists</h4>
- <p>
- Finally, the property may represent an event listener list (an instance of
- <tt>org.apache.pivot.util.ListenerList</tt>). If so, the sub-elements represent
- listeners of the appropriate type and are added to the listener list. This is discussed
- in more detail in the <a href="#scripting">Scripting</a> section.
+ Script blocks can also be defined in event handler attributes and elements, which are
+ discussed in more detail below.
</p>
+ </li>
- <h2>Attributes</h2>
+ <li>
<p>
- An attribute in WTKX may represent one of the following:
+ The <tt><bxml:define></tt> element is used to declare objects that will exist
+ outside of the hierarchy but may be referred to elsewhere.
</p>
- <ul>
- <li><p>A standard Java bean property setter</p></li>
- <li><p>A "static" property setter (explained below)</p></li>
- <li><p>An event listener</p></li>
- </ul>
-
- <h4>Java Bean Property Setters</h4>
-
<p>
- If an attribute represents a bean property setter, the attribute value is passed as the
- argument to the setter method. If the type of the property is a string, the value is
- passed as-is; however, if it is one of the simple types (<tt>boolean</tt>,
- <tt>char</tt>, <tt>byte</tt>, <tt>short</tt>, <tt>int</tt>, <tt>long</tt>,
- <tt>float</tt>, or <tt>double</tt>) or one of their wrapper equivalents, it is
- converted the appropriate type before invoking the setter. Whenever possible,
- <tt>WTKXSerializer</tt> will use <tt>BeanAdapter</tt> to determine what, if any,
- type conversion needs to take place. For example, given the following simple bean class:
+ For example, the following define block declares an instance of <tt>Foo</tt> named "myFoo"
+ that is not processed as part of the document flow (in other words, would not be added to
+ its parent element, if it had one) but can be referred to by variable name later in the
+ document:
</p>
- <source type="java">
- <![CDATA[
- package com.foo;
-
- public class MyBean {
- public String getFoo() { ... }
- public void setFoo(String foo) { ... }
- public int getBar() { ... }
- public void setBar(int bar) { ... }
- }
- ]]>
+ <source type="xml">
+ <![CDATA[
+ <bxml:define>
+ <Foo bxml:id="myFoo"/>
+ </bxml:define>
+ ]]>
</source>
+ </li>
+ <li>
<p>
- the following WTKX would instantiate the bean and invoke the "foo" and "bar" setters,
- passing a string to <tt>setFoo()</tt> and an int to <tt>setBar()</tt>:
+ The <tt><bxml:reference></tt> element is used to dereference a page variable. For
+ example, the <tt>Foo</tt> instance in the previous example could be dereferenced as
+ follows elsewhere in the document:
</p>
<source type="xml">
- <![CDATA[
- <MyBean foo="hello" bar="123"
- xmlns="com.foo"/>
- ]]>
+ <![CDATA[
+ <bxml:reference id="myFoo"/>
+ ]]>
</source>
<p>
- However, if the element represents a class that already implements the
- <tt>Dictionary</tt> interface (such as <tt>HashMap</tt>), the type of the attribute
- cannot be determined, no conversion takes place - the values are simply passed as
- strings.
+ Wherever this tag appears, it will effectively be replaced by the <tt>Foo</tt> instance
+ declared in the define block.
</p>
- <h4>Static Property Setters</h4>
<p>
- Attributes may also represent "static setters" (sometimes called "attached
- properties"). Attached properties are properties that only make sense in a particular
- context. They are not intrinsic to the class on which they are invoked, but are defined
- by another class (generally the parent container of a component).
+ The "$" variable deference operator can be used to dereference page variables in an
+ attribute. This operator is discussed in more detail below.
</p>
+ </li>
+ </ul>
<p>
- The following WTKX invokes the static setter for the <tt>TabPane</tt> class's "label"
- property:
+ The "bxml" namespace is generally declared on the root element of a BXML document as
+ follows:
</p>
<source type="xml">
- <![CDATA[
- <TabPane xmlns="org.apache.pivot.wtk">
- <tabs>
- <Label TabPane.label="First Tab" text="Tab 1"/>
- <tabs>
- </TabPane>
- ]]>
+ <![CDATA[
+ <Bar xmlns:bxml="http://pivot.apache.org/bxml"
+ xmlns="com.foo">
+ ...
+ </Bar>
+ ]]>
</source>
+ <h2>Elements</h2>
<p>
- This translates roughly to the following in Java:
+ In BXML, an XML element that does not begin with the reserved "bxml" namespace prefix
+ represents one of the following:
</p>
- <source type="java">
- <![CDATA[
- TabPane tabPane = new TabPane();
- Label label = new Label();
- label.setText("Tab 1");
- tabPane.getTabs().add(label);
- TabPane.setLabel(label, "First Tab");
- ]]>
- </source>
+ <ul>
+ <li><p>A class instance</p></li>
+ <li><p>A property of a class instance</p></li>
+ <li><p>A "static" property</p></li>
+ </ul>
+
+ <p>Each of these is discussed in more detail below.</p>
+ <h3>Class Instances</h3>
<p>
- The call to <tt>TabPane.setLabel()</tt> attaches the "name" property to the
- <tt>Label</tt> instance. The tab pane then uses the value of this property as the
- button data for the label's tab in the tab panes button bar. <tt>TabPane</tt> also
- defines a static setter for a tab's icon. Other containers, including
- <tt>Accordion</tt> and <tt>TablePane</tt>, define similar setters.
+ If an element's tag name begins with an uppercase letter (and it is not a "static"
+ property setter; see below), it is considered a class instance. When
+ <tt>BXMLSerializer</tt> encounters such an element, creates an instance of that class. As
+ discussed above, the XML namespace prefix is used to determine the Java package to which
+ the class belongs.
</p>
<p>
- Note that, although the static setter attribute is declared first in the WTKX, it is
- actually invoked after the setter for the "text" property (as well as after the
- <tt>Label</tt> instance has been added to the tab pane). This is because static setters
- often cannot be called until after the object on which they are invoked has been added
- to an instance of the parent class that defines the setter. The act of adding the
- object to the parent effectively makes the attached properties available. Conversely,
- removing the object from the parent also removes any previously attached properties.
+ For example, the following BXML would produce an instance of the
+ <tt>org.apache.pivot.wtk.Label</tt> class populated with the text "Hello, World!":
</p>
- <h4>Event Listeners</h4>
+ <source type="xml">
+ <![CDATA[
+ <Label text="Hello, World!" xmlns="org.apache.pivot.wtk" />
+ ]]>
+ </source>
+
<p>
- Finally, an attribute may represent an event listener. The attribute value contains
- script code that is executed in response to the event. This is discussed in more detail
- in the <a href="#scripting">Scripting</a> section.
+ Class instance elements in a BXML file will often represent instances of Java bean types.
+ Internally, the BXML serializer uses an instance of
+ <tt>org.apache.pivot.beans.BeanAdapter</tt> to wrap the instantiated class and invoke its
+ setter methods. This class implements the <tt>org.apache.pivot.collections.Dictionary</tt>
+ interface and allows a caller to get and set bean property values as key/value pairs.
</p>
- <h3>Resolution Operators</h3>
<p>
- Setter attributes (either bean or static) in WTKX support several resolution operators
- that extend their type handling capabilities:
+ However, if the element represents a type that already implements the <tt>Dictionary</tt>
+ interface (such as <tt>org.apache.pivot.collections.HashMap</tt>), it is not wrapped and
+ its dictionary methods are used directly. For example, the following BXML creates an
+ instance of <tt>org.apache.pivot.collections.HashMap</tt> and sets its "foo" and "bar"
+ values to "123" and "456", respectively:
+ </p>
+
+ <source type="xml">
+ <![CDATA[
+ <HashMap foo="123" bar="456"/>
+ ]]>
+ </source>
+
+ <h3>Instance Properties</h3>
+ <p>
+ Elements whose tag names begin with a lowercase letter represent instance properties. An
+ instance property element may represent one of the following:
</p>
<ul>
- <li><p>Object dereference</p></li>
- <li><p>Resource resolution</p></li>
- <li><p>URL resolution</p></li>
+ <li><p>A property setter</p></li>
+ <li><p>A read-only sequence</p></li>
+ <li><p>A read-only dictionary</p></li>
+ <li><p>An event listener list</p></li>
</ul>
- <h4>Object Dereference</h4>
-
<p>
- The object deference operator allows a caller to replace an attribute value with an
- instance of a named object before the corresponding setter method is invoked. Any
- attribute whose value begins with the "$" is considered an object reference.
+ <tt>BXMLSerializer</tt> uses a bean adapter to obtain information about the type of the
+ property so that it can process the element's contents correctly.
</p>
+ <h4>Property Setters</h4>
<p>
- For example, a table view header must be associated with an instance of TableView; in
- Java, this is done via the <tt>setTableView()</tt> method. In WTKX, the object
- dereference operator is used. The following WTKX defines an instance of
- <tt>ScrollPane</tt>, setting a <tt>TableView</tt> as its view component and a
- <tt>TableViewHeader</tt> as the column header. The table view is associated with the
- header via the "tableView" attribute:
+ If the element represents a Java bean property setter, the contents of the element (which
+ must be either a text node or a class instance element) are passed as the value to the
+ setter for the property. For example, the following BXML creates an instance of the
+ <tt>Label</tt> class and sets the value of the label's "text" property to "Hello, World!":
</p>
<source type="xml">
- <![CDATA[
- <ScrollPane xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx">
- <view>
- <TableView wtkx:id="tableView">
- ...
- </TableView>
- </view>
- <columnHeader>
- <TableViewHeader tableView="$tableView"/>
- </columnHeader>
- </ScrollPane>
- ]]>
+ <![CDATA[
+ <Label xmlns="org.apache.pivot.wtk">
+ <text>Hello, World!</text>
+ </Label>
+ ]]>
</source>
<p>
- Note the use of the "wtkx" namespace prefix in the preceding example. This is a special
- namespace reserved by the WTKX serializer. As shown above, it defines an "id" element
- that is used to assign a name to a class instance. In addition to the object
- dereference operator, this ID can also be used to obtain a reference to the
- instantiated element in the Java code that processes the WTKX or by script code defined
- or included by the WTKX file.
+ It produces the same result as the earlier example which used an attribute to set the
+ "text" property:
</p>
+ <source type="xml">
+ <![CDATA[
+ <Label text="Hello, World!" xmlns="org.apache.pivot.wtk"/>
+ ]]>
+ </source>
+
<p>
- Other special elements are also defined by the <tt>wtkx</tt> namespace. Each are
- discussed in more detail in later sections.
+ This example creates an instance of <tt>ListView</tt> and sets the value of its
+ "listData" property to an instance of <tt>org.apache.pivot.collections.ArrayList</tt>
+ that has been populated with several instances of
+ <tt>org.apache.pivot.wtk.content.ListItem</tt> (a data class recognized by the default
+ list item renderer):
</p>
- <h4>Resource Resolution</h4>
+ <source type="xml">
+ <![CDATA[
+ <ListView xmlns="org.apache.pivot.wtk"
+ xmlns:collections="org.apache.pivot.collections"
+ xmlns:content="org.apache.pivot.wtk.content">
+ <listData>
+ <collections:ArrayList>
+ <content:ListItem text="A"/>
+ <content:ListItem text="B"/>
+ <content:ListItem text="C"/>
+ </collections:ArrayList>
+ </listData>
+ </ListView>
+ ]]>
+ </source>
+
+ <h4>Read-Only Sequences</h4>
<p>
- In WTKX, resource substitution can be performed at load time for localization purposes.
- When given an instance of <tt>org.apache.pivot.util.Resources</tt>,
- <tt>WTKXSerializer</tt> will replace instances of resource names with their
- locale-specific values. Resource names are identified by a "%" prefix, as shown below:
+ If the property represents a read-only sequence (a bean property whose getter returns an
+ instance of <tt>org.apache.pivot.collections.Sequence</tt> and has no corresponding setter
+ method), the contents of the element are added to the sequence. For example, the "tabs"
+ property of the <tt>org.apache.pivot.wtk.TabPane</tt> class is a read-only sequence
+ representing the tab pane's tab components. Tabs can be added to a <tt>TabPane</tt> in
+ BXML as follows:
</p>
<source type="xml">
- <![CDATA[
- <Label text="%myText"/
- xmlns="org.apache.pivot.wtk">
- ]]>
+ <![CDATA[
+ <TabPane xmlns="org.apache.pivot.wtk">
+ <tabs>
+ <Label text="Foo"/>
+ <Label text="Bar"/>
+ </tabs>
+ </TabPane>
+ ]]>
</source>
+ <h4>Read-Only Dictionaries</h4>
<p>
- The associated localized resource file might contain something like the following:
+ A property element may also represent a read-only dictionary (a bean property whose getter
+ returns an instance of <tt>org.apache.pivot.collections.Dictionary</tt> but has no
+ corresponding setter method). For example, the "userData" property of the
+ <tt>org.apache.pivot.wtk.Component</tt> class represents a read-only dictionary:
</p>
- <source type="jscript">
- <![CDATA[
- { myText:"This is my text!"
- }
- ]]>
+ <source type="xml">
+ <![CDATA[
+ <Label text="Hello, World!"
+ xmlns="org.apache.pivot.wtk">
+ <userData foo="123" bar="456"/>
+ </Label>
+ ]]>
</source>
<p>
- producing a label displaying the text "This is my text!".
+ The attribute values are put into the dictionary using the attribute names as keys.
</p>
+ <h4>Listener Lists</h4>
<p>
- <tt>WTKXSerializer</tt> is discussed in more detail below.
+ Finally, the property may represent an event listener list (an instance of
+ <tt>org.apache.pivot.util.ListenerList</tt>). If so, the sub-elements represent
+ listeners of the appropriate type and are added to the listener list. This is discussed
+ in more detail in the <a href="#scripting">Scripting</a> section.
</p>
- <h4>URL Resolution</h4>
+ <h4>Default Properties</h4>
<p>
- Attributes can also be used to specify URLs. An attribute that begins with the "@"
- character is converted to a URL whose path is interpreted as relative to the location
- of the WTKX source file. For example, the following WTKX would load an image from the
- same directory as the WTKX file into an <tt>ImageView</tt> component. This WTKX
- translates to a call to the <tt>ImageView#setImage(java.net.URL)</tt> method:
+ A class may define a "default property" using the <tt>@DefaultProperty</tt> annotation
+ defined in the <tt>org.apache.pivot.beans</tt> package. If present, the sub-element
+ representing the default property can be omitted from the markup. For example, the
+ <tt>TabPane</tt> component discussed above defines the "tabs" property as the default, so
+ the <tabs>sub-element is not required:
</p>
<source type="xml">
- <![CDATA[
- <ImageView image="@foo.png"
- xmlns="org.apache.pivot.wtk"/>
- ]]>
+ <![CDATA[
+ <TabPane xmlns="org.apache.pivot.wtk">
+ <Label text="Foo"/>
+ <Label text="Bar"/>
+ </TabPane>
+ ]]>
</source>
<p>
- Without the "@" operator, bean properties would have no context by which to determine
- the path to such a resource.
+ Taking advantage of default properties can significantly reduce the verbosity of BXML
+ markup.
</p>
- <h2>Includes</h2>
+ <h3>Static Properties</h3>
+
<p>
- The <tt><wtkx:include></tt> tag allows a WTKX file to embed content defined in an
- external WTKX file as if it was defined in the source file itself. This is useful for
- partitioning content into manageable pieces (for example, when working on large
- applications or with multiple developers, or when defining reusable content templates).
+ Finally, an element may represent a "static" property setter (sometimes called an
+ "attached property"). Static properties are properties that only make sense in a
+ particular context. They are not intrinsic to the class to which they are applied, but
+ are defined by another class (generally the parent container of a component).
</p>
<p>
- The following WTKX defines a Window whose content is defined in an external file named
- "content.wtkx":
+ For example, The following BXML invokes the static setter for the TabPane class's
+ "tabData" property:
</p>
<source type="xml">
- <![CDATA[
- <Window xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx">
- <content>
- <wtkx:include src="content.wtkx"/>
- </content>
- </Window>
- ]]>
- </source>
-
- <source type="xml">
- <![CDATA[
- <-- content.wtkx -->
- <Label xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx"
- wtkx:id="label" text="Hello, World!"/>
- ]]>
+ <![CDATA[
+ <TabPane xmlns:content="org.apache.pivot.wtk.content"
+ xmlns="org.apache.pivot.wtk">
+ <Label text="Tab 1">
+ <TabPane.tabData>
+ <content:ButtonData text="First Tab"/>
+ </TabPane.tabData>
+ </Label>
+ </TabPane>
+ ]]>
</source>
<p>
- By default, the contents of the included file are loaded using a nested instance of
- <tt>WTKXSerializer</tt>. The nested serializer creates a separate namespace for the
- include, which prevents naming collisions with the parent file. If the
- <tt><wtkx:include></tt> tag itself is given an ID, the contents of the include's
- namespace can be accessed externally via JSON path syntax. For example, given the
- following root WTKX, the <tt>Label</tt> instance can be accessed via the path
- "content.label":
+ This translates roughly to the following in Java:
</p>
- <source type="xml">
- <![CDATA[
- <-- window.wtkx -->
- <Window xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx">
- <content>
- <wtkx:include wtkx:id="content" src="content.wtkx"/>
- </content>
- </Window>
- ]]>
+ <source type="java">
+ <![CDATA[
+ TabPane tabPane = new TabPane();
+
+ Label label = new Label();
+ label.setText("Tab 1");
+
+ ButtonData buttonData = new ButtonData();
+ buttonData.setText("First Tab");
+ TabPane.setTabData(label, buttonData);
+
+ tabPane.getTabs().add(label);
+ ]]>
</source>
<p>
- However, it is sometimes useful to allow an include to inherit the namespace of the
- parent file. The <tt>inline</tt> attribute can be used for this purpose. When set
- to "true", the include will not be assigned a new, unique namespace but will instead
- share the parent file's namespace.
+ The call to <tt>TabPane.setTabData()</tt> attaches the "tabData" property to the
+ <tt>Label</tt> instance. The tab pane then uses the value of this property as the button
+ data for the label's tab in the tab pane's button bar. Other containers, including
+ <tt>Accordion</tt> and <tt>TablePane</tt>, define similar setters (as well as getters).
</p>
- <h2><a name="defines">Defines</a></h2>
+ <h2>Attributes</h2>
+ <p>
+ An attribute in BXML may represent one of the following:
+ </p>
+
+ <ul>
+ <li><p>A property of a class instance</p></li>
+ <li><p>A "static" property</p></li>
+ <li><p>An event listener</p></li>
+ </ul>
+
+ <p>As with elements, <tt>BXMLSerializer</tt> uses an instance of <tt>BeanAdapter</tt> to
+ determine what type of property an attribute represents.</p>
+
+ <h4>Instance Properties</h4>
<p>
- In general, class instance elements declared in WTKX are expected to have a parent tag
- that represents a sequence of some sort (generally, either as a parent container or a
- property of a parent container). However, it is sometimes desirable to declare objects
- for use in a WTKX file that do not have or need a direct parent. The
- <tt><wtkx:define></tt> tag can be used for this purpose.
+ If an attribute represents an instance property, the attribute value is passed as the
+ argument to the setter method. If the type of the property is a string, the value is
+ passed as-is; otherwise, <tt>BXMLSerializer</tt> attempts to convert the value to the
+ appropriate type using the <tt>BeanAdapter#coerce()</tt> method. For example, given the
+ following simple bean class:
</p>
+ <source type="java">
+ <![CDATA[
+ package com.foo;
+
+ public class MyBean {
+ public String getFoo() { ... }
+ public void setFoo(String foo) { ... }
+ public int getBar() { ... }
+ public void setBar(int bar) { ... }
+ }
+ ]]>
+ </source>
+
<p>
- For example, the following WTKX instantiates a login dialog by including a file named
- "login_dialog.wtkx" within a define block. The dialog instance is assigned an ID,
- presumably so it can be used by an event handler defined in script or Java code later
- on:
+ the following BXML would instantiate the bean and invoke the "foo" and "bar" setters,
+ passing a string to <tt>setFoo()</tt> and an int to <tt>setBar()</tt>:
</p>
<source type="xml">
- <![CDATA[
- <Window xmlns:wtkx="http://pivot.apache.org/wtkx"
- xmlns="org.apache.pivot.wtk">
- <wtkx:define>
- <wtkx:include wtkx:id="loginDialog" src="login_dialog.wtkx"/>
- </wtkx:define>
-
- <content>
- ...
- </content>
- </Window>
- ]]>
+ <![CDATA[
+ <MyBean foo="hello" bar="123"/>
+ ]]>
</source>
- <h2><a name="scripting">Scripting</a></h2>
<p>
- The <tt><wtkx:script></tt> tag allows a caller to import scripting code into or
- embed script within a WTKX file. Any JVM scripting language can be used. The name of
- the scripting language is passed to the <tt>WTKXSerializer</tt> instance that is used
- to load the WTKX file. <tt>WTKXSerializer</tt> is discussed in more detail below.
+ Note that, if the parent element represents an untyped class (a class that implements
+ the <tt>Dictionary</tt> interface rather than a Java bean, such as <tt>HashMap</tt>), the
+ type of the attribute cannot be determined, and no conversion takes place - the values are
+ simply passed as strings.
</p>
+ <h4>Static Properties</h4>
<p>
- For example, the following WTKX defines a JavaScript block that defines a variable
- named "foo". The value of this variable is used to populate the <tt>Label</tt> instance
- that is declared as the window's content:
+ Like elements, attributes may also represent static property setters. For example, The
+ following BXML invokes the static setter for the TabPane class's "tabData" property:
</p>
<source type="xml">
- <![CDATA[
- <Window xmlns:wtkx="http://pivot.apache.org/wtkx"
- xmlns="org.apache.pivot.wtk">
- <wtkx:script>
- var foo = "Hello, World!";
- </wtkx:script>
- <content>
- <Label text="$foo"/>
- </content>
- </Window>
- ]]>
+ <![CDATA[
+ <TabPane xmlns:content="org.apache.pivot.wtk.content"
+ xmlns="org.apache.pivot.wtk">
+ <Label text="Tab 1" TabPane.tabData="First Tab"/>
+ </TabPane>
+ ]]>
</source>
<p>
- The script could also have been defined in an external file:
+ This translates roughly to the following in Java:
</p>
- <source type="xml">
- <![CDATA[
- <Window xmlns:wtkx="http://pivot.apache.org/wtkx"
- xmlns="org.apache.pivot.wtk">
- <wtkx:script src="foo.js"/>
- <content>
- <Label text="$foo"/>
- </content>
- </Window>
- ]]>
+ <source type="java">
+ <![CDATA[
+ TabPane tabPane = new TabPane();
+
+ Label label = new Label();
+ label.setText("Tab 1");
+
+ TabPane.setTabData(label, "First Tab");
+
+ tabPane.getTabs().add(label);
+ ]]>
</source>
<p>
- In either case, any global variables declared in a script are added to the WTKX file's
- namespace, and become available for use by the object dereference operator (as shown)
- as well as to callers via the <tt>WTKXSerializer#get()</tt> method discussed below.
+ As explained in the element example, the tab pane uses the value of the "tabData"
+ property as the button data for the tab component's tab button.
</p>
- <h3>Listener List Elements</h3>
+ <h4>Event Listeners</h4>
<p>
- Script code can also be used to define event handlers in WTKX. Event handlers can
- often be defined more succinctly in script than in Java. For example, given the
- following WTKX:
+ Finally, an attribute may represent an event listener. The attribute value contains
+ script code that is executed in response to the event. This is discussed in more detail
+ in the <a href="#scripting">Scripting</a> section.
</p>
- <source type="xml">
- <![CDATA[
- <PushButton xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx"
- wtkx:id="pushButton" buttonData="Click Me!"/>
- ]]>
- </source>
-
+ <h3>Resolution Operators</h3>
<p>
- the Java code to obtain a reference to a <tt>PushButton</tt> and attach a button press
- listener to it might look like this:
+ Setter attributes (either bean or static) in BXML support several resolution operators
+ that extend their type handling capabilities:
</p>
- <source type="java">
- <![CDATA[
- PushButton pushButton = (PushButton)wtkxSerializer.get("pushButton");
+ <ul>
+ <li><p>Object dereference</p></li>
+ <li><p>Resource resolution</p></li>
+ <li><p>URL resolution</p></li>
+ </ul>
- pushButton.getButtonPressListeners().add(new ButtonPressListener() {
- public void buttonPressed(Button button) {
- // Handle event
- }
- });
- ]]>
- </source>
+ <h4>Object Dereference</h4>
<p>
- While this is simple enough, it can become cumbersome in any non-trivial application
- where many such event handlers are defined. It also dissociates the event handler from
- the element to which it applies, making it difficult to track down event handling logic.
+ The object deference operator ("$") allows a caller to replace an attribute value with
+ an instance of a named object before the corresponding setter method is invoked. Any
+ attribute whose value begins with the "$" is considered an object reference.
</p>
<p>
- A similar event handler might be defined in JavaScript as follows:
+ For example, a table view header must be associated with an instance of TableView; in
+ Java, this is done via the <tt>setTableView()</tt> method. In BXML, the object
+ dereference operator is used. The following BXML defines an instance of
+ <tt>ScrollPane</tt>, setting a <tt>TableView</tt> as its view component and a
+ <tt>TableViewHeader</tt> as the column header. The table view is associated with the
+ header via the "tableView" attribute:
</p>
<source type="xml">
- <![CDATA[
- <PushButton xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx"
- buttonData="Click Me!">
- <buttonPressListeners>
- <wtkx:script>
- function buttonPressed(button) {
- // Handle event
- }
- </wtkx:script>
- </buttonPressListeners>
- </PushButton>
- ]]>
+ <![CDATA[
+ <ScrollPane xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml">
+ <view>
+ <TableView bxml:id="tableView">
+ ...
+ </TableView>
+ </view>
+
+ <columnHeader>
+ <TableViewHeader tableView="$tableView"/>
+ </columnHeader>
+ </ScrollPane>
+ ]]>
</source>
+ <h4>Resource Resolution</h4>
<p>
- This version is quite a bit easier to read, and creates a much stronger association
- between the button and the handler. It doesn't even require the button to be given an
- ID.
+ In BXML, resource substitution can be performed at load time for localization purposes.
+ When given an instance of <tt>org.apache.pivot.util.Resources</tt>, <tt>BXMLSerializer</tt>
+ will replace instances of resource names with their locale-specific values. Resource
+ names are identified by a "%" prefix, as shown below:
</p>
- <p>
- When script is declared within a listener list element, <tt>WTKXSerializer</tt> creates
- a special scope that is local to the handler. As a result, any variables or functions
- defined within the script block do not pollute the page's global namespace and are only
- visible within the block.
- </p>
+ <source type="xml">
+ <![CDATA[
+ <Label text="%myText"/>
+ ]]>
+ </source>
<p>
- Also, though it isn't obvious from this simple example, script-based event handlers are
- not required to provide implementations for every method defined by the listener
- interface. Any omitted methods are simply processed by a default no-op handler.
+ The associated resource file might contain something like the following:
</p>
- <h3>Event Listener Attributes</h3>
+ <source type="jscript">
+ <![CDATA[
+ { myText:"This is my text!"
+ }
+ ]]>
+ </source>
+
<p>
- Event listeners can also be declared in attributes, using a syntax similar to that used
- for static property setters. The attribute name for an event listener consists of the
- name of the interface that defines the event plus the name of the event, separated by a
- period. Like listener list elements, a special scope is created for listener attributes
- that is local to the handler; any variables defined within the attribute are only
- visible within the handler.
+ producing a label containing the text "This is my text!".
</p>
+ <h4>URL Resolution</h4>
<p>
- For example, the above button press listener can be declared in an attribute as follows:
+ Attributes can also be used to specify URLs. An attribute that begins with the "@"
+ character is converted to a URL whose path is interpreted as relative to the location of
+ the BXML source file. For example, the following BXML would load an image from the same
+ directory as the BXML file into an <tt>ImageView</tt> component. This BXML translates to a
+ call to the <tt>ImageView#setImage(java.net.URL)</tt> method:
</p>
<source type="xml">
- <![CDATA[
- <PushButton xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx"
- buttonData="Click Me!"
- ButtonPressListener.buttonPressed="handleEvent(arguments[0])"/>
- ]]>
+ <![CDATA[
+ <ImageView image="@foo.png"/>
+ ]]>
</source>
<p>
- Note that the handler function is passed a value of <tt>arguments[0]</tt>. The
- <tt>arguments</tt> array contains the arguments that were originally passed to the event
- listener method, and only exists within the scope of the event handler.
- <tt>arguments[0]</tt> contains the first argument passed to the listener method, which
- in this case is a reference to the button that fired the event.
+ Without the "@" operator, bean properties would have no context by which to determine the
+ path to such a resource.
</p>
+ <h2><a name="scripting">Scripting</a></h2>
<p>
- Attribute-based event handlers are well suited to short handler code that, ideally,
- fits on a single line. Longer event handler code may be better suited to an
- element-based listener list, or, depending on the level of complexity, a Java-based
- event handler.
+ The <tt><bxml:script></tt> tag allows a caller to import scripting code into or
+ embed script within a BXML file. Any JVM scripting language can be used, including
+ JavaScript, Groovy, and Clojure, among others.
</p>
- <h2>WTKXSerializer</h2>
<p>
- The <tt>org.apache.pivot.wtkx.WTKXSerializer</tt> class, which has been mentioned in
- previous sections, is what drives the actual loading and processing of a WTKX file and
- its associated script and includes. It implements the
- <tt>org.apache.pivot.serialization.Serializer</tt> interface, and returns the object
- hierarchy corresponding to the structure declared within the WTKX file. It defines the
- following overloads for the <tt>readObject()</tt> method:
+ For example, the following BXML defines a JavaScript block that defines a variable
+ named "foo". The value of this variable is used to populate the <tt>Label</tt> instance
+ that is declared as the window's content:
</p>
- <source type="java">
- <![CDATA[
- public Object readObject(String resourceName) { ... }
- public Object readObject(URL location) { ... }
- public Object readObject(InputStream inputStream) { ... }
- ]]>
+ <source type="xml">
+ <![CDATA[
+ <Window xmlns:bxml="http://pivot.apache.org/bxml"
+ xmlns="org.apache.pivot.wtk">
+ <bxml:script>
+ var foo = "Hello, World!";
+ </bxml:script>
+ <Label text="$foo"/>
+ </Window>
+ ]]>
+ </source>
+
+ <p>
+ The script could also have been defined in an external file:
+ </p>
+
+ <source type="xml">
+ <![CDATA[
+ <Window xmlns:bxml="http://pivot.apache.org/bxml"
+ xmlns="org.apache.pivot.wtk">
+ <bxml:script src="foo.js"/>
+ <Label text="$foo"/>
+ </Window>
+ ]]>
</source>
<p>
- The first version loads a WTKX file from a resource specified on the application's
- classpath. This method delegates to the second version, which loads a resource from an
- arbitrary URL. Callers must use one of these versions in order to use the URL
- resolution operator described in the previous section, since the location URL is used
- as the base URL for any relative URLs specified in the file.
+ In either case, any global variables declared in a script are added to the BXML file's
+ variable namespace and become available for use by the object dereference operator,
+ the <bxml:reference> tag, and to callers via <tt>BXMLSerializer#getNamespace()</tt>,
+ discussed in more detail below.
</p>
+ <h3>Listener List Elements</h3>
<p>
- The second method delegates in turn to the third version, which performs the actual
- processing and returns the deserialized object graph. For example, given the following
- WTKX, which defines a root <tt>Window</tt> object and sets its contents to a
- <tt>Label</tt> displaying the text "Hello, World!":
+ Script code can also be used to define event handlers in BXML. Events can often be
+ handled more succinctly in script than in Java. For example, given the following BXML:
</p>
<source type="xml">
- <![CDATA[
- <Window xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx">
- <content>
- <Label wtkx:id="label" text="Hello, World!"/>
- </content>
- <Window>
- ]]>
+ <![CDATA[
+ <PushButton xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml"
+ bxml:id="pushButton" buttonData="Click Me!"/>
+ ]]>
</source>
<p>
- this Java code, taken from an implementation of
- <tt>org.apache.pivot.wtk.Application</tt>, would load the WTKX into a local variable
- and open the window on the application's display:
+ the Java code to obtain a reference to a <tt>PushButton</tt> and attach a button press
+ listener to it might look like this:
</p>
<source type="java">
- <![CDATA[
- public void startup(Display display, Map<String, String> properties)
- throws Exception {
- WTKXSerializer wtkxSerializer = new WTKXSerializer();
-
- Window window =
- (Window)wtkxSerializer.readObject(getClass().getResource("window.wtkx"));
- window.open(display);
+ <![CDATA[
+ PushButton pushButton = (PushButton)bxmlSerializer.getNamespace().get("pushButton");
+
+ pushButton.getButtonPressListeners().add(new ButtonPressListener() {
+ public void buttonPressed(Button button) {
+ // Handle event
}
- ]]>
+ });
+ ]]>
</source>
- <h3>Accessing Named Objects</h3>
<p>
- As previously discussed, the <tt>WTKXSerializer#get()</tt> method allows a caller to
- retrieve a named object instance from a WTKX file once the root object has been loaded.
- The <tt>readObject()</tt> method populates a map of named object IDs to object
- instances that can later be used to obtain a reference to those objects.
+ While this is simple enough, it can become cumbersome in any non-trivial application
+ where many such event handlers are defined. A similar event handler might be defined
+ in JavaScript as follows:
</p>
+ <source type="xml">
+ <![CDATA[
+ <PushButton xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml"
+ buttonData="Click Me!">
+ <buttonPressListeners>
+ function buttonPressed(button) {
+ // Handle event
+ }
+ </buttonPressListeners>
+ </PushButton>
+ ]]>
+ </source>
+
<p>
- Continuing the previous example, the following code would obtain a reference to the
- <tt>Label</tt> instance and change its text to "Welcome to Pivot"!:
+ This version is quite a bit easier to read, and creates a strong association between
+ the button and the handler. It also doesn't require the button to have an ID.
</p>
- <source type="java">
- <![CDATA[
- public void startup(Display display, Map<String, String> properties)
- throws Exception {
- WTKXSerializer wtkxSerializer = new WTKXSerializer();
-
- Window window =
- (Window)wtkxSerializer.readObject(getClass().getResource("window.wtkx"));
- Label label = wtkxSerializer.getObjectByID("label");
- label.setText("Welcome to Pivot!");
- window.open(display);
- }
- ]]>
- </source>
+ <p>
+ When script is declared within a listener list element, <tt>BXMLSerializer</tt> creates a
+ special scope that is local to the handler. As a result, any variables or functions
+ defined within the script block do not pollute the page's global namespace and are only
+ visible within the block.
+ </p>
<p>
- <tt>WTKXSerializer</tt> implements the <tt>Dictionary</tt> interface, so callers can
- also use the <tt>put()</tt> or <tt>remove()</tt> methods to modify the serializer's
- namespace before the WTKX file is loaded (effectively "parameterizing" the WTKX).
+ Also, though it isn't obvious from this simple example, script-based event handlers are
+ not required to provide implementations for every method defined by the listener interface.
+ Any omitted methods are simply processed by a default no-op handler.
</p>
- <h4>Nested Includes</h4>
+ <h3>Event Listener Attributes</h3>
<p>
- As mentioned earlier, objects defined in WTKX includes can also be retrieved via
- <tt>get()</tt>. The ID of the included file defines the namespace for the include;
- callers can use a dot-separated namespace path to a nested object to access it:
+ Event listeners can also be declared in attributes, using a syntax similar to that used for
+ static property setters. The attribute name for an event listener consists of the name of
+ the interface that defines the event plus the name of the event, separated by a period.
+ Like listener list elements, a special scope is created for listener attributes that is
+ local to the handler; any variables defined within the attribute are only visible within
+ the handler.
</p>
- <source type="java">
- <![CDATA[
- Label label = (Label)wtkxSerializer.get("content.label")
- ]]>
+ <p>
+ For example, the above button press listener can be declared in an attribute as follows:
+ </p>
+
+ <source type="xml">
+ <![CDATA[
+ <PushButton xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml"
+ buttonData="Click Me!"
+ ButtonPressListener.buttonPressed="handleEvent(arguments[0])"/>
+ ]]>
</source>
<p>
- where "content" is the ID of the <tt><wtkx:include></tt> and "label" is the ID
- of the label itself.
+ Note that the handler function is passed a value of <tt>arguments[0]</tt>. The
+ <tt>arguments</tt> array contains the arguments that were originally passed to the event
+ listener method, and only exists within the scope of the event handler.
+ <tt>arguments[0]</tt> contains the first argument passed to the listener method, which in
+ this case is a reference to the button that fired the event.
+ </p>
+
+ <p>
+ Attribute-based event handlers are well suited to short handler code that, ideally, fits
+ on a single line. Longer event handler code may be better suited to an element-based
+ listener list, or, depending on the level of complexity, a Java-based event handler.
+ </p>
+
+ <h3>Accessing Named Objects</h3>
+ <p>
+ As previously discussed, the <tt>BXMLSerializer#getNamespace()</tt> method allows a caller
+ to retrieve a named object instance from a BXML file once the root object has been loaded.
+ For example, the following code loads a hypothetical BXML file containing a <tt>Window</tt>
+ and a <tt>Label</tt> instance, obtains a reference to the label, changes its text to
+ "Welcome to Pivot!", and opens the window:
</p>
- <h3>WTKX Binding</h3>
+ <source type="java">
+ <![CDATA[
+ public void startup(Display display, Map<String, String> properties)
+ throws Exception {
+ BXMLSerializer bxmlSerializer = new BXMLSerializer();
+ Window window =
+ (Window)bxmlSerializer.readObject(getClass().getResource("window.bxml"));
+
+ Label label = bxmlSerializer.getNamespace().get("label");
+ label.setText("Welcome to Pivot!");
+
+ window.open(display);
+ }
+ ]]>
+ </source>
<p>
- The <tt>org.apache.pivot.wtkx</tt> package includes an annotation that can be used to
- simplify the process of mapping named objects into a Java application. The
- <tt>@WTKX</tt> annotation is used to tag a member variable so that it will be
- automatically mapped to a named object in a WTKX file.
+ <tt>getNamespace()</tt> returns a value that implements the <tt>Dictionary</tt> interface,
+ so callers can also use the <tt>put()</tt> or <tt>remove()</tt> methods to modify the
+ serializer's namespace before the BXML file is loaded (effectively "parameterizing"
+ the BXML).
</p>
+ <h3>The Bindable Interface</h3>
+
<p>
- The <tt>bind()</tt> method of <tt>WTKXSerializer</tt> is used to perform the actual
- mapping. However, it is often easier to use the <tt>Bindable</tt> interface.
- Implementing this interface ensures that <tt>bind()</tt> will be automatically called
- on the implementing class by the WTKX serializer.
+ The <tt>org.apache.pivot.beans.Bindable</tt> interface can be used to simplify the process
+ of mapping named objects into a Java application. This interface defines a single method,
+ <tt>initialize()</tt>, that is called when the root element of a BXML file has been fully
+ loaded. This allows the implementing class to get access to the document's namespace
+ (i.e. page variables), the resources that were used to load it, and the location it was
+ loaded from, to perform any necessary post-processing (for example, registering event
+ listeners).
</p>
<p>
- <tt>Bindable</tt> defines a single method, <tt>initialize()</tt>, that is called when
- the root element of a WTKX file has been fully loaded and the bound values have been
- processed. This allows the bound class to perform any required initialization (often
- event registration on the bound members). It takes a single argument of type
- <tt>org.apache.pivot.util.Resources</tt> that contains the resources used to load the
- file (if any).
+ Note that only the root element will be called to <tt>initialize()</tt>, because the
+ bindable properties (namespace, resources, and location) apply to the document as a whole,
+ not to individual sub-elements. However, this includes the root elements of any BXML files
+ included using the <bxml:include> tag, allowing <tt>Bindable</tt> implementations to
+ effectively implement the "code behind" the markup of each BXML file used by an
+ application.
</p>
+ <h4>@BXML</h4>
<p>
- For example, given the following WTKX:
+ If any of the <tt>Bindable</tt>'s member variables are tagged with the
+ <tt>org.apache.pivot.beans.BXML</tt> annotation, they will be automatically populated
+ with the corresponding variables defined in the BXML file. For example, given the
+ following BXML:
</p>
<source type="xml">
- <![CDATA[
- <Window xmlns="org.apache.pivot.wtk"
- xmlns:wtkx="http://pivot.apache.org/wtkx">
- <content>
- <Label wtkx:id="label" text="Hello, World!"/>
- </content>
- <Window>
- ]]>
+ <![CDATA[
+ <Window xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml">
+ <Label bxml:id="label" text="Hello, World!"/>
+ <Window>
+ ]]>
</source>
<p>
- a Java member variable declared as follows will be automatically populated with the
- declared <tt>Label</tt> instance when the declaring class is bound:
+ a Java member variable declared as follows will be automatically populated with the
+ declared <tt>Label</tt> instance when the BXML file is deserialized:
</p>
<source type="java">
- <![CDATA[
- @WTKX private Label label;
- ]]>
+ <![CDATA[
+ @BXML private Label label;
+ ]]>
</source>
<p>
- As a result, the <tt>@WTKX</tt> annotation can significanly simplify the process of
- working with loaded WTKX data in Java code. However, it is important to note that,
- because WTKX binding relies on reflection to set the member variables, it can only be
- used with trusted code or to set the values of public fields.
+ As a result, the <tt>@BXML</tt> annotation can significanly simplify the process of
+ working with loaded BXML data in Java code. However, it is important to note that, because
+ BXML binding relies on reflection to set the member variables, it can only be used with
+ trusted code or to set the values of public fields. For untrusted code, the namespace
+ value passed to the <tt>initialize()</tt> method can be used to obtain named objects
+ defined in a BXML file.
</p>
<h2>Summary</h2>
<p>
- WTKX provides a number of features that help simplify the process of building a user
- interface. It can be used to instantiate objects and set member variables as well as
- define script logic for working with those objects. It is a powerful and efficient way
- to construct a Pivot application.
+ BXML provides a number of features that help simplify the process of building a user
+ interface. It can be used to instantiate objects and set member variables as well as
+ define script logic for working with those objects. It is a powerful and efficient way to
+ construct the user interface of a Pivot application.
</p>
</body>
</document>