You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pivot.apache.org by sm...@apache.org on 2012/01/19 01:51:42 UTC
svn commit: r1233143 [10/47] - in /pivot/site/trunk/deploy: ./ 2.0.1/
2.0.1/docs/ 2.0.1/docs/api/ demos/ tutorials/
Modified: pivot/site/trunk/deploy/tutorials/bxml-primer.html
URL: http://svn.apache.org/viewvc/pivot/site/trunk/deploy/tutorials/bxml-primer.html?rev=1233143&r1=1233142&r2=1233143&view=diff
==============================================================================
--- pivot/site/trunk/deploy/tutorials/bxml-primer.html (original)
+++ pivot/site/trunk/deploy/tutorials/bxml-primer.html Thu Jan 19 00:51:39 2012
@@ -1,4 +1,4 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -14,936 +14,938 @@ distributed under the License is distrib
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
---><html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html; charset=UTF-8" http-equiv="Content-Type" /><title>BXML Primer | Apache Pivot</title><link xmlns="" type="text/css" rel="stylesheet" href="/styles/pivot.css"><script xmlns="http://www.w3.org/1999/xhtml" type="text/javascript">
- var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
- document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
- </script><script type="text/javascript">
- try {
- var pageTracker = _gat._getTracker("UA-7977275-3");
- pageTracker._trackPageview();
- } catch(err) {}</script></head><body><div xmlns="" id="wrapper"><div id="main"><div id="header"><div class="logo"><a href="/index.html"><img title="Apache Pivot Homepage" alt="Apache Pivot" src="/images/logo.png"></a></div><div class="tagline"><img style="visibility:hidden" alt="Rich Internet Applications in Java" src="/images/tagline.png"></div><ul class="navi"><li><a href="/demos/">Demos</a></li><li><a href="/download.cgi#2.0">Download</a></li><li><a href="/tutorials/">Tutorial</a></li><li><a href="/get-involved.html">Get Involved</a></li><li><a href="/about.html">About</a></li></ul></div><div class="group" id="contentBase"><h1>BXML Primer</h1><ul class="naviLeft"><li><a href="/tutorials/sample-application.html">Sample Application</a></li><li><a href="/tutorials/platform-overview.html">Platform Overview</a></li><li><a href="/tutorials/hello-world.html">Hello, World!</a></li><li><a href="/tutorials/hello-bxml.html">Hello, BXML!</a></li><li><a href="/tutorial
s/component-and-container.html">Component & Container</a></li><li><a href="/tutorials/labels-and-image-views.html">Labels & Image Views</a></li><li><a href="/tutorials/svg-images.html">SVG Images</a></li><li><a href="/tutorials/buttons.html">Buttons</a></li><li><a href="/tutorials/push-buttons.html">Push Buttons</a></li><li><a href="/tutorials/toggle-buttons.html">Toggle Buttons</a></li><li><a href="/tutorials/radio-buttons.html">Radio Buttons</a></li><li><a href="/tutorials/checkboxes.html">Checkboxes</a></li><li><a href="/tutorials/link-buttons.html">Link Buttons</a></li><li><a href="/tutorials/lists.html">Lists</a></li><li><a href="/tutorials/list-buttons.html">List Buttons</a></li><li><a href="/tutorials/repeatable-list-buttons.html">Repeatable List Buttons</a></li><li><a href="/tutorials/text.html">Text</a></li><li><a href="/tutorials/suggestion-popups.html">Suggestion Popups</a></li><li><a href="/tutorials/text-areas.html">Text Areas</a></li><li><a href="/tutor
ials/separators.html">Separators</a></li><li><a href="/tutorials/layout-containers.html">Layout Containers</a></li><li><a href="/tutorials/flow-panes.html">Flow Panes</a></li><li><a href="/tutorials/box-panes.html">Box Panes</a></li><li><a href="/tutorials/grid-panes.html">Grid Panes</a></li><li><a href="/tutorials/table-panes.html">Table Panes</a></li><li><a href="/tutorials/borders.html">Borders</a></li><li><a href="/tutorials/stack-panes.html">Stack Panes</a></li><li><a href="/tutorials/split-panes.html">Split Panes</a></li><li><a href="/tutorials/forms.html">Forms</a></li><li><a href="/tutorials/panels.html">Panels</a></li><li><a href="/tutorials/navigation-containers.html">Navigation Containers</a></li><li><a href="/tutorials/card-panes.html">Card Panes</a></li><li><a href="/tutorials/tab-panes.html">Tab Panes</a></li><li><a href="/tutorials/accordions.html">Accordions</a></li><li><a href="/tutorials/expanders.html">Expanders</a></li><li><a href="/tutorials/rollups.html
">Rollups</a></li><li><a href="/tutorials/viewports.html">Viewports</a></li><li><a href="/tutorials/scroll-panes.html">Scroll Panes</a></li><li><a href="/tutorials/panoramas.html">Panoramas</a></li><li><a href="/tutorials/progress-indicators.html">Progress Indicators</a></li><li><a href="/tutorials/meters.html">Meters</a></li><li><a href="/tutorials/activity-indicators.html">Activity Indicators</a></li><li><a href="/tutorials/bounded-range-components.html">Bounded Range Components</a></li><li><a href="/tutorials/sliders.html">Sliders</a></li><li><a href="/tutorials/scroll-bars.html">Scroll Bars</a></li><li><a href="/tutorials/spinners.html">Spinners</a></li><li><a href="/tutorials/calendars.html">Calendars</a></li><li><a href="/tutorials/menus.html">Menus</a></li><li><a href="/tutorials/context-menus.html">Context Menus</a></li><li><a href="/tutorials/menu-bars.html">Menu Bars</a></li><li><a href="/tutorials/menu-buttons.html">Menu Buttons</a></li><li><a href="/tutorials/col
or-choosers.html">Color Choosers</a></li><li><a href="/tutorials/table-views.html">Table Views</a></li><li><a href="/tutorials/table-views.json.html">JSON-based TableView</a></li><li><a href="/tutorials/table-views.custom.html">Custom TableView</a></li><li><a href="/tutorials/tree-views.html">Tree Views</a></li><li><a href="/tutorials/file-browsing.html">File Browsing</a></li><li><a href="/tutorials/windows.html">Windows</a></li><li><a href="/tutorials/clipboard.html">Clipboard</a></li><li><a href="/tutorials/drag-and-drop.html">Drag and Drop</a></li><li><a href="/tutorials/effects.html">Effects</a></li><li><a href="/tutorials/effects.transitions.html">Transitions</a></li><li><a href="/tutorials/data-binding.html">Data Binding</a></li><li><a href="/tutorials/property-binding.html">Property Binding</a></li><li><a href="/tutorials/localization.html">Localization</a></li><li><a href="/tutorials/background-tasks.html">Background Tasks</a></li><li><a href="/tutorials/web-queries.
html">Web Queries</a></li><li><a href="/tutorials/query-servlet.html">QueryServlet</a></li><li><a href="/tutorials/scripting.html">Scripting</a></li><li><a href="/tutorials/summary.html">Summary</a></li><li><a href="/tutorials/stock-tracker.html">The "Stock Tracker" Application</a></li><li><a href="/tutorials/stock-tracker.ui.html">UI Markup Using BXML</a></li><li><a href="/tutorials/stock-tracker.events.html">Event Handling</a></li><li><a href="/tutorials/stock-tracker.web-queries.html">Web Queries</a></li><li><a href="/tutorials/stock-tracker.data-binding.html">Data Binding</a></li><li><a href="/tutorials/stock-tracker.localization.html">Localization</a></li><li><a href="/tutorials/bxml-primer.html">BXML Primer</a></li></ul><div class="content"><style type="text/css">
- applet {
- border: 1px solid #999999;
- }
- </style><!--NOTE: Syntax highlighting script is LGPL--><script src="http://alexgorbatchev.com/pub/sh/current/scripts/shCore.js" type="text/javascript"></script><script src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushJava.js" type="text/javascript"></script><script src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushXml.js" type="text/javascript"></script><script src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushJScript.js" type="text/javascript"></script><link href="http://alexgorbatchev.com/pub/sh/current/styles/shCore.css" rel="stylesheet" type="text/css"><link href="http://alexgorbatchev.com/pub/sh/current/styles/shThemeDefault.css" rel="stylesheet" type="text/css"><script type="text/javascript">
- SyntaxHighlighter.all();
- </script><div class="section">
- <p>
- 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 document introduces the BXML language and explains how it can be used to create and
- configure a collection of Java objects.
- </p>
-
- <h2>BXMLSerializer</h2>
-
- <p>
- 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>
-
- <pre class="brush:java">
-
- 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);
- }
-
- </pre>
-
- <p>
- For example, the following code snippet loads a Window object declared in a file named
- "my_window.bxml":
- </p>
-
- <pre class="brush:java">
-
- BXMLSerializer bxmlSerializer = new BXMLSerializer();
- Window window = (Window)bxmlSerializer.readObject(getClass().getResource("my_window.bxml"));
-
- </pre>
-
- <p>
- <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>
-
- <h2>Namespaces</h2>
-
- <p>
- In BXML, an XML namespace represents a Java package. Declaring a namespace associates the
- namespace prefix with the package, similar to how the import keyword is used in Java.
- </p>
-
- <p>
- For example, the following simple BXML associates the package "com.foo" with the "foo"
- namespace prefix:
- </p>
-
- <pre class="brush:xml">
-
- <foo:Bar xmlns:foo="com.foo"/>
-
- </pre>
-
- <p>
- 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>
-
- <pre class="brush:xml">
-
- <Bar xmlns="com.foo"/>;
-
- </pre>
-
- <p>
- More complex examples may use classes defined in multiple packages; multiple namespace
- prefixes can be used for this purpose.
- </p>
-
- <h3>The "bxml" Namespace</h3>
-
- <p>
- The "bxml" namespace prefix is reserved and defines a number of elements and attributes
- that are used for internal processing. It is generally declared on the root element of a
- BXML document:
- </p>
-
- <pre class="brush:xml">
-
- <Bar xmlns:bxml="http://pivot.apache.org/bxml"
- xmlns="com.foo">
- ...
- </Bar>
-
- </pre>
-
- <p>
- The "bxml" namespace includes the following:
- </p>
-
- <ul>
- <li>
- <p>
- The <tt>bxml:id</tt> attribute, which 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 code that deserializes the file,
- via the <tt>BXMLSerializer#getNamespace()</tt> method:
- </p>
-
- <pre class="brush:xml">
-
- <Foo bxml:id="myFoo"/>
-
- </pre>
- </li>
-
- <li>
- <p>
- The <tt><bxml:include></tt> tag, which 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>
-
- <pre class="brush:xml">
-
- <bxml:include src="my_include.bxml"/>;
-
- </pre>
-
- <p>
- BXML 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). By default, each include is assigned its own variable namespace to
- avoid naming collisions with ancestor documents; however, this behavior can be overridden
- by adding an "inline" attribute with a value of "true" to the <tt><bxml:include></tt>
- tag.
- </p>
- </li>
-
- <li>
- <p>
- The <tt><bxml:script></tt> tag, which defines a block of script code within
- a BXML file. For example, the following script block defines a function named
- <tt>foo()</tt>, which can then be called from other script blocks in the document:
- </p>
-
- <pre class="brush:xml">
-
- <bxml:script>
- function foo() {
- ....
- }
- </bxml:script>
-
- </pre>
-
- <p>
- The default scripting language is JavaScript, but any JVM-compatible scripting language can
- be used. The <tt>language</tt> processing instruction is used to specify a different
- language; for example, Groovy:
- </p>
-
- <pre class="brush:xml">
-
- <?language groovy?>
-
- </pre>
-
- <p>
- Script blocks can also be defined in event handler attributes and elements. Scripting and
- event handling are discussed in more detail below.
- </p>
- </li>
-
- <li>
- <p>
- The <tt><bxml:define></tt> tag, which is used to declare objects that will exist
- outside of the hierarchy but may be referred to elsewhere.
- </p>
-
- <p>
- 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>
-
- <pre class="brush:xml">
-
- <bxml:define>
- <Foo bxml:id="myFoo"/>
- </bxml:define>
-
- </pre>
- </li>
-
- <li>
- <p>
- The <tt><bxml:reference></tt> tag, 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>
-
- <pre class="brush:xml">
-
- <bxml:reference id="myFoo"/>
-
- </pre>
-
- <p>
- Wherever this tag appears, it will effectively be replaced by the value of the "myFoo"
- variable.
- </p>
-
- <p>
- The variable deference operator ("$") can also be used to dereference page variables. This
- is discussed in more detail below.
- </p>
- </li>
- </ul>
-
- <h2>Elements</h2>
- <p>
- In BXML, an XML element that does not begin with the reserved "bxml" namespace prefix
- represents 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 "static" property</p></li>
- </ul>
-
- <p>Each of these is discussed in more detail below.</p>
-
- <h3>Class Instances</h3>
- <p>
- 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, it 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>
- 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>
-
- <pre class="brush:xml">
-
- <Label text="Hello, World!" xmlns="org.apache.pivot.wtk" />
-
- </pre>
-
- <p>
- Class instance elements in a BXML file will often represent instances of Java bean types.
- Internally, <tt>BXMLSerializer</tt> 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>
-
- <p>
- 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>
-
- <pre class="brush:xml">
-
- <HashMap foo="123" bar="456"/>
-
- </pre>
-
- <p>
- How the "foo" and "bar" attributes are handled is discussed in more detail below.
- </p>
-
- <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>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>Property Setters</h4>
- <p>
- If the element represents a property setter, the contents of the element (which must be
- either a text node or a nested 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>
-
- <pre class="brush:xml">
-
- <Label xmlns="org.apache.pivot.wtk">
- <text>Hello, World!</text>
- </Label>
-
- </pre>
-
- <p>
- This produces the same result as the earlier example which used an attribute to set the
- "text" property:
- </p>
-
- <pre class="brush:xml">
-
- <Label text="Hello, World!" xmlns="org.apache.pivot.wtk"/>
-
- </pre>
-
- <p>
- The following 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>:
- </p>
-
- <pre class="brush:xml">
-
- <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>
-
- </pre>
-
- <h4>Read-Only Sequences</h4>
- <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 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>
-
- <pre class="brush:xml">
-
- <TabPane xmlns="org.apache.pivot.wtk">
- <tabs>
- <Label text="Foo"/>
- <Label text="Bar"/>
- </tabs>
- </TabPane>
-
- </pre>
-
- <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 the
- <tt>org.apache.pivot.wtk.Component</tt> class represents a read-only dictionary:
- </p>
-
- <pre class="brush:xml">
-
- <Label text="Hello, World!"
- xmlns="org.apache.pivot.wtk">
- <userData foo="123" bar="456"/>
- </Label>
-
- </pre>
-
- <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.
- </p>
-
- <h4>Default Properties</h4>
- <p>
- 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 actually required:
- </p>
-
- <pre class="brush:xml">
-
- <TabPane xmlns="org.apache.pivot.wtk">
- <Label text="Foo"/>
- <Label text="Bar"/>
- </TabPane>
-
- </pre>
-
- <p>
- Taking advantage of default properties can significantly reduce the verbosity of BXML
- markup.
- </p>
-
- <h3>Static Properties</h3>
-
- <p>
- An element may also 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>
- Static properties are prefixed with the name of class that defines them.
- For example, The following BXML invokes the static setter for the TabPane class's
- "tabData" property:
- </p>
-
- <pre class="brush:xml">
-
- <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>
-
- </pre>
-
- <p>
- This translates roughly to the following in Java:
- </p>
-
- <pre class="brush:java">
-
- 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);
-
- </pre>
-
- <p>
- 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 properties.
- </p>
-
- <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>
-
- <h4>Instance Properties</h4>
-
- <p>
- 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>
-
- <pre class="brush:java">
-
- package com.foo;
-
- public class MyBean {
- public String getFoo() { ... }
- public void setFoo(String foo) { ... }
- public int getBar() { ... }
- public void setBar(int bar) { ... }
- }
-
- </pre>
-
- <p>
- 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>
-
- <pre class="brush:xml">
-
- <MyBean foo="hello" bar="123"/>
-
- </pre>
-
- <p>
- Note that, if the parent element represents an untyped class (a class that implements
- the <tt>Dictionary</tt> interface directly, such as
- <tt>org.apache.pivot.collections.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>
- 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>
-
- <pre class="brush:xml">
-
- <TabPane xmlns:content="org.apache.pivot.wtk.content"
- xmlns="org.apache.pivot.wtk">
- <Label text="Tab 1" TabPane.tabData="First Tab"/>
- </TabPane>
-
- </pre>
-
- <p>
- This translates roughly to the following in Java:
- </p>
-
- <pre class="brush:java">
-
- TabPane tabPane = new TabPane();
-
- Label label = new Label();
- label.setText("Tab 1");
-
- TabPane.setTabData(label, "First Tab");
-
- tabPane.getTabs().add(label);
-
- </pre>
-
- <h4>Event Listeners</h4>
- <p>
- Finally, an attribute may represent an event listener. Event listener attribute values
- contain 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>
-
- <h3>Resolution Operators</h3>
- <p>
- Property setter attributes (either bean or static) in BXML support several resolution
- operators that extend their capabilities:
- </p>
-
- <ul>
- <li><p>Object dereference</p></li>
- <li><p>Resource resolution</p></li>
- <li><p>URL resolution</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.
- </p>
-
- <p>
- For example, a table view header must be associated with an instance of <tt>TableView</tt>;
- 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>
-
- <pre class="brush:xml">
-
- <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>
-
- </pre>
-
- <h4>Resource Resolution</h4>
- <p>
- 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>
-
- <pre class="brush:xml">
-
- <Label text="%myText"/>
-
- </pre>
-
- <p>
- The associated resource file might contain something like the following:
- </p>
-
- <pre class="brush:jscript">
-
- { myText:"This is my text!"
- }
-
- </pre>
-
- <p>
- producing a label containing the text "This is my text!".
- </p>
-
- <h4>URL Resolution</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 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>
-
- <pre class="brush:xml">
-
- <ImageView image="@foo.png"/>
-
- </pre>
-
- <p>
- 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>
- 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>
-
- <p>
- 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>
-
- <pre class="brush:xml">
-
- <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>
-
- </pre>
-
- <p>
- The script could also have been defined in an external file:
- </p>
-
- <pre class="brush:xml">
-
- <Window xmlns:bxml="http://pivot.apache.org/bxml"
- xmlns="org.apache.pivot.wtk">
- <bxml:script src="foo.js"/>
- <Label text="$foo"/>
- </Window>
-
- </pre>
-
- <p>
- 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>
- Script code can also be used to define event handlers in BXML. Event handlers can often be
- defined more succinctly in script than in Java. For example, given the following BXML:
- </p>
-
- <pre class="brush:xml">
-
- <PushButton xmlns="org.apache.pivot.wtk"
- xmlns:bxml="http://pivot.apache.org/bxml"
- bxml:id="pushButton" buttonData="Click Me!"/>
-
- </pre>
-
- <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:
- </p>
-
- <pre class="brush:java">
-
- PushButton pushButton = (PushButton)bxmlSerializer.getNamespace().get("pushButton");
-
- pushButton.getButtonPressListeners().add(new ButtonPressListener() {
- public void buttonPressed(Button button) {
- // Handle event
- }
- });
-
- </pre>
-
- <p>
- While this is simple enough, it can become cumbersome in any non-trivial application
- where many such event are defined. A similar event handler might be defined in JavaScript
- as follows:
- </p>
-
- <pre class="brush:xml">
-
- <PushButton xmlns="org.apache.pivot.wtk"
- xmlns:bxml="http://pivot.apache.org/bxml"
- buttonData="Click Me!">
- <buttonPressListeners>
- function buttonPressed(button) {
- // Handle event
- }
- </buttonPressListeners>
- </PushButton>
-
- </pre>
-
- <p>
- 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>
-
- <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. However, the script code can still see and access global variables
- declared elsewhere in the page. This is somewhat analogous to defining an anonymous inner
- class as a listener in Java.
- </p>
-
- <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.
- </p>
-
- <h3>Event Listener Attributes</h3>
- <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.
- </p>
-
- <p>
- For example, the above button press listener can be declared in an attribute as follows:
- </p>
-
- <pre class="brush:xml">
-
- <PushButton xmlns="org.apache.pivot.wtk"
- xmlns:bxml="http://pivot.apache.org/bxml"
- buttonData="Click Me!"
- ButtonPressListener.buttonPressed="handleEvent(arguments[0])"/>
-
- </pre>
-
- <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.
- </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, implementation in a Java or
- other compiled language.
- </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>
-
- <pre class="brush:java">
-
- 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);
- }
-
- </pre>
-
- <p>
- <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>org.apache.pivot.beans.Bindable</tt> interface can be used to simplify integration
- between BXML markup and compiled code. <tt>Bindable</tt> defines a single method,
- <tt>initialize()</tt>, that is called on the root element of a BXML document once the
- document has been completely loaded. It 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>
- 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>
- 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>
-
- <pre class="brush:xml">
-
- <Window xmlns="org.apache.pivot.wtk"
- xmlns:bxml="http://pivot.apache.org/bxml">
- <Label bxml:id="label" text="Hello, World!"/>
- <Window>
-
- </pre>
-
- <p>
- 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>
-
- <pre class="brush:java">
-
- @BXML private Label label;
-
- </pre>
-
- <p>
- 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 access named objects
- defined in a BXML file.
- </p>
-
- <h2>Summary</h2>
- <p>
- 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>
- </div></div></div></div><div class="group" id="footer"><div class="footerLogo">Copyright (c) 1999-2011<br>The Apache Software Foundation.</div><div class="footerLinks"><ul class="footerMenuGr"><li><strong>Demos</strong><ul><li><a href="/demos/kitchen-sink.html" target="_new">"Kitchen Sink"</a></li><li><a href="/demos/component-explorer.html" target="_new">Component Explorer</a></li><li><a href="http://ixnay.biz/pivot-jfree-demos/charts_demo.html" target="_new">Charting</a></li><li><a href="/demos/">More Demos</a></li></ul></li><li><strong>Documentation</strong><ul><li><a href="/getting-started.html">Getting Started</a></li><li><a href="/tutorials/">Tutorial</a></li><li><a href="/faq.html">FAQ</a></li><li><a href="/2.0/docs/api/">Javadoc (2.0)</a></li></ul></li><li><strong>Get Involved</strong><ul><li><a href="/svn.html">SVN Repositories</a></li><li><a href="/lists.html">Mailing Lists</a></li><li><a href="http://issues.apache.org/jira/browse/PIVOT">Bug Database</a></li><l
i><a href="http://cwiki.apache.org/PIVOT/">Wiki</a></li></ul></li><li><strong>Related</strong><ul><li><a href="http://code.google.com/p/pivot-jfree/">JFreeChart Provider</a></li></ul></li><li><strong>About</strong><ul><li><a href="/who-we-are.html">Who We Are</a></li><li><a href="/contact.html">Contact</a></li><li><a href="/news.html">News</a></li><li><a href="/legal.html">Legal/License</a></li></ul></li></ul></div></div></div></body></html>
\ No newline at end of file
+--><html xmlns="http://www.w3.org/1999/xhtml"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>BXML Primer | Apache Pivot</title><link href="/styles/pivot.css" rel="stylesheet" type="text/css"><script type="text/javascript">
+ var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+ document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+ </script><script type="text/javascript">
+ try {
+ var pageTracker = _gat._getTracker("UA-7977275-3");
+ pageTracker._trackPageview();
+ } catch(err) {}</script></head><body><div id="wrapper"><div id="main"><div id="header"><div xmlns="" class="logo"><a href="/index.html"><img src="/images/logo.png" alt="Apache Pivot" title="Apache Pivot Homepage"></a></div><div class="tagline"><img src="/images/tagline.png" alt="Rich Internet Applications in Java" style="visibility:hidden"></div><ul class="navi"><li><a href="/demos/">Demos</a></li><li><a href="/download.cgi#2.0.1">Download</a></li><li><a href="/tutorials/">Tutorial</a></li><li><a href="/get-involved.html">Get Involved</a></li><li><a href="/about.html">About</a></li></ul></div><div id="contentBase" class="group"><h1>BXML Primer</h1><ul class="naviLeft"><li><a href="/tutorials/sample-application.html">Sample Application</a></li><li><a href="/tutorials/platform-overview.html">Platform Overview</a></li><li><a href="/tutorials/hello-world.html">Hello, World!</a></li><li><a href="/tutorials/hello-bxml.html">Hello, BXML!</a></li><li><a href="/tutori
als/component-and-container.html">Component & Container</a></li><li><a href="/tutorials/labels-and-image-views.html">Labels & Image Views</a></li><li><a href="/tutorials/svg-images.html">SVG Images</a></li><li><a href="/tutorials/buttons.html">Buttons</a></li><li><a href="/tutorials/push-buttons.html">Push Buttons</a></li><li><a href="/tutorials/toggle-buttons.html">Toggle Buttons</a></li><li><a href="/tutorials/radio-buttons.html">Radio Buttons</a></li><li><a href="/tutorials/checkboxes.html">Checkboxes</a></li><li><a href="/tutorials/link-buttons.html">Link Buttons</a></li><li><a href="/tutorials/lists.html">Lists</a></li><li><a href="/tutorials/list-buttons.html">List Buttons</a></li><li><a href="/tutorials/repeatable-list-buttons.html">Repeatable List Buttons</a></li><li><a href="/tutorials/text.html">Text</a></li><li><a href="/tutorials/suggestion-popups.html">Suggestion Popups</a></li><li><a href="/tutorials/text-areas.html">Text Areas</a></li><li><a href="/tut
orials/separators.html">Separators</a></li><li><a href="/tutorials/layout-containers.html">Layout Containers</a></li><li><a href="/tutorials/flow-panes.html">Flow Panes</a></li><li><a href="/tutorials/box-panes.html">Box Panes</a></li><li><a href="/tutorials/fill-panes.html">Fill Panes</a></li><li><a href="/tutorials/grid-panes.html">Grid Panes</a></li><li><a href="/tutorials/table-panes.html">Table Panes</a></li><li><a href="/tutorials/borders.html">Borders</a></li><li><a href="/tutorials/stack-panes.html">Stack Panes</a></li><li><a href="/tutorials/split-panes.html">Split Panes</a></li><li><a href="/tutorials/forms.html">Forms</a></li><li><a href="/tutorials/panels.html">Panels</a></li><li><a href="/tutorials/navigation-containers.html">Navigation Containers</a></li><li><a href="/tutorials/card-panes.html">Card Panes</a></li><li><a href="/tutorials/tab-panes.html">Tab Panes</a></li><li><a href="/tutorials/accordions.html">Accordions</a></li><li><a href="/tutorials/expander
s.html">Expanders</a></li><li><a href="/tutorials/rollups.html">Rollups</a></li><li><a href="/tutorials/viewports.html">Viewports</a></li><li><a href="/tutorials/scroll-panes.html">Scroll Panes</a></li><li><a href="/tutorials/panoramas.html">Panoramas</a></li><li><a href="/tutorials/progress-indicators.html">Progress Indicators</a></li><li><a href="/tutorials/meters.html">Meters</a></li><li><a href="/tutorials/activity-indicators.html">Activity Indicators</a></li><li><a href="/tutorials/bounded-range-components.html">Bounded Range Components</a></li><li><a href="/tutorials/sliders.html">Sliders</a></li><li><a href="/tutorials/scroll-bars.html">Scroll Bars</a></li><li><a href="/tutorials/spinners.html">Spinners</a></li><li><a href="/tutorials/calendars.html">Calendars</a></li><li><a href="/tutorials/menus.html">Menus</a></li><li><a href="/tutorials/context-menus.html">Context Menus</a></li><li><a href="/tutorials/menu-bars.html">Menu Bars</a></li><li><a href="/tutorials/menu-
buttons.html">Menu Buttons</a></li><li><a href="/tutorials/color-choosers.html">Color Choosers</a></li><li><a href="/tutorials/table-views.html">Table Views</a></li><li><a href="/tutorials/table-views.json.html">JSON-based TableView</a></li><li><a href="/tutorials/table-views.custom.html">Custom TableView</a></li><li><a href="/tutorials/tree-views.html">Tree Views</a></li><li><a href="/tutorials/file-browsing.html">File Browsing</a></li><li><a href="/tutorials/windows.html">Windows</a></li><li><a href="/tutorials/clipboard.html">Clipboard</a></li><li><a href="/tutorials/drag-and-drop.html">Drag and Drop</a></li><li><a href="/tutorials/effects.html">Effects</a></li><li><a href="/tutorials/effects.transitions.html">Transitions</a></li><li><a href="/tutorials/data-binding.html">Data Binding</a></li><li><a href="/tutorials/property-binding.html">Property Binding</a></li><li><a href="/tutorials/localization.html">Localization</a></li><li><a href="/tutorials/background-tasks.html"
>Background Tasks</a></li><li><a href="/tutorials/web-queries.html">Web Queries</a></li><li><a href="/tutorials/query-servlet.html">QueryServlet</a></li><li><a href="/tutorials/scripting.html">Scripting</a></li><li><a href="/tutorials/summary.html">Summary</a></li><li><a href="/tutorials/stock-tracker.html">The "Stock Tracker" Application</a></li><li><a href="/tutorials/stock-tracker.ui.html">UI Markup Using BXML</a></li><li><a href="/tutorials/stock-tracker.events.html">Event Handling</a></li><li><a href="/tutorials/stock-tracker.web-queries.html">Web Queries</a></li><li><a href="/tutorials/stock-tracker.data-binding.html">Data Binding</a></li><li><a href="/tutorials/stock-tracker.localization.html">Localization</a></li><li><a href="/tutorials/bxml-primer.html">BXML Primer</a></li></ul><div class="content"><style type="text/css">
+ applet {
+ border: 1px solid #999999;
+ }
+ </style><!--NOTE: Syntax highlighting script is LGPL--><script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shCore.js"></script><script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushJava.js"></script><script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushXml.js"></script><script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushJScript.js"></script><link type="text/css" rel="stylesheet" href="http://alexgorbatchev.com/pub/sh/current/styles/shCore.css"><link type="text/css" rel="stylesheet" href="http://alexgorbatchev.com/pub/sh/current/styles/shThemeDefault.css"><script type="text/javascript">
+ SyntaxHighlighter.all();
+ </script><div class="section">
+ <p>
+ 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 document introduces the BXML language and explains how it can be used to create and
+ configure a collection of Java objects.
+ </p>
+
+ <h3>BXMLSerializer</h3>
+
+ <p>
+ 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>
+
+ <pre class="brush:java">
+
+ 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);
+ }
+
+ </pre>
+
+ <p>
+ For example, the following code snippet loads a Window object declared in a file named
+ "my_window.bxml":
+ </p>
+
+ <pre class="brush:java">
+
+ BXMLSerializer bxmlSerializer = new BXMLSerializer();
+ Window window = (Window)bxmlSerializer.readObject(getClass().getResource("my_window.bxml"));
+
+ </pre>
+
+ <p>
+ <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>
+
+ <h3>Namespaces</h3>
+
+ <p>
+ In BXML, an XML namespace represents a Java package. Declaring a namespace associates the
+ namespace prefix with the package, similar to how the import keyword is used in Java.
+ </p>
+
+ <p>
+ For example, the following simple BXML associates the package "com.foo" with the "foo"
+ namespace prefix:
+ </p>
+
+ <pre class="brush:xml">
+
+ <foo:Bar xmlns:foo="com.foo"/>
+
+ </pre>
+
+ <p>
+ 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>
+
+ <pre class="brush:xml">
+
+ <Bar xmlns="com.foo"/>;
+
+ </pre>
+
+ <p>
+ More complex examples may use classes defined in multiple packages; multiple namespace
+ prefixes can be used for this purpose.
+ </p>
+
+ <h3>The "bxml" Namespace</h3>
+
+ <p>
+ The "bxml" namespace prefix is reserved and defines a number of elements and attributes
+ that are used for internal processing. It is generally declared on the root element of a
+ BXML document:
+ </p>
+
+ <pre class="brush:xml">
+
+ <Bar xmlns:bxml="http://pivot.apache.org/bxml"
+ xmlns="com.foo">
+ ...
+ </Bar>
+
+ </pre>
+
+ <p>
+ The "bxml" namespace includes the following:
+ </p>
+
+ <ul>
+ <li>
+ <p>
+ The <tt>bxml:id</tt> attribute, which 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 code that deserializes the file,
+ via the <tt>BXMLSerializer#getNamespace()</tt> method:
+ </p>
+
+ <pre class="brush:xml">
+
+ <Foo bxml:id="myFoo"/>
+
+ </pre>
+ </li>
+
+ <li>
+ <p>
+ The <tt><bxml:include></tt> tag, which 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>
+
+ <pre class="brush:xml">
+
+ <bxml:include src="my_include.bxml"/>;
+
+ </pre>
+
+ <p>
+ BXML 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). By default, each include is assigned its own variable namespace to
+ avoid naming collisions with ancestor documents; however, this behavior can be overridden
+ by adding an "inline" attribute with a value of "true" to the <tt><bxml:include></tt>
+ tag.
+ </p>
+ </li>
+
+ <li>
+ <p>
+ The <tt><bxml:script></tt> tag, which defines a block of script code within
+ a BXML file. For example, the following script block defines a function named
+ <tt>foo()</tt>, which can then be called from other script blocks in the document:
+ </p>
+
+ <pre class="brush:xml">
+
+ <bxml:script>
+ function foo() {
+ ....
+ }
+ </bxml:script>
+
+ </pre>
+
+ <p>
+ The default scripting language is JavaScript, but any JVM-compatible scripting language can
+ be used. The <tt>language</tt> processing instruction is used to specify a different
+ language; for example, Groovy:
+ </p>
+
+ <pre class="brush:xml">
+
+ <?language groovy?>
+
+ </pre>
+
+ <p>
+ Script blocks can also be defined in event handler attributes and elements. Scripting and
+ event handling are discussed in more detail below.
+ </p>
+ </li>
+
+ <li>
+ <p>
+ The <tt><bxml:define></tt> tag, which is used to declare objects that will exist
+ outside of the hierarchy but may be referred to elsewhere.
+ </p>
+
+ <p>
+ 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>
+
+ <pre class="brush:xml">
+
+ <bxml:define>
+ <Foo bxml:id="myFoo"/>
+ </bxml:define>
+
+ </pre>
+ </li>
+
+ <li>
+ <p>
+ The <tt><bxml:reference></tt> tag, 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>
+
+ <pre class="brush:xml">
+
+ <bxml:reference id="myFoo"/>
+
+ </pre>
+
+ <p>
+ Wherever this tag appears, it will effectively be replaced by the value of the "myFoo"
+ variable.
+ </p>
+
+ <p>
+ The variable deference operator ("$") can also be used to dereference page variables. This
+ is discussed in more detail below.
+ </p>
+ </li>
+ </ul>
+
+ <h3>Elements</h3>
+ <p>
+ In BXML, an XML element that does not begin with the reserved "bxml" namespace prefix
+ represents 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 "static" property</p></li>
+ </ul>
+
+ <p>Each of these is discussed in more detail below.</p>
+
+ <h3>Class Instances</h3>
+ <p>
+ 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, it 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>
+ 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>
+
+ <pre class="brush:xml">
+
+ <Label text="Hello, World!" xmlns="org.apache.pivot.wtk" />
+
+ </pre>
+
+ <p>
+ Class instance elements in a BXML file will often represent instances of Java bean types.
+ Internally, <tt>BXMLSerializer</tt> 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>
+
+ <p>
+ 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>
+
+ <pre class="brush:xml">
+
+ <HashMap foo="123" bar="456"/>
+
+ </pre>
+
+ <p>
+ How the "foo" and "bar" attributes are handled is discussed in more detail below.
+ </p>
+
+ <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>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>Property Setters</h4>
+ <p>
+ If the element represents a property setter, the contents of the element (which must be
+ either a text node or a nested 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>
+
+ <pre class="brush:xml">
+
+ <Label xmlns="org.apache.pivot.wtk">
+ <text>Hello, World!</text>
+ </Label>
+
+ </pre>
+
+ <p>
+ This produces the same result as the earlier example which used an attribute to set the
+ "text" property:
+ </p>
+
+ <pre class="brush:xml">
+
+ <Label text="Hello, World!" xmlns="org.apache.pivot.wtk"/>
+
+ </pre>
+
+ <p>
+ The following 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>:
+ </p>
+
+ <pre class="brush:xml">
+
+ <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>
+
+ </pre>
+
+ <h4>Read-Only Sequences</h4>
+ <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 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>
+
+ <pre class="brush:xml">
+
+ <TabPane xmlns="org.apache.pivot.wtk">
+ <tabs>
+ <Label text="Foo"/>
+ <Label text="Bar"/>
+ </tabs>
+ </TabPane>
+
+ </pre>
+
+ <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 the
+ <tt>org.apache.pivot.wtk.Component</tt> class represents a read-only dictionary:
+ </p>
+
+ <pre class="brush:xml">
+
+ <Label text="Hello, World!"
+ xmlns="org.apache.pivot.wtk">
+ <userData foo="123" bar="456"/>
+ </Label>
+
+ </pre>
+
+ <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.
+ </p>
+
+ <h4>Default Properties</h4>
+ <p>
+ 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 actually required:
+ </p>
+
+ <pre class="brush:xml">
+
+ <TabPane xmlns="org.apache.pivot.wtk">
+ <Label text="Foo"/>
+ <Label text="Bar"/>
+ </TabPane>
+
+ </pre>
+
+ <p>
+ Taking advantage of default properties can significantly reduce the verbosity of BXML
+ markup.
+ </p>
+
+ <h3>Static Properties</h3>
+
+ <p>
+ An element may also 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>
+ Static properties are prefixed with the name of class that defines them.
+ For example, The following BXML invokes the static setter for the TabPane class's
+ "tabData" property:
+ </p>
+
+ <pre class="brush:xml">
+
+ <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>
+
+ </pre>
+
+ <p>
+ This translates roughly to the following in Java:
+ </p>
+
+ <pre class="brush:java">
+
+ 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);
+
+ </pre>
+
+ <p>
+ 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 properties.
+ </p>
+
+ <h3>Attributes</h3>
+ <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>
+
+ <h4>Instance Properties</h4>
+
+ <p>
+ 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>
+
+ <pre class="brush:java">
+
+ package com.foo;
+
+ public class MyBean {
+ public String getFoo() { ... }
+ public void setFoo(String foo) { ... }
+ public int getBar() { ... }
+ public void setBar(int bar) { ... }
+ }
+
+ </pre>
+
+ <p>
+ 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>
+
+ <pre class="brush:xml">
+
+ <MyBean foo="hello" bar="123"/>
+
+ </pre>
+
+ <p>
+ Note that, if the parent element represents an untyped class (a class that implements
+ the <tt>Dictionary</tt> interface directly, such as
+ <tt>org.apache.pivot.collections.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>
+ 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>
+
+ <pre class="brush:xml">
+
+ <TabPane xmlns:content="org.apache.pivot.wtk.content"
+ xmlns="org.apache.pivot.wtk">
+ <Label text="Tab 1" TabPane.tabData="First Tab"/>
+ </TabPane>
+
+ </pre>
+
+ <p>
+ This translates roughly to the following in Java:
+ </p>
+
+ <pre class="brush:java">
+
+ TabPane tabPane = new TabPane();
+
+ Label label = new Label();
+ label.setText("Tab 1");
+
+ TabPane.setTabData(label, "First Tab");
+
+ tabPane.getTabs().add(label);
+
+ </pre>
+
+ <h4>Event Listeners</h4>
+ <p>
+ Finally, an attribute may represent an event listener. Event listener attribute values
+ contain 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>
+
+ <h3>Resolution Operators</h3>
+ <p>
+ Property setter attributes (either bean or static) in BXML support several resolution
+ operators that extend their capabilities:
+ </p>
+
+ <ul>
+ <li><p>Object dereference</p></li>
+ <li><p>Resource resolution</p></li>
+ <li><p>URL resolution</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.
+ </p>
+
+ <p>
+ For example, a table view header must be associated with an instance of <tt>TableView</tt>;
+ 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>
+
+ <pre class="brush:xml">
+
+ <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>
+
+ </pre>
+
+ <h4>Resource Resolution</h4>
+ <p>
+ 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>
+
+ <pre class="brush:xml">
+
+ <Label text="%myText"/>
+
+ </pre>
+
+ <p>
+ The associated resource file might contain something like the following:
+ </p>
+
+ <pre class="brush:jscript">
+
+ { myText:"This is my text!"
+ }
+
+ </pre>
+
+ <p>
+ producing a label containing the text "This is my text!".
+ </p>
+
+ <h4>URL Resolution</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 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>
+
+ <pre class="brush:xml">
+
+ <ImageView image="@foo.png"/>
+
+ </pre>
+
+ <p>
+ Without the "@" operator, bean properties would have no context by which to determine the
+ path to such a resource.
+ </p>
+
+ <h3><a name="scripting">Scripting</a></h3>
+ <p>
+ 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>
+
+ <p>
+ 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>
+
+ <pre class="brush:xml">
+
+ <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>
+
+ </pre>
+
+ <p>
+ The script could also have been defined in an external file:
+ </p>
+
+ <pre class="brush:xml">
+
+ <Window xmlns:bxml="http://pivot.apache.org/bxml"
+ xmlns="org.apache.pivot.wtk">
+ <bxml:script src="foo.js"/>
+ <Label text="$foo"/>
+ </Window>
+
+ </pre>
+
+ <p>
+ 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>
+ Script code can also be used to define event handlers in BXML. Event handlers can often be
+ defined more succinctly in script than in Java. For example, given the following BXML:
+ </p>
+
+ <pre class="brush:xml">
+
+ <PushButton xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml"
+ bxml:id="pushButton" buttonData="Click Me!"/>
+
+ </pre>
+
+ <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:
+ </p>
+
+ <pre class="brush:java">
+
+ PushButton pushButton = (PushButton)bxmlSerializer.getNamespace().get("pushButton");
+
+ pushButton.getButtonPressListeners().add(new ButtonPressListener() {
+ public void buttonPressed(Button button) {
+ // Handle event
+ }
+ });
+
+ </pre>
+
+ <p>
+ While this is simple enough, it can become cumbersome in any non-trivial application
+ where many such event are defined. A similar event handler might be defined in JavaScript
+ as follows:
+ </p>
+
+ <pre class="brush:xml">
+
+ <PushButton xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml"
+ buttonData="Click Me!">
+ <buttonPressListeners>
+ function buttonPressed(button) {
+ // Handle event
+ }
+ </buttonPressListeners>
+ </PushButton>
+
+ </pre>
+
+ <p>
+ 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>
+
+ <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. However, the script code can still see and access global variables
+ declared elsewhere in the page. This is somewhat analogous to defining an anonymous inner
+ class as a listener in Java.
+ </p>
+
+ <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.
+ </p>
+
+ <h3>Event Listener Attributes</h3>
+ <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.
+ </p>
+
+ <p>
+ For example, the above button press listener can be declared in an attribute as follows:
+ </p>
+
+ <pre class="brush:xml">
+
+ <PushButton xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml"
+ buttonData="Click Me!"
+ ButtonPressListener.buttonPressed="handleEvent(arguments[0])"/>
+
+ </pre>
+
+ <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.
+ </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, implementation in a Java or
+ other compiled language.
+ </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>
+
+ <pre class="brush:java">
+
+ 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);
+ }
+
+ </pre>
+
+ <p>
+ <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>org.apache.pivot.beans.Bindable</tt> interface can be used to simplify integration
+ between BXML markup and compiled code. <tt>Bindable</tt> defines a single method,
+ <tt>initialize()</tt>, that is called on the root element of a BXML document once the
+ document has been completely loaded. It 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>
+ 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>
+ 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>
+
+ <pre class="brush:xml">
+
+ <Window xmlns="org.apache.pivot.wtk"
+ xmlns:bxml="http://pivot.apache.org/bxml">
+ <Label bxml:id="label" text="Hello, World!"/>
+ <Window>
+
+ </pre>
+
+ <p>
+ 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>
+
+ <pre class="brush:java">
+
+ @BXML private Label label;
+
+ </pre>
+
+ <p>
+ 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 access named objects
+ defined in a BXML file.
+ </p>
+
+ <h3>Summary</h3>
+ <p>
+ 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>
+ </div></div></div></div><div id="footer" class="group"><div class="footerLogo">Copyright (c) 1999-2012<br>The Apache Software Foundation.</div><div class="footerLinks"><ul class="footerMenuGr"><li><strong>Demos</strong><ul><li><a href="/demos/kitchen-sink.html" target="_new">"Kitchen Sink"</a></li><li><a href="/demos/component-explorer.html" target="_new">Component Explorer</a></li><li><a href="http://cwiki.apache.org/confluence/display/PIVOT/Other+Demos" target="_new">Charting</a></li><li><a href="/demos/">More Demos</a></li></ul></li><li><strong>Documentation</strong><ul><li><a href="/getting-started.html">Getting Started</a></li><li><a href="/tutorials/">Tutorial</a></li><li><a href="/faq.html">FAQ</a></li><li><a href="/2.0.1/docs/api/">Javadoc (2.0.1)</a></li></ul></li><li><strong>Get Involved</strong><ul><li><a href="/svn.html">SVN Repositories</a></li><li><a href="/lists.html">Mailing Lists</a></li><li><a href="http://issues.apache.org/jira/browse/PIVOT">Bug Databa
se</a></li><li><a href="http://cwiki.apache.org/PIVOT/">Wiki</a></li></ul></li><li><strong>Related</strong><ul><li><a href="http://code.google.com/a/apache-extras.org/p/pivot-jfree/">JFreeChart Provider</a></li><li><a href="http://code.google.com/a/apache-extras.org/p/pivot-common/">Pivot-Common</a></li><li><a href="http://code.google.com/a/apache-extras.org/p/pivot-contrib/">Pivot-Contrib</a></li><li><a href="http://code.google.com/a/apache-extras.org/p/pivot-multilang/">Pivot-Multilang</a></li></ul></li><li><strong>About</strong><ul><li><a href="/who-we-are.html">Who We Are</a></li><li><a href="/contact.html">Contact</a></li><li><a href="http://cwiki.apache.org/confluence/display/PIVOT/News">News</a></li><li><a href="/legal.html">Legal/License</a></li></ul></li></ul></div><div class="footerLinks">
+ Apache Pivot is a trademark of the Apache Software Foundation
+ </div></div></div></body></html>
\ No newline at end of file