| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| |
| <html> |
| <link href="../../book.css" rel="stylesheet" type="text/css" /> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <title>Markup-language</title> |
| </head> |
| |
| <body> |
| <h1>Markup language</h1> |
| <p>Markup languages are designed for the processing, definition and |
| presentation of text. XWT provides an Extensible UI Markup Language for |
| declarative Eclipse application programming.</p> |
| |
| <ul> |
| <li><a href="#language_01">A Declarative language with Flow |
| Control Support</a></li> |
| <li><a href="#language_02">XWT Object Elements</a></li> |
| <li><a href="#language_03">Setting Properties</a></li> |
| <li><a href="#language_06">Reference Values and Markup |
| Extensions</li> |
| <li><a href="#language_07">Case and Whitespace</a></li> |
| |
| <li><a href="#language_04">XWT Root Elements and XML |
| Namespaces</a></li> |
| <li><a href="#language_05">Events and XWT Code-behind</a></li> |
| </ul> |
| |
| |
| <h3><a name="language_01"></a>A Declarative language with Flow |
| Control Support</h3> |
| <p>XWT simplifies creating a UI for Java programming. You can create |
| visible UI elements in the XWT declarative markup, and then separate the |
| UI definition from the run-time logic by using code-behind files. The |
| ability to mix code with markup in XWT is important because XML by |
| itself is declarative, and does not really suggest a model for flow |
| control.</p> |
| |
| <p>The following XWT example shows how markup is necessary to create |
| a button as part of a UI.</p> |
| |
| <pre> |
| <span class="XMLElementTag"><Shell.layout></span> |
| <span class="XMLElementTag"><GridLayout</span> <span |
| class="XMLAttrTag">numColumns</span>=<span class="XMLAttrValue">"1"</span> <span |
| class="XMLElementTag">/></span> |
| <span class="XMLElementTag"></Shell.layout></span> |
| <span class="XMLElementTag"><Button</span> <span class="XMLAttrTag">text</span>=<span |
| class="XMLAttrValue">"Hello"</span> <span class="XMLElementTag">/></span> |
| </pre> |
| |
| <h3><a name="language_02"></a> XWT Object Elements</h3> |
| <p>XWT has a set of rules that map object elements into classes or |
| structures, attributes into properties or events, and XML namespaces to |
| Java packages.</p> |
| |
| <p>The preceding example specified two object elements: <span |
| class="XMLElementTag"><GridLayout /></span> and <span |
| class="XMLElementTag"><Button /></span>. The string <span |
| class="XMLElementTag">GridLayout</span> and <span class="XMLElementTag">Button</span> |
| each map to the name of a class that is defined by XWT and is part of |
| the XWT assemblies. When you specify an object element tag, you create |
| an instruction for XWT processing to create a new instance of the named |
| class when your XWT page is loaded. Each instance is created by calling |
| the default constructor of the underlying class or structure and storing |
| the result. To be usable as an object element in XWT, the class or |
| structure must expose a public default (parameterless) constructor.</p> |
| |
| <h3><a name="language_03"></a>Setting Properties</h3> |
| <p>Properties in XWT are set by setting properties on an object |
| element, using a variety of possible syntaxes. Which syntaxes can be |
| used for a given property will vary, based on the characteristics of the |
| property that you are setting.</p> |
| |
| <p>By setting values of properties, you add features or |
| characteristics to object element. The initial state of the underlying |
| object instance for an object element is based on the default |
| constructor behavior. Typically, your application will use something |
| other than a completely default instance of any given object.</p> |
| |
| <p><b>Attribute Syntax</b></p> |
| |
| <p>In XWT, properties can often be expressed as attributes. |
| Attribute syntax is the most streamlined property setting syntax and |
| will be the most intuitive syntax to use for developers that have used |
| markup languages in the past. For example, the following markup creates |
| a button that with push style, as well as display text specified as <span |
| class="XMLAttrTag">test</span>.</p> |
| |
| <pre> |
| <span class="XMLElementTag"><Button</span> <span class="XMLAttrTag">x:style</span>=<span |
| class="XMLAttrValue">"PUSH"</span> <span class="XMLAttrTag">text</span>=<span |
| class="XMLAttrValue">"Hello, world!"</span> <span class="XMLElementTag">/></span> |
| </pre> |
| |
| |
| <p><b>Property Element Syntax</b></p> |
| <p>For some properties of an object element, attribute syntax is not |
| possible, because the object or information necessary to provide the |
| property value cannot be adequately expressed as a simple string. For |
| these cases, a different syntax known as property element syntax can be |
| used. Property element syntax sets the referenced property of the |
| containing element with the content of the tag. Generally, the content |
| is an object of the type that the property takes as its value. The |
| syntax for property element itself is <TypeName.Property>. After |
| specifying content, you must close the property element with a closing |
| tag just like any other element (with syntax |
| </TypeName.Property>). For properties where both attribute and |
| property element syntax are supported, the two syntaxes generally have |
| the same result, although subtleties such as whitespace handling can |
| vary slightly between syntaxes. The following example is using property |
| element syntax for <span class="XMLAttrTag">text</span> properties of |
| the Button.</p> |
| |
| |
| <pre> |
| <span class="XMLElementTag"><Button></span> |
| <span class="XMLElementTag"><Button.text></span> |
| This is a Button |
| <span class="XMLElementTag"></Button.text></span> |
| <span class="XMLElementTag"></Button></span> |
| </pre> |
| |
| <h3><a name="language_06"></a>Reference Values and Markup |
| Extensions</h3> |
| <p>Markup extensions are an XWT concept. In attribute syntax, curly |
| braces ({ and }) indicate a markup extension usage. This usage directs |
| the XWT processing to escape from the general treatment of attribute |
| values are either a literal string or directly string-convertible value.</p> |
| |
| <p>When properties take a reference type value, these properties |
| will often require either property element syntax (which always creates |
| a new instance) or an object reference through a markup extension. A |
| markup extension usage can potentially return an existing instance, and |
| thus can be more versatile or might incur less object overhead.</p> |
| |
| <p>When a markup extension is used to provide an attribute value, |
| the attribute value should instead be provided by the logic within the |
| backing class for the relevant markup extension. The most common markup |
| extensions used in XWT application programming are <b>Binding</b>, used |
| for data binding expressions and the resource reference <b>StaticResource</b> |
| and <b>DynamicResource</b>. By using markup extension, you can use |
| attribute syntax to provide reference values for properties even if that |
| the property does not support an attribute syntax for direct object |
| instantiation, or enable specific behavior that defers the general |
| behavior of the requirement that XAML properties must be filled by |
| values of the property's type.</p> |
| |
| <p>For instance, the following example sets the value of text |
| property using attribute syntax. The text binds a Person class.</p> |
| |
| |
| <pre> |
| <span class="XMLElementTag"><Shell</span> |
| ... |
| <span class="XMLAttrTag">DataContext</span>=<span |
| class="XMLAttrValue">"{StaticResource myData}"</span><span |
| class="XMLElementTag">></span> |
| ... |
| <span class="XMLElementTag"><x:Shell.Resources></span> |
| <span |
| class="XMLElementTag"><y:Person</span> <span class="XMLAttrTag">x:Key</span>=<span |
| class="XMLAttrValue">"myData"</span><span class="XMLElementTag">/></span> |
| <span class="XMLElementTag"></x:Shell.Resources></span> |
| |
| <span class="XMLElementTag"><Text</span> <span |
| class="XMLAttrTag">x:style</span>=<span class="XMLAttrValue">"BORDER"</span> <span |
| class="XMLAttrTag">text</span>=<span class="XMLAttrValue">"{Binding Path=name}"</span><span |
| class="XMLElementTag">></span> |
| <span |
| class="XMLElementTag"><Text.layoutData></span> |
| <span |
| class="XMLElementTag"><GridData</span> <span class="XMLAttrTag">horizontalAlignment</span>=<span |
| class="XMLAttrValue">"FILL"</span> |
| <span |
| class="XMLAttrTag">grabExcessHorizontalSpace</span>=<span |
| class="XMLAttrValue">"true"</span><span class="XMLElementTag">/></span> |
| <span |
| class="XMLElementTag"></Text.layoutData></span> |
| <span class="XMLElementTag"></Text></span> |
| ... |
| <span class="XMLElementTag"></Shell></span> |
| </pre> |
| |
| <h3><a name="language_07"></a>Case and Whitespace</h3> |
| <p>XWT is in general case sensitive. Object elements and property elements must all be specified by using the proper case when |
| compared by name to the underlying type in programming language, or to a member |
| of a type. There is one exception for attribute name. The first letter and only the first letter of attribute name is not case-sensitive.</p> |
| |
| <p>The values for attributes are not always case sensitive. Case |
| sensitivity for values will depend on the type converter behavior |
| associated with the property that takes the value, or the property value |
| type. For instance, properties that take Boolean type can take |
| either true or True as equivalent values, but only because the default |
| string type conversion for Boolean already permits these as equivalents. |
| </p> |
| |
| <p>XWT processors and serializers will ignore or drop all |
| non-significant whitespace, and will normalize any significant |
| whitespace. This behavior is generally only of consequence when you |
| specify strings within XWT content properties. In simplest terms, XWT |
| converts space, line feed and tab characters into spaces and then |
| preserves one space if found at either end of a contiguous string.</p> |
| |
| <h3><a name="language_04"></a>XWT Root Elements and XML Namespaces</h3> |
| <p>An XWT file must have only one root element, in order to be both a |
| well-formed XML file and a valid XWT file. Typically you should choose |
| an element that is part of the application model. The following example |
| shows the root element of a typical XWT file with the root element |
| Composite.</p> |
| |
| |
| <pre> |
| <span class="XMLElementTag"><Composite</span> <span |
| class="XMLAttrTag">xmlns</span>=<span class="XMLAttrValue">"http://www.eclipse.org/xwt/presentation"</span> |
| <span class="XMLAttrTag">xmlns:x</span>=<span |
| class="XMLAttrValue">"http://www.eclipse.org/xwt"</span><span |
| class="XMLElementTag">></span> |
| ... |
| <span class="XMLElementTag"></Composite></span> |
| </pre> |
| |
| <p>The root element also contains the attributes <b>xmlns</b> and <b>xmlns:x</b>. |
| These attributes indicate to an XWT processor which XML namespaces |
| contain the element definitions for elements that the markup will |
| reference. The <b>xmlns</b> attribute specifically indicates the default |
| XML namespace. Within the default XML namespace, object elements in the |
| markup can be specified without a prefix. The default XML namespace is |
| mapped to the namespace |
| "http://www.eclipse.org/xwt/presentation". The <b>xmlns:x</b> |
| attribute indicates an additional XML namespace, which maps the XWT |
| language namespace "http://www.eclipse.org/xwt". Required |
| language components defined by the XWT specification are prefixed by <b>x:</b> |
| when referenced in the markup of a file with this mapping.</p> |
| |
| |
| <p><b>The x:Prefix</b></p> |
| <p>In the previous root element example, the prefix <b>x:</b> was |
| used to map the XWT XML namespace |
| "http://www.eclipse.org/xwt". This <b>x:</b> prefix will be |
| used to map the XWT XML namespace in the templates for projects. The <b>x:</b>prefix |
| XML namespace contain several programming constructs that you will use |
| quite frequently in your XWT. The following is a listing of the most |
| common x:prefix namespace programming constructs you will use:</p> |
| |
| <ul> |
| <li>x:Key: Sets a unique key for each resource in a DataContext.</li> |
| <li>x:Class: Specifies the CLR namespace and class name for the |
| class that provides code-behind for an XWT page. You must have such a |
| class to support code-behind, and it is for this reason that you almost |
| always see x: mapped, even if there are no resources.</li> |
| <li>x:Name: Specifies a object name for the instance.</li> |
| <li>x:Null: <strong>null</strong> in Java.</li> |
| <li>x:Static: Enables a value reference that gets a static value |
| that is not otherwise an XWT-compatible property.</li> |
| <li>x:Type: Constructs a Type reference based on a type name.</li> |
| <li>x:Array: Provides general support for arrays of objects in |
| XWT.</li> |
| <li>x:Style: Specifies the type of a instance.</li> |
| </ul> |
| |
| <h3><a name="language_05"></a>Events and XWT Code-behind</h3> |
| <p>Most XWT applications consist of both markup and code-behind. |
| Within a project, the XWT is written as .xwt file and a synchronized |
| java class is used to write a code-behind file. When an XWT file is |
| loaded, the location of the XWT code-behind file for each XWT page is |
| identified by specifying a namespace and class as the x:Class attribute |
| of the root element of the XWT page.</p> |
| |
| <p>In the examples so far, you have seen several buttons, but none |
| of these buttons had any logical behavior associated with them yet. The |
| primary application-level mechanism for adding a behavior for an object |
| element is to use an existing event of the element class, and to write a |
| specific handler for that event that is invoked when that event is |
| raised at run time. The event name and the name of the handler to use |
| are specified in the markup, whereas the code that implements your |
| handler is defined in the code-behind.</p> |
| |
| <p>XWT:</p> |
| <pre> |
| <span class="XMLElementTag"><Shell</span> <span class="XMLAttrTag">xmlns</span>=<span |
| class="XMLAttrValue">"http://www.eclipse.org/xwt/presentation"</span> |
| <span class="XMLAttrTag">xmlns:x</span>=<span |
| class="XMLAttrValue">"http://www.eclipse.org/xwt"</span> |
| <span class="XMLAttrTag">x:Class</span>=<span |
| class="XMLAttrValue">"org.eclipse.xwt.tests.events.ButtonHandler"</span><span |
| class="XMLElementTag">></span> |
| <span class="XMLElementTag"><Shell.layout></span> |
| <span |
| class="XMLElementTag"><GridLayout</span> <span class="XMLAttrTag">numColumns</span>=<span |
| class="XMLAttrValue">"2"</span><span class="XMLElementTag">/></span> |
| <span class="XMLElementTag"></Shell.layout></span> |
| <span class="XMLElementTag"><Button</span> <span |
| class="XMLAttrTag">text</span>=<span class="XMLAttrValue">"Hello, world"</span> <span |
| class="XMLAttrTag">SelectionEvent</span>=<span class="XMLAttrValue">"selection"</span><span |
| class="XMLElementTag">/></span> |
| <span class="XMLElementTag"></Shell></span> |
| </pre> |
| |
| <p>Java:</p> |
| <pre> |
| <span class="JavaKeyword">protected void</span> selection(Event event) { |
| Button button = (Button) event.<span |
| class="JavaMember">widget</span>; |
| button.setText(<span class="JavaString">"OK"</span>); |
| } |
| </pre> |
| |
| <p><b>Event Attribute Syntax</b></p> |
| |
| <p>When you specify behavior through events in markup, you typically |
| use attribute syntax to attach handlers. The object element where the |
| event attribute is specified becomes the instance that listens for the |
| event and calls the handler. The name of the specific event you want to |
| handle is the attribute name. The attribute value is the method name of |
| the handler you will define. You must then provide the handler |
| implementation in code-behind, with the handler being based on the |
| delegate for that event.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </body> |
| <p><img src="../../cpy.png" /></p> |
| </html> |