Styles

Most applications try to use consistent styling and Aria provides support for consistent coloring and typography through its style manager. Aria's style management allows all the information and details of colors and fonts to be maintained separately from the rest of the UI description. Not only does this make it easy to reference particular style elements but it also makes it easy to switch styles say, for example, when rebranding an application for a different sets of end-users.

Using styles

In the introduction section we saw how styles could be applied when adding components either via XML or within Java code. Aria provides interactive visual tools to help design and use styles. Within Aria a style can be applied by selecting a component or several components and clicking on the chosen style in the style palette.

Changing a style

Color schemes

Aria extends the notion of styles by including a color scheme chooser to provide coherent sets of styles.

You can edit a set of styles as a color scheme by choosing the Color Scheme... option from the Style Palette's popup menu. The Color Chooser provides a convenient way of specifying sympathetic systems of colors and styles. The chooser consists of a number of areas for choosing the colors and then applying these colors to a set of styles. The color chooser has two parts, the first allows the choice of a set of sympathetic colors and the second allows selection of these colors for various usages. On the left hand side is a color wheel where you can choose a base color. This base color can be manipulated using two sliders for brightness and saturation. The hue can also be modified by clicking at some point within the inner circle. The Hue, Saturation and Brightness values can also be entered directly as numeric values. Clicking on the selected color preview (just below the color wheel) pops up a list of system colors (see the image on the right). The system colors can also be selected whenever the color wheel is available. Once the color has been chosen the colors and the variants are shown in a preview area. The number and type of variants displayed depend on the color scheme chosen. By default the scheme is monochromatic but other schemes can be chosen from the drop down list at the top of the chooser. Below the preview area is a table of colors and you can click on any on these to use it as the base color. On the second page of the chooser is an area where you can configure the styles. Simply click on the various sample texts to modify the foreground color, the background color or the font. A set of radio buttons allow you choose from these options. Once the set of styles has been selected click OK to save the styles under the specified style name. If a new style is being created the styles will be added to the style palette. Alternatively if the style name is already in use then the styles will be updated once the chooser is closed.

Layout Managers

Layout

By default Aria uses absolute positioning of components, with each component having explicitly specified size and location. Frequently it is more convenient to use some of the additional layout facilities found in Aria and in Java to both improve the overall appearance and simplify development.

Aria even provides its own layout manager to support interactive visual layout above and beyond what is possible with explicit layout while providing the runtime resize and position behavior that are frequently hard to achieve with other layout managers.

Default layout

As mentioned in the introduction Aria assumes that each component's coordinates are specified explicitly. Simply speaking this means that each component must have a specified X, Y location and a width and size dimension. The dimensions are all in pixels and do not vary with the size of the application window or the page container.

Limitations of explicit layout

Perhaps the greatest limitation of explicit layout is that the pages do not resize with changes to the application window and therefore if the application is made full screen it does not make good use of the available screen space.

Another significant limitation of the explicit layout is that it is not always possible to know the size needed for a component or a component's content in advance. Dynamic sizing of components can alleviate such problems.

Later in this chapter we will see how Java's Layout Manager facility has been adapted to help address some of the issues.

Aria provides a number of tools to support interactive positioning of controls. The tools include grids and guides. These tools can be used with several of the supported layout managers but work best with Aria's own layout managers; the GuideLayout and the ScaleLayout.

Alignment tools

Aria provides several tools for aligning components within a container and even spanning containers. These tools are located on the toolbar within the page designer and perform the following functions:

Alignment and Justification Tools

Title	Usage
	Align Bottom - aligns the bottom edges of all the selected components. The components are moved and retain their current height.
	Align Centre - aligns the centres of all the selected components. The components are moved and retain their current width.
	Align Left - aligns the left edges of all the selected components. The components are moved and retain their current width.
	Align Right - aligns the right edges of all the selected components. The components are moved and retain their current width.
	Align Top - aligns the top edges of all the selected components. The components are moved and retain their current height.
	Justify Horizontal - aligns the left and right edges of all the selected components. The components sized according to the minimum left and maximum right hand coordinates.
	Justify Vertical - aligns the top and bottom edges of all the selected components. The components sized according to the minimum top and maximum bottom coordinates
	Space Vertical - Adjusts the space between the selected components so that the space is equal distributed along the vertical axis
	Space Horizontal - Adjusts the space between the selected components so that the space is equal distributed alongthe horizontal axis

The alignment and justification tools are primarily designed to work with explicit layouts and will adjust the coordinates of the selected components. Use of the alignment tools with pages controlled by layout managers can lead to results that vary according to the specific layout manager and its current settings.

Grids and Guides

In the page designer the page being edited can be shown within a grid and with layout guides. The designer shows rulers to the top and left of the page, set out in pixel units.

The designer allows components to optionally snap to the grid. The selection of this option and the granularity of the grid can be configured within the page designer. In the top left hand corner or the designer is a button, that when pressed toggles the display mode. When in the configuration mode the rulers are shown with a red tint.

Once in the configuration mode you may right click anywhere on the page to get a context menu giving some options to control the layout. Once configuration has been completed just click the button in the top left to return to the page editing mode.

The options that can be configured in this way include:

Guides

Drawing on the techniques used in desktop publishing and document layout, Aria includes a facility to use guides. Guides are vertical or horizontal lines on the page to which components snap or gravitate while being positioned during page layout.

Guides are configured on a page by page basis rather than at the level of individual panels. Guides therefore support layout across panels so it is easy to align components on a page wide basis rather than solely within an individual container as is the case with most layout managers. Guides are also visually intuitive so little effort is required to learn how guides function and indeed there should be few surprises when using guide layouts unlike layouts such as the GridBagLayout which is notoriously difficult to use.

Adding guides

Guides can be configured on a page by page basis or on an application wide basis (as master guides) to help enforce layout rules across pages.

Within the page designer adding guides is carried out by

1. Clicking the button in the top left intersection of the rulers.
2. Click and drag from either of the rulers onto the page
3. Release the mouse at the location for the new guide
4. Drag an existing guide to adjust its position
5. Click the button in the top left to exit the guide editing mode.

To remove a guide simply enter the guide editing mode and drag a guide back to the ruler.

Individual guides can then be configured by right clicking on them and choosing the Guide Options... menu option. This option allows control over how the guide is positioned at runtime.

Guides can be positioned relative to one another or relative to the size at which the page is displayed so as to give a controlled final layout. The coordinates system used for the guide can also be expressed in relative terms of the page size instead of the absolute pixel size used at design time. The guide ID shown in the dialog is used to reference the guide by the constraint specified for each component on the panel controlled by the guide layout manager.

Several more options are available for configuration of the guides:

The area of guide sensitivity, that is the area within which a component will snap to the guide when moved can be highlighted (as illustrated above) by choosing the Show snap zone context menu option. The context menu is displayed by right clicking on a guide in edit mode. To enter the guide's edit mode, toggle the button to the top left of the page at the vertex of the two rulers. In this mode the rulers are shown with a red background. Some of the guide options are context sensitive and depend on the guide on which the mouse is clicked. The options are described below:

Snapping to guides

As a component or set of components is dragged about within the page designer the edges of the components will automatically snap to the guide whenever within range.

Guides will tend to cause a component to resize as a component is dragged but once a component goes out of range it will snap back to its original size.

Snapping to hints

In addition to the snapping of components to the guides the editor will show layout hints. These hints correspond to the edges of other components on the form. The hints therefore act as a form of automatic alignment of components. Later we plan to enhance this mechanism to support the alignment of baselines and the preferred platform component spacings (both features of the forthcoming JDK 6).

Setting up Columns

While in the configuration mode you can choose to setup columns and rows to assist layout. The GuideChooser dialog appears when this option is chosen.

You can use this dialog to quickly setup regularly spaced columns and rows. Once the guides have been added you may reposition the guides to best suit your layout needs.

A form will typically require a number of different guide types with some absolute position and some relative or scaled positioning.

Using guides

While it is possible to use guides purely for design time layout assistance the guides are of added benefit at runtime when a page is resized. To actually use the guides for this purpose it is necessary to use the GuideLayout manager. To use this Layout manager select the panel or container for which you wish to apply this option and set the layout property in the component's property sheet (normally to the bottom right of the page designer).

You may not see any immediate effect of choosing this layout manager but if you view the page's XML you will see that additional constraint attributes are added to the components belonging to the affected panel. The constraints refer to the guide ID which you may have noticed while setting up the guides. The guides are numbered from zero, up from left to right and from top to bottom. The constraint is thus just the list of guides to which the left, top, right and bottom edges of the component are bound (a -1 value indicates an unbound edge).

An example guide layout

To illustrate the use of the guide layout let's look at a sample form. The form is made up of two columns of labels and edits. Therefore a four column guide layout is created so that we can specify the spacing between the labels and edits and also the spacing between the columns, just as is shown above.

The leftmost guide in each column and the last guide (vertical guides 0, 3 and 7) are scaled guides so that each holds its position relative to the page. The next guide is a relative guide specifying a fixed width for the label. Following this another relative guide with a fixed width of 10 pixels is used to specify the spacing between label and edit. The edit field is then left to use the remaining space between the fixed guides and the scaled guides.

The XML code for the complete form layout is shown below.

Guide layout

 <Page Layout="Guide">
   <Layout/>
   <Guides width="640" height="480"> 
     <vert > 
         <Guide id="0" pos="10.0" type="abs" coords="abs" />
         <Guide id="1" pos="150.0" type="rel" coords="abs" prev="0"}
         <Guide id="2" pos="10.0" type="rel" coords="abs" prev="1"}
         <Guide id="3" pos="49.063" type="abs" coords="rel"}
         <Guide id="4" pos="10.0" type="rel" coords="abs" prev="3"
         <Guide id="5" pos="150.0" type="rel" coords="abs" prev="4"
         <Guide id="6" pos="10.0" type="rel" coords="abs" prev="5"
         <Guide id="7" pos="98.125" type="abs" coords="rel" 
     </vert > 
 
     <horz > 
         <Guide id="0" pos="10.0" type="abs" coords="abs"}
         <Guide id="1" pos="20.0" type="rel" coords="abs" prev="0"}
         <Guide id="2" pos="10.0" type="rel" coords="abs" prev="1"}
         <Guide id="3" pos="20.0" type="rel" coords="abs" prev="2"}
         <Guide id="4" pos="10.0" type="rel" coords="abs" prev="3"}
         <Guide id="5" pos="20.0" type="rel" coords="abs" prev="4"}
         <Guide id="6" pos="10.0" type="rel" coords="abs" prev="5"}
         <Guide id="7" pos="20.0" type="rel" coords="abs" prev="6"}
         <Guide id="8" pos="30.0" type="rel" coords="abs" prev="7"}
         <Guide id="9" pos="97.917" type="abs" coords="rel"/>
     <horz > 
   </Guides>
 
   <Components>
     <!-- guide constraints: left, top, right, bottom -->
     <Label x="10" y="10" w="150" h="20" constraint="0,0,1,1" content="First Name"/>
     <Edit x="170" y="10" w="144" h="20" constraint="2,0,3,1"/>
     <Edit x="170" y="40" w="144" h="20" constraint="2,2,3,3"/>
     <Edit x="170" y="70" w="144" h="20" constraint="2,4,3,5"/>
     <Edit x="170" y="100" w="144" h="20" constraint="2,6,3,7"/>
     <Label x="10" y="40" w="150" h="20" constraint="0,2,1,3" content="Second Name"/>
 
     <Label x="10" y="70" w="150" h="20" constraint="0,4,1,5" content="Phone"/>
     <Label x="10" y="100" w="150" h="20" constraint="0,6,1,7" content="Fax"/>
     <Edit x="485" y="11" w="144" h="19" constraint="6,0,7,1"/>
     <Edit x="484" y="40" w="144" h="21" constraint="6,2,7,3"/>
     <Edit x="484" y="69" w="146" h="22" constraint="6,4,7,5"/>
     <Label x="325" y="10" w="150" h="20" constraint="4,0,5,1" content="Address"/>
     <Label x="324" y="41" w="152" h="20" constraint="4,2,5,3" content="Street"/>
     <Label x="324" y="69" w="150" h="22" constraint="4,4,5,5" content="Town"/>
   </Components>
 </Page>

The constraints for each component specify the guide ID for the left, top, right and bottom edges. If the component is not bound to a guide then the ID can be specified as -1 and the x, y, w or h dimensions will be used to size and position the component as needed.

As of version 2.0.6 the guides can be stored in a separate file for reuse. Using this mechanism the guide files can be included using the following syntax:

Including guides

   <Guides include="guides/myGuideFile.xml"> 

By convention the guide files are included in the guides subfolder of the pages folder. The .xml extension is optional.

To see the guide layout in action we then resize the form. In the resized form each column still occupies half of the page although the relative size of the edit fields has increased.

Reusing guides

Sometimes, to promote consistency across forms you may wish to reuse a set of guides. So far we have no explicit support for such a process with Aria, however you can achieve the same effect by manually cutting and pasting the guide setup from one form to another.

The entire guide declaration is contained in the Guides element at the start of each page, with a Guide entry for each vertical and horizontal guide.

Layout managers

Java introduced the concept of layout managers as a way of managing cross platform layout issues. There are a wide variety of layout managers available within the core Java libraries and from third parties. However for reasons of simplicity only a core set of layout managers is supported within Aria.

Aria also includes a number of other layout managers used by some of its builders and wizards but not yet directly supported by the editor or by the basic Aria setup. These layout managers include:

While these layout managers are not yet supported by the editor you can still make use of them by coding their use directly in Java. Some of the examples shipped with Aria make use of these layouts.

Component hierarchies

It is often a good idea to subdivide an application and its pages into different areas.

At the highest level and application may use the notion of a frameset to subdivide the screen or page. Typically a frameset is used where there are persistent elements to an application such as headers, footers or sidebars. Framesets are often used for navigation controls like toolbars, progress meters, structural views (tree views) and so on.

Within an individual page further nesting of content may be used with various types of panels, scrollpanes, splitters and tab controls.

Generally the more an application can subdivide the hierarchy of components the easier it is to control the layout of those controls.

The coordinates of child panels and of the components nested in a child panel are always relative to the parent or owner of the component or panel. The coordinates are also always measured from the top left of the panel that owns the component.

Using a layout manager

In using a layout manager in Aria there are two steps to consider. First the parent container for a component must specify the type of layout manager it employs and secondly each component should specify the constraints that the layout manager should use to lay it out.

Using XML the layout is added to the page or parent component as in the example below:

Sample Page using Layout Managers

 <Page class="org.formaria.testpilot.ApplicationRecorder" layout="border">
    <Components>
       <ScrollPane constraint="center">
          <Table2 name="table" horizontal_scrollbar="as needed" 
                               vertical_scrollbar="always"/>
       </ScrollPane>
       <Panel name="SouthPanel" constraint="south" layout="flow" style="base">
          <Button name="btnOption" content="Options"/>
          <Button name="btnStart" content="Start" enabled="false"/>
          <Button name="btnPause" content="Pause"/>
          <Button name="btnSave" content="Save" enabled="false"/>
          <Button name="btnBack" content="Back"/>
          <Button name="btnAssert" content="Assert" enabled="false"/>
       </Panel>
    </Components>
    <Events>
       <Event method="setOptions" target="btnOption" type="MouseHandler"/>
       <Event method="startScript" target="btnStart" type="MouseHandler"/>
       <Event method="addPause" target="btnPause" type="MouseHandler"/>
       <Event method="saveScript" target="btnSave" type="MouseHandler"/>
       <Event method="goBack" target="btnBack" type="MouseHandler"/>
       <Event method="addAssert" target="btnAssert" type="MouseHandler"/>
    </Events>
 </Page>

In the example the page is given a border layout and its children, the scroll pane and the panel are given constraints that apply to the border layout. The panel in turn is given a flow layout, but in the case of a flow layout the only constraint is the order in which items are added to the container.

The layout in individual components is controlled by the constraint attribute. The value of the constraint attribute varies according to the layout manager in use. The AriaEditor editor will present a list of the constraints that are appropriate for the particular layout manager.

Framesets

In earlier chapters (See Frames setup.) we saw how framesets could be added and configured. The frameset is an important layout device for applications in that different frame elements can have different lifecycles. Frequently the top, left and bottom elements in a frameset are unchanging within an application, and this long running context provides a space for common features such as toolbars, navigation bars, banners and feedback information.

The frameset is control by a border layout (see See Layout managers.) and you can update each named area of the frameset independently of one another. The frames or named areas within the frameset are termed targets within Aria. Using the targets is straightforward.

We have seen how a page can be displayed by calling the showPage(...) method:

Showing a single page

 // Via the page manager member variable of the page
 pageMgr.showPage( "DetailsPage" );

A second version of the showPage method takes an additional argument that specifies the target area:

Showing a single page in the content target area

// The manager objects
pageMgr.showPage( "DetailsPage", "content" );
pageMgr.showPage( "StatusPage", "footer" );

The name of the target area matches what was specified in the frames file. After this what you do with the frames is really up to you. The framesets are just a way of dividing up the screen real estate and after that the pages they contain are treated as though a single page was being used with all the same lifecycle methods being called.

Editing framesets

Framesets when displayed comprise multiple pages and for a visual editor such as Aria this represents a number of issues and some of these issues impinge upon the operation of the page designer. The page designer can display a page within its frameset and this is normal behavior (in fact you are given a choice of using the frameset or not when opening a page).

You need to be aware that when editing a page within a frameset you are also editing the other pages referenced by the frameset. Normally the designer works with one page, one XML file and one Java source file for the page's response methods but in the case of a frameset other pages are also open. This is evident if you manipulate components on other pages within the frameset, you will see a small red icon appear next to the page files in the files view indicating that the file is modified.

The page you opened in the designer continues to be the one being edited and if you switch to XML it is this page's XML that you will see. However if the other pages are open in different instances of the page editor you can see their XML too.

Importantly the same instance of a frameset page is used in all instances of the designer. Therefore if you edit a page in one designer and switch to another that also shows the page in a frameset you should see your changes appear in the second designer.

Stopping home page from loading

In some applications the frameset may be modified or configured at startup, and in these cases it may be undesireable to have the framework load the home page into the frameset's content area. To stop the framework loading the home page in this way set the startup property StartClass to NONE:

Specifying that no home page should be loaded

 StartClass=NONE

When the start class is set in this way the content area is filled with the file/class specified by the frames.xml file. If the frames file does not specify the file then the content area will start in an empty state.

Application Styles

While Aria supports framesets within what would otherwise be considered an SDI (Single Document Interface) interface the framework supports a variety of other application styles, including the MDI (Multiple Document Interface) and a Docking Framework. The frameset is therefore used to describe the composition of the application and the `target' areas of the application. The target areas are those areas, panels or windows (depening upon the application style) that can be manipulated by the page manager and the showPage method. For more information on these application styles see See Application styles..

References

For more information on layout managers see the Sun's Java documentation.

http://java.sun.com/docs/books/tutorial/uiswing/layout/using.html

Data Binding

Data binding

Aria applications use the Model-View-Controller ( MVC) pattern to separate the key concerns in building an application. A key principal of this separation is that the model can be implemented without overdue concern for the presentation layer or user interface. Keeping the model simple makes it easy to implement business logic.

The separation of the model also means that the business logic need have little concern for the modalities or peculiarities of the user interface or the user interaction within the application.

Of course the model cannot be completely divorced from the user interface as occasionally interaction is required, say for instance if the model requires special input or needs to signal an error. Aria achieves the separation of concerns espoused by the MVC architecture by implementing a loose coupling between the data model and the user interface.

On the data or model side of the architecture Aria provides a rich data model that can be addressed via XML and XPath like references. This model can be composed of a wide variety of data and the data can be used in a variety of ways depending on the needs of the user interface and application.

Typically the data model will consist of data from a number of data sources such as static data defined in flat files, tables mapped in from a database, server side data obtained via service calls and configuration information.

Aria also saves its own data to the model, for example saving the component state data to the aria_state node so that things like list selections indices can be accessed via the mode or used for master details linking.

Your application may also save data to the model as it needs. The model grows with your application and its content is highly configurable. For example each node within the model can have multiple child nodes and each node can be a rich type, not just the basic types built into Java. Tables themselves are good examples of these composite objects, consisting of multiple rows and with rows consisting of multiple fields.

The diagram below shows how various data sources might be mapped into the hierarchy and how an individual object can be a composite of other objects. The diagram also serves to show the hierarchical arrangement of data which we will see being used in the next section on data binding.

Event Handling

Aria aims to simplify application development by reducing the amount of boilerplate code that must be generated for an application. One of the most time consuming activities and a troublesome feature of application development is the wiring together of components and events.

Java's abstract event handling mechanism is certainly flexible but more often than not the code needed for even simple event handling is repetitive and adds little of particular value to the application. In Aria the most common instances of this event handling wiring is taken care of by basic library functions so that all the Aria user need do is specify what is specific to a particular event.

Aria's event handling relies on the basic Java event handling mechanisms and at any point you can go beyond the Aria library and work directly with the low level event mechanisms. This chapter shows how to work with both mechanisms.

Adding EventHandlers interactively

Adding event handling in Aria is very easy. Simply select the component whose event you want to handle within the page designer. Then in the properties palette locate the event of interest. In the screen shot below you can see a mouse event being entered for the selected button.

Once the name has been entered and you press enter Aria finds the event handler in the source code or adds a new event handler if the handler doesn't exist already.

To correctly add the handler Aria must do a few extra things that may require additional input or modify the source code in other ways. Of these tasks the most obvious occurs if no name has been given to the component being edited then a popup dialog will appear requesting that you enter a name for the component.

Once a name is available for the component Aria can proceed and opens the source code in a text editor at the new event handler method.

If necessary a new source file may have been created into which the handler is added. The event is bound to the user interface and the new Java class by a declaration in the page's XML. You can see the event declaration by switching to the page designer and selecting the XML button in the designer's toolbar..

The page XML is updated as soon as the new method is added and the XML text editor is displayed.

And that's it, all of the infrastructure for event handling is taken care of and you can begin entering the application specific business logic.

Basic event handling

Regardless of how you edit the event handlers for your application the basic mechanisms are the same. The page's XML declaration names the event to be used to respond to a particular event type for a given component.

While the XML could point to a method in the page's base class or some existing utility class, most pages involve some form of custom class for handling the custom logic that belongs to the page. Pages can derive directly from Page but by changing the base class you can customize the event handling for components

This example re-introduces some Java code. Now the base class is our own custom written class derived from Page so that calls specified in the XML can be intercepted by the custom class.

A new Java class declaration

public class EventHandling extends Page

The XML file now specifies this custom class as it's base class and defines the two buttons which will have events attached.

A page specifying events

 <Page class="org.formaria.samples.xmlbuild.EventHandling">
    <Components>
      <Component name="btnProceed" type="XBUTTON" x="40" y="10" w="60" h="20" content="Proceed"/>
      <Component name="btnCancel" type="XBUTTON" x="110" y="10" w="60" h="20" content="Proceed"/>
    </Components>
 
	<Events>
      <Event method="nextPage" target="btnProceed" type="MouseHandler" next="xmlnavsamplescr2"/>
      <Event method="cancel" target="btnCancel" type="MouseHandler"/>
    </Events>

So now the java code handling the events is as follows:

The Java class's implementation of the events

 public void nextPage()
 {
     if ( wasMouseClicked() ){
       // Do something here...
       PageManager.showPage( getAttribute( "next" ));
     }
 }
 
 public void cancel()
 {
     if ( wasMouseClicked() ){
       Button button = (Button)findComponent( "btnCancel" );
       button.setText( "Clicked!" );
     }
 }

Built-in event handlers

Aria supports several basic types event, the support types are described below:

All of these basic event handlers are added via the Page class or its derivatives. We have already seen an example above of adding a handler via XML but the handlers can also be added via Java with just as much ease. Here's an example that is equivalent to the above XML:

Adding an event handler with Java

 addMouseHandler( btnProceed, "nextPage" );
 addMouseHandler( btnCancel, "cancel" );

Accessing event objects

In the case of multiple event being processed by a single event handler it is sometimes useful to query the properties of the event that caused the handler to be invoked. This is frequently the case with mouse events and key events (and special helper methods are defined for working with mouse events).

To access the event that triggered the handler it is necessary to call the getCurrentEvent method. The event can then be cast to whatever the appropriate type and the event specific data is then accessible. The example below shows how information is extracted from a mouse event. Note that the event is first checked to ensure that it is a mouse event before attempting to cast the value.

Accessing the current event

 public void handleMouseClicks()
 {
   if ( wasMouseClicked()) {
     MouseEvent me = (MouseEvent)getCurrentEvent();
     Point pt = me.getPoint();
    statusLabel.setText( "The mouse is at: + Integer.toString(pt.x) + "," + 
		Integer.toString(pt.y));
   }
 }

Under the hood

In adding event handlers Aria has to go through a number of steps and it is worth understanding these steps, if only for the sake of in-depth knowledge.

Consider first of all the process of adding the event handler. Aria constructs your page and the user interface for the page. This is really a process of adding the user interface components to an instance of your page's class. That class is derived from Page which includes the event handling mechanism. In processing the event declaration in your page's XML Aria therefore uses the page's event handling mechanism.

Like most normal Java code Aria pages respond to event through the standard listener interfaces and to save coding the page implements a number of the more common listener interfaces. The page can therefore listen for the common events associated with these interfaces. One of the most common is the ActionListener interface which is invoked in response to an event such as a button click. So when you ask a Aria page to add an actionHandler for a button it justs adds itself as an ActionListener for the button.

Once the button is clicked the page is notified through the interface. The method you registered is then looked-up and invoked via reflection (since Aria doesn't really have any knowledge of your method). No great magic there, but the process saves some more of the plumbing code.

Custom event handlers

It is possible to add support for just about any event type to a Aria application. The EventAdapter interface is an interface that wraps an object implementing the particular listener of interest. The wrapper is intended to be generic and therefore delegates most of its work to the Aria event handler.

Adding a custom event handler

 <Event method="tabChanged"  
  target="tabPanel"  
  type="org.formaria.events.swing.ChangeEventHelper"/>

The ChangeEventHelper implements the ChangeListener interface and in responding to ChangeEvents it invokes the named method. The framework assumes that the class referenced is an instance of the EventAdapter interface, which specifies the parameters needed to create and add the event handler.

The complete source for the above helper is shown below

ChangeEventHelper, a custom event handler

 package org.formaria.events.swing;
 
 import javax.swing.event.ChangeEvent;
 import javax.swing.event.ChangeListener;
 import org.formaria.aria.events.EventAdapter;
 import org.formaria.aria.events.AriaEventHandler;
 
 /**
  * A helper for the Swing ChangeListener interface
  * <p>Copyright (c) Formaria Ltd., 2009
  * <p>License: see license.txt
  * $Revision: 1.2 $
  */
 public class ChangeEventHelper implements ChangeListener, XEventAdapter
 {
   protected AriaEventHandler eventHandler;
 
   /**
    * Set the current event handler
    * @param xeh the event handler
    */
   public void setEventHandler( AriaEventHandler xeh )
   {
     eventHandler = xeh;
   }
 
   /**
    * Get the name of the adder method e.g. addActionListener
    * @return the method name
    */
   public String getAddedMethodName()
   {
     return "addChangeListener";
   }
 
   /**
    * Get the name of the listener e.g. java.awt.event.ActionListener
    * @return the listener name
    */
   public String getListenerInterfaceName()
   {
     return "javax.swing.event.ChangeListener";    
   }
 
   /**
    * Get the event mask
    * @return the mask e.g. AWTEvent.ACTION_MASK
    */
   public long getEventMask()
   {
     return 0x100000;
   }
 
   /**
    * The change event has occured
   */
   public void stateChanged( ChangeEvent e )
   {
     try {
       eventHandler.invoke( getEventMask(), e );
     }
     catch ( Exception ex ) {
       ex.printStackTrace();
     }
   }
 }
 

In the case of the above class the listener specific code is the stateChanged method, but all that does is delegate to the event handler.

Exception handling

Any application logic relying on user input is susceptible to a variety of errors and exceptional conditions that make process impossible to complete. In the Java world it is normal to trap these exceptions as they occur.

In Aria exception handling is closely tied to the event handling mechanism and the validation mechanism. The idea is that exceptions and validation errors can be handled in a manner similar to the event handling mechanism. Furthermore exceptions can be handled with a certain degree of separation from the normal flow of events since, as the name suggests they occur in exceptional circumstances.

For example an incomplete form could potentially produce a series of exceptions during event processing and during validation. From a user point of view it is unlikely that individual warnings would be produced for each error and instead the user would be informed of a set of errors or a synopsis of the errors. Aria supports this type of error handling and also redirection of errors to a central error handler. You can find more information on exception handling and input validation at See Writing a custom exception handler.

Generic event handling

Aria has built in handlers for the event types listed above however in some cases it is not adequate for all demands or it may be necessary to handle some other event types. Therefore the Aria API includes a number of methods to assist in integration of other event types.

To customize the event handling it is necessary to subclass the Page class. In subclassing Page there are three possible mechanisms for changing the event handling.

First the setEventHandler method can be used to set a specific event handler. Changing the event handler gives considerable scope to change the behavior of the event handling within Aria.

Secondly individual events can be added with the methods listed below. Choosing to add or modify specific events means that the changes will have less impact than modifying the event handler but at the cost of more work if the changes are to be reused elsewhere.

Finally the underlying Java event handling mechanisms can be used to handle events just as would be the case in a plain old Java application. Nothing in Aria should interfere with the basic event handling mechanism.

Event Handler API

 public void setEventHandler( EventHandler eh );
 
 public void addListener( Object comp, String listenerName, String argType );
 public void addHandler( Object comp, long eventType, String methodName ) throws Exception;

The first method setEventHandler sets the event handler class for the page. This method should be called in the page constructor. The page delegates to the event handler whenever an attempt is made to add a new event handler.

Most applications call specific methods in the page's API such asaddActionHandler, which in turn delegates to the event handler instance. The event handler is essentially a helper class that takes care of adding the event listener (by calling addListener and addHandler) and mapping the listener to a response method in the page. Further information on these APIs can be found in the API documentation.

Under the hood the Page class implements the methods specified by the ActionListener interface. In adding an event the page adds itself as a listener to the target component. When the event of interest is fired the page therefore responds to the event via this listener interface. The page then searches for the handler (that you had registered) and invokes it.

Extended Event Specification

As we saw in the earlier data binding chapter the syntax for dynamic method bindings has been extended to include referencing of classes other than the class upon which the current page is based.

The obvious difference from the data binding syntax is that an event binding sets up a reference to a method (the event handler method) and does not itself cause the method to be evaluated. The syntax for the extended event bindings is as follows:

To illustrate this extended event specification syntax let's have a look at an example.

Counter example extended with library functions

    <Page class="com.mypackage.ui.swing.SimpleCalculator">
      <Components>
        <Edit name="Counter" ... />
        <Panel ...>
          <Button name="DecBtn" ... content="${org.formaria.library.Calculator.getDecLabel()}"/>
          <Button name="ClearBtn" content="${org.formaria.library.Calculator[foo].getClearLabel()}"/>
          <Button name="IncBtn" ... content="${[foo].getIncLabel()}"/>
          <Button name="divideBtn" ... content="/"/>
          <Button name="multiplyBtn" ... content="X"/>
       </Panel>
     </Components>
     <Events>
       <Event method="doEquals" target="ClearBtn" type="ActionHandler"/>
         <Event method="org.formaria.library.Calculator.increment" 
                  target="IncBtn" type="ActionHandler"/>
       <Event method="org.formaria.library.Calculator[].decrement" 
                target="DecBtn" type="ActionHandler"/>
       <Event method="org.formaria.library.Calculator[foo].divide" 
                target="divideBtn" type="ActionHandler"/>
       <Event method="[foo].multiply" target="multiplyBtn" type="ActionHandler"/>
     </Events>
   </Page>

In the above example we are recreating the simple calculator that we have used in other examples. While the example is a contrived (we will document some more realistic examples later) it shows the new syntax in action.

Line 14 sets up an event binding to a static member of the org.formaria.library. Calculator class

Line 15 constructs a new instance of the class each time the event is bound (when the XML expression is loaded and evaluated).

Line 16 constructs a new instance and sets up a reference to the new instance. If the instance already existed it would be reused. In this case a instance of 'foo' had already been created at line 7 so that instance is reused instead of creating a new instance.

Lines 17 and 18 create bindings to other methods in the class and as in the case of line 16 they each use the 'foo' object created on line 7.

The importance of this simple extension should not be under estimated. Quite simply this extension means that your event handlers do not necessarily have to exist in a class derived from Page. In fact the extension means that you can build libraries of utility functions for common tasks and these functions can be used for things like navigation, calculations and other tasks that do not have to be tied to a particular page.

It is also worth noting that this extension mechanism does not mean that the library functions built using the mechanism cannot access the current page or the current component. Such values can be passed as arguments to the function are they can be accessed via the project, the page, the current event and the component hierarchy.

Adding event types

The EventHandler class loads a file events.xml to get a specification of the events it is to handle. The event handler can be instructed to handle other event types by adding additional configuration files. The easiest way to do this on a per project basis is to add an events.xml file to the project's resources. A startup parameter EventHandlers controls the name of the file loaded, but if none is found Aria attempts to load events.xml.

The default events.xml file is as follows:

Default event specification

 <?xml version="1.0" encoding="UTF-8"?>
 <events>
   <event name="ActionHandler" interface="java.awt.event.ActionListener" mask="128"/>
   <!-- mask="AWTEvent.ACTION_EVENT_MASK"/-->
   <event name="MenuHandler" interface="java.awt.event.ActionListener" mask="128"/>
   <!-- mask="AWTEvent.ACTION_EVENT_MASK"/-->
   <event name="FocusHandler" interface="java.awt.event.FocusListener" mask="4"/>
   <!-- mask="AWTEvent.FOCUS_EVENT_MASK"/-->
   <event name="TextHandler" interface="java.awt.event.TextListener" mask="1024"/>
   <!-- mask="AWTEvent.TEXT_EVENT_MASK"/-->
   <event name="ItemHandler" interface="java.awt.event.ItemListener" mask="512"/>
   <!-- mask="AWTEvent.ITEM_EVENT_MASK"/-->
   <event name="KeyHandler" interface="java.awt.event.KeyListener" mask="8"/>
   <!-- mask="AWTEvent.KEY_EVENT_MASK"/-->
   <event name="MouseHandler" interface="java.awt.event.MouseListener" mask="16"/>
   <!-- mask="AWTEvent.MOUSE_EVENT_MASK"/-->
   <event name="MouseMotionHandler" interface="java.awt.event.MouseMotionListener" mask="32"/>
   <!-- mask="AWTEvent.MOUSE_MOTION_EVENT_MASK"/-->
 </events>

Navigation and Page Management

Aria provides all the infrastructure necessary to manage pages within an application whether the pages are created with XML or via Java. The page manager at the heart of Aria also provides support for framesets and page history management.

The page management function is separated from the application and from the individual pages to provide independence of the underlying widget set.

Navigation

In Aria each page can be regarded as a discrete entity displayed by the application or applet. All pages must be derived from the basic Page class and this class interacts with the PageManager class to provide several methods of changing the displayed page. The page manager acts to maintain references to pages so that they do not need to be recreated whenever they are displayed, hidden or redisplayed.

In order to get a reference to the PageManager for the current project the call below can be used.

Retrieving the PageManager for the current project

 ProjectManager.getPageManager();

The main methods are showPage and showPrevious , which unsurprisingly show a new page and redisplay the previously selected page.

To invoke these methods it is necessary to add a way of initiating the navigation action. Normally this is accomplished by having a button or hostpot on the page with a text or graphic to indicate that a click will cause, say the next page to be displayed.

In the example below the user can initiate the navigation action by clicking on a button.

Setting up the navigation button and response event

 <Page class="myPackage.MyCustomPageClass">
     <Components>
        ...
        <Button name="btnProceed" x="40" y="10" w="60" h="20" content="Proceed"/>
     </Components>
     <Events>
       ...
       <Event method="proceed" target="btnProceed" type="ActionHandler"/>
     </Events>

The page must then implement the proceed response method. The Page class contains a reference to the PageManager for the current Project and can be used directly from subclassed Pages as shown below:

Implementing the response method

 package myPackage;
 
 import org.formaria.aria.*;
 import org.formaria.swing.*;
 import org.formaria.aria.data.*;
 import org.formaria.aria.helper.*;
 
 public class MyCustomPageClass extends Page
 {
 
   public MyCustomPageClass()
   {
   }
 
   ...
 
   public void proceed()
   {
     pageMgr.showPage( "Page2");
   }
 }
 

The page manager

The Aria page manager provides a mechanism for loading and displaying pages. It takes care of managing the page's lifecycle so that you need not be concerned with when and how a page is loaded or destroyed.

When an application requests a page by calling the showPage method the actual loading of the page is delegated to the page manager. The page manager will then attempt to load an XML file corresponding by name to the requested page. If an XML file is not found then the page manager will attempt to load a Java class of that name (and failing that, a dummy page can be created).

The page manager also takes care of the page lifecycle, calling the pageCreated, pageActivated and pageDeactivated methods as appropriate.

As the pages are separated from one another and from the applet class through this page manager mechanism the pages can be loaded independently of each other (unless explicit links or references are inserted). Furthermore, as the page manager is also separate from the applet and the widget set it is possible to code a large variety of utility functions so that they can work with different widget sets such as Swing and AWT.

Showing a page

A few simple methods are provided to allow loading and display of pages. It is generally assumed that all page handling will be delegated to the page manager and this is the case whenever the Page 's methods are used to display pages and this is the case for the normal response methods used in Aria applications.

The showPage method simply takes the name of a page. An alternative form of the showPage method can also take a second parameter indicating the target area (but more on this later). The showPage method loads the page as described above and requests that the applet displays the page. Implicitly in this process any currently visible page is deactivated and hidden.

Once a page has been shown it is regarded as the current page and at any point the current page can be referenced by calling the page manager's getCurrentPage method.

The showPage call can also include a URL so that the page can be loaded from a remote source. In fact most resource specifications in Aria can include URLs in this way.

Targets

Aria supports the notion of framesets similar to those used in HTML. Like HTML the framesets in Aria are defined in a separate frames file (pointed to by the startup properties file).

Each of the areas referenced by the frames file is known as a target area. Most of the page management methods include versions that take a target area name as a parameter and these functions affect the named area. Thus if you use the showPage method with a target area name, the area named in the method call is updated instead of the application's entire content area.

In cases where a frameset is used it is still possible to call the single argument versions of the page management functions. It is then assumed that the target area name defaults to ` content'.

Generally this default name works well where the frameset is being used to provide navigation facilities and other long lived facilities such as banners and footer. (see also Framesets.)

Page history

In addition to the showPage method Aria also provides the showPrevious method. As a page is shown, the history/order of the displayed pages is saved and the showPrevious method allows you to reverse through this order of pages. The showPrevious method works in much the same way as showPage and in fact relies on the same mechanisms to update the application.

Page history should be used with caution as it does not necessarily correspond to the end user's notion of what the previous page was. Furthermore if the user has navigated through a loop of pages then over use of the showPrevious method could lead to confusion.

Frequently there may be a need for multiple navigation mechanisms to help avoid such situations. It may be that it is just the user's perception of the order of pages that is out of sync with the way things are implemented and therefore we recommend adding visual feedback to your application to help support navigation.

Visual feedback should let the user know where they are within the application, how far they have progressed and how far they have to go to completion. The type of feedback used will of course vary from application to application and will also depend on the visual styles employed but whatever the detail, such hints greatly aid usability.

Resetting the page cache

On rare occasions it may be necessary to reset the page cache and page history. Some instances of this occur whenever the bound data is changed or reloaded from a different source, when a language changes or when it is necessary to reset all pages, removing user inputs.

To reset the page cache in this way use the following code:

Reset the page cache

 // Use the Page's member variable pageMgr!
 pageMgr.reset();

Page loaders

Aria employs an extensible method of loading pages. The page manager normally loads pages from XML or from Java classes if it cannot find a suitable XML page. This process can be altered by setting up secondary page loaders. The page loader is described by the PageLoader interface and can be configured through the startup property value for BuilderClass and NumBuilderClasses. Aria includes several page loaders including Aria's default page loader, an HTML page loader (see Importing HTML.) and a generic page loader for loading forms and other file formats (see Importing forms.).

Dataset defined navigation

When applications which use pages in a particular sequence are being written such as application forms consisting of multiple pages or wizard applications it is possible to define those pages in a static XML dataset file. For example in the code sample below, pages are defined within in a dataset file for a wizard type application.

 <Datasets>
   	<dataset id="navigation">
     		<dataset id="wizardpages">
       			<data value="welcome"/>
       			<data value="projectinit" desc="WIZ_PROJ_SET"/>
       			<data value="languagepage" desc="WIZ_PROJ_LANG"/>
       			<data value="colourscheme" desc="WIZ_PROJ_LAYOUT"/>
       		<data value="finish" desc="WIZ_PROJ_FINISH"/>
     		</dataset>
  	</dataset>
 </Datasets>
 

This dataset file needs to be referenced from the datasources file which is in turn loaded from the ModelData startup property. For more on loading datasets see See Data management.. Once loaded, the application will have access to these definitions via the DataModel for the project. There are three possible paths declared in this wizard dataset, `wizardpages', `generationpages' and `buildpages'. The relevant path can be set upon clicking a button, a menu or seleting a radio button.

A singleton class can then be written which takes care of the navigation and of course the pages referenced by the value attribute of the model nodes need to exist on the classpath.

NavigationManager Singleton class

 public class NavigationManager {
 
   BaseModel navMdl;
   protected int currentNode = 0;
   BasePage currentPage;
   private static NavigationManager navMgr;
 
   private NavigationManager( String navPath ) {
     navMdl = ( BaseModel ) ProjectManager.getModel().get( "navigation/wizardpages" );
   }
 
   public static NavigationManager getInstance()
   {
     if ( navMgr == null ) 
       navMgr = new NavigationManager()
 
     return navMgr;
   }
 
   public static void next()
   {
     getInstance.showNextPage();
   }
 
   public static void prev()
   {
     getInstance.showPrevPage();
   }
 
   public void showPrevPage()
   {
     currentNode--;
     showpage();
 
   }
 
   public void showNextPage()
   {
     if ( currentPage == null ) {
       BaseModel mdl = (BaseModel) navMdl.get( currentNode );
       String pagename = (String) mdl.get();
       currentPage = (BasePage) ProjectManager.getPageManager().getPage( pagename );
     }
     if ( currentPage.checkValidations() == 0 ) {
       currentNode++;
       showpage();
     }
   }
 
   public void showHomePage()
   {
     currentPage = null;
     currentNode = 0;
     BaseModel mdl = (BaseModel) navMdl.get( currentNode );
     String pagename = (String) mdl.get();
     currentPage = (BasePage) ProjectManager.getPageManager().showPage( pagename );
   }
 
   private void showpage()
   {
     BaseModel mdl = ( BaseModel ) navMdl.get( currentNode );
     String pagename = ( String ) mdl.get();
     currentPage = ( BasePage ) ProjectManager.getPageManager().showPage( pagename );
   }
 
 }

This mechanism can be used in conjunction with Library Functions to manage the page navigation in a simple and easy to maintain way. Take the following XML page declaration for example.

A navigation page XML declaration

 <Page class="net.co.test.NavPanel" style="Heading">
 	  <Components>
     		<Image name="nextButton" x="564" y="51" w="19" h="18" content="right.gif"/>
     		<Image name="prevButton" x="60" y="54" w="19" h="18" content="left.gif"/>
   	</Components>
   	<Events>
     		<Event method="net.co.test.NavigationManager.next" target="nextButton" type="MouseHandler"/>
     		<Event method="net.co.test.NavigationManager.prev" target="prevButton" type="MouseHandler"/>
   	</Events>
 </Page>
 

This code will call the static methods of the NavigationManager class and the NavigationManager will take care of presenting the correct page. Of course this can be extended to take care of multiple routes through an application or to repeat certain pages which will bind to different parts of the model and it should be obvious that pages can be added or rearranged without any difficulty.

Mapping page names

A page name can now be paramaterized or mapped, so that a frames file or startup.properties file can specify a key instead of a page name. This key can then be mapped to a specific page depending on the context or on startup parameters.

Setup the application lifecycle listener to set the initial page name

 // In startup.properties specifc the Lifecycle object
 // LifeCycleListener=my.project.ProjectListener
 
 // In that object map the "START_PAGE" page name
 public class ProjectListener implements LifeCycleListener
 {  
   /**
    * Called when the application/applet has been created and initialized.
    * @param project the owner project
    */
   public void initialize( Project p )
   {
     String[] args = (String[])project.getObject( "StartupArgs" );   
     // Set the start page to the 3rd command-line parameter    
     p.getPageManager().mapPageName( "START_PAGE", args[ 3 ] );
   }
 }

and instead of hardcoding a page name in the frames file it can be replaced with the appropriate key:

Set the content using a key instead of a page name

 // In the frames.xml include the "START_PAGE" key
 <Frame name="content" constraint="content" width="500" height="200" 
     content="START_PAGE" title="Home" icon="ac0036-16.png" sidebar="west"/> 

Application Styles

Aria supports multiple application styles, including Single Document Interface (SDI) and Multiple Document Interface (MDI) styles with and without docking of the internal windows.

Using the various application types you can create a variety of applications from the simple to the complex. Most applications will rely on an SDI style of interface for simplicity, but others such as management consoles and tool style applications can make good use of a docking framework to help manage the user interface complexities that arise from hierarchies and structures of the application domain.

Application styles are simple dictated by the startup applet used to launch an application and most of the remaining code and configuration is common to all applications types. In some cases, switching between application styles is also possible, provided that attention is paid to things like page navigation and framesets.

Application styles

Aria supports multiple application styles as metntioned above. These styles are:

Generally it seems that users prefer SDI type applications , or some form of docking, however some application such as complex management applications may justify use of MDI. The choice of one application style depends on your particular application and changing from one to another is just a matter of choosing the appropriate startup class.

Docking Frames

Docking frames allow multiple windows, with headers, titles and icons to be displayed in various areas of the screen. Multiple windows or targets can be placed in each of these areas. The docked windows can be minimized to sidebars and later restored to their original location. The docked windows may also be dragged from one area to another thereby allowing users to customize the layout of their application.

Docking frames also show a preview of the docked window when the mouse is moved over the sidebar button. Using these `sliding' windows can save valuable screen real estate and help reduce clutter. A user might, for instance, minimize a window to the sidebar when the information contained in that window is only of occassional interest. Then, in order to consult the window all she need do is move the mouse over the sidebar button to view the window contents once more. A simple click will then dismiss the preview.

A docked panel may also be zoomed in on so that it occupies almost all the available screen area (apart from the toolbars, menus and sidebars). To zoom in on a panel just double click the header, then to restore the view just double click the header once more.

Using the docking layout

As mentioned above, to use the docking layout you just need to select the appropriate startup application org.formaria.swing.docking.DockingApp

Startup for the docking application style

 java -cp AriaRuntimeCommon.jar org.formaria.swing.docking.DockingApp

The FrameTest sample application can be seen below when used with the Docking application style. The application is shown with half of its windows minimized, two to the south or bottom docking sidebar and one to the east or right handside sidebar

Setting the layout configuration

The basic frameset is specified using the frames file that was used for the basic frames setup earlier (see Framesets.), but for docking layouts we must add some extra information detailing how the screen is to be divided up. For example the following:

Setting up a docking layout

 <FrameSet layout="(COLUMN (ROW weight=1.0 left 
 (COLUMN middleTop content middleBottom) right) bottom)">
   <Frame name="left" constraint="left" content="p1" 
      icon="aria_icon.png" sidebar="west" title="Dock to the left"/>
   <Frame name="right" constraint="right" content="p2" icon="aria_icon.png" sidebar="east"/>
   <Frame name="middleTop" constraint="middleTop" content="p3" icon="aria_icon.png" sidebar="west"/>
   <Frame name="middleBottom" constraint="middleBottom" content="p4" icon="aria_icon.png" sidebar="south"/>
   <Frame name="content" constraint="content" content="Welcome" icon="aria_icon.png" sidebar="west"/>
   <Frame name="bottom" constraint="bottom" content="p6" icon="aria_icon.png" sidebar="south"/>
 </FrameSet>

The docking layout is specified as an attribute of the FrameSet element, and follows the format specified by the SwingLabs MultiSplitLayout layout manager (see http://today.java.net/pub/a/today/2006/03/23/multi-split-pane.html ).

Docking options

Each of the docked frames has a number of properties that yo can use to customize the appearance of the docked frame, and these are:

Docking frame attributes

Attribute	Usage
icon	Specifies the name of an icon to use in the frame's header.
sidebar	The name of the side bar into which this target docks when minimzed. The options are: west - dock into the west or left hand side sidebar south - dock into the south or bottom edge sidebar east - dock into the east or right hand side sidebar
title	The title of the frame.
constraint	The name of the docking area into which this frame or panel normally docks. The constraint should match one of the areas specified by the FramsSet 's config attribute.
minimized	If true , sets the initial state of the panel to be minimized.

Embedded applications

Not all applications are standalone and in some cases an application needs to coexist with legacy functionality or functionality obtained from a third party. Therefore there are situations where an application does not have direct control of its startup or of its frame. For this purpose Aria and Aria applications can be embedded in a standard Swing application as though the Aria application was just a Panel or just another component being used by the application.

The key to embedding a Aria application is the XContentHolder interface which describes the content displayed to the user. The interface is used by the page manager to display the pages that makeup the Aria application.

Modular application

Just as a Aria application can be embedded in a legacy application, one Aria application can be embedded in another. In fact multiple Aria applications can coexist within the one JVM. Applications used in this way can also exist as standalone entities in their own right. Turning this about, applications can therefore be built in a modular way, such that a component or module can also exist and operate as a complete application.

Building applications in a modular way allows you to deliver functionality in a targeted way, depending on things like user roles/needs, security/access rights, connectivity levels, development schedules or even for commercial reasons (e.g. advanced features for power users). With a modular architecture you can be more targeted with your delivery of functionality.

Aria's support for modular applications extends throughout the platform and apart from the loading of the modules you can largely regard the separate modules as being part of the complete application from a development standpoint.

Set startup objects

Multple startup objects can be added simply by adding startup property entries in the form:

Listing the startup objects

 StartupObject<N>=Name;className
 StartupObject<N>=Name;className;Project

where is a counter starting from 0. In the second example the object is constructed via a constructor that takes an instance of the project as an argument

While this may seem like an insignificant change it opens up the possiblity of having multiple applications running within the same JVM and it means that an application can be built from modular elements, elements that can exist as standalone applications or as integrated modules.

Relaunching applications

Support for the system tray or launch area has been added. When a system tray icon is added the application can choose to stay resident in memory after the main window has been closed by setting the " ExitOnClose " startup property to false. The advantage of doing this is that the data model does not need to be reinitialized if the main window is just being redisplayed. This initialization can be significantly quicker than normal startup as all the classes needed by the JVM are already loaded. If remote data is used the startup gain may be even greater as network access may not be required.

The tray icon provides two menu items, one to open the window and the second to close the window and exit the JVM.

Input Validation

Aria input validation allows you to define your validations in a single file so that the validation rules contained in the file can be used application wide or even across applications. Built-in validations provide common validations such as `mandatory' and `min-max' validations. The validation rules provide predictable and consistent behavior making your code much easier to maintain and extend than the alternative of checking individual inputs on an ad hoc basis.

The validation mechanism can also make it easier to localize an application or customize things like input limits for different environments or contexts.

In this section you will see how to implement the simple validations and how to handle validation errors and exceptions. The chapter will also show how to build customized validations.

Adding Basic Validations

The first step in adding input validations is to define our validation rules in an XML file and amend the startup.properties file to refer to the file.

Create a new file and name it ` validations.xml '. In the file create a simple validation file in the resources directory of your project.

A simple validation file

 <Validations>
  <validation name="firstname" type="mandatory" msg="Firstname cannot be blank"/>
 </Validations> 

The name attribute is what we refer to when referencing the validation from a page. The type attribute defines the validation type and the msg attribute is the message which is shown should the validation fail.

The startup.properties file needs to refer to the new validations file. Setting the validations file can be carried out through the project properties page within the editor or manually by adding the following line to the startup.properties file. If no `Validations' property is specified the application will default to `validations.xml' and use it if found.

New line in the startup.properties

 Validations=validations.xml

Now a page can be created with an edit field which needs to be validated. To provide data for the field and to map the input field to the data model a binding can be added within the data section. A button has also been added which will be used to trigger the validation.

The validated page

 <Page class="org.formaria.test.Personal" style="prompt">
   <Components>
   <Label x="144" y="110" w="100" h="20" style="prompt" content="Firstname:" 
          alignment="Left" opaque="false"/>
       <Edit name="firstnameText" x="294" y="108" w="178" h="20" style="data" alignment="Leading"/>
       <Button name="validateBtn" x="220" y="250" w="200" h="30" content="Validate"/>
   </Components>
   <Events>
     <Event method="doValidation" target="validateBtn" type="ActionHandler"/>
   </Events>
   <Validations>
     <Validation rule="firstname" target="firstnameText"/>
   </Validations>
   <Data>
     <Bind target="firstnameText" source="customer/firstname" output="customer/firstname"/>
   </Data>
 </Page>

Once the validation rule has been setup and bound to a component, the validation needs to be triggered and validation error messages also need to be presented to the user.

From the page's XML file it can be seen that the class which implements the event handlers is ` org.formaria.test.Personal '. For now, simply insert the following function into the class:

Prepare to handle validations with an event handler function

   public void doValidation()
   {
     int ret = checkValidations();
   }

If the application is run and the button clicked, the Java console will show the exceptions being thrown with the text of the validation. If some text is entered into the textbox and the button clicked again no exception is now thrown indicating that everything is OK.

The checkValidations function returns a value indicating the status. A decision can be made what to do depending on the value returned from the function. The return values are defined as constants in the org.formaria.aria.validation.Validator interface.

This code works but it is not a particularly elegant way of handling the validations and the section Writing a custom exception handler., will also look at how to handle and display the validations in a more programmer friendly way.

Adding component validations

The validation described above was triggered by a programmed event and the same validation would also be triggered upon a page transition. Component validations on the other hand are triggered when the user interface component being validated has lost focus. Start by opening the validations.xml file and adding a new minmax validation. The new validation appears as below

An in-line validation

 <validation name="age" type="minmax" min="18" max="65" 
             msg="Customer age must be between {min} and {max}" mandatory="false"/>

In this case the type is ` minmax ' indicating that this validation is to be used with numeric data. The ` min ' and ` max ' attributes contain the limits of the input. The message contains the two pieces of text ` {min} ' and ` {max} '. These values will be substituted with the values contained in the ` min ' and ` max ' attributes whenever the validation is triggered. The ` mandatory' attribute indicates whether or not the field must contain data when the page level validations are being carried out.

Next add another edit component to the ` personal ' page and add the validation below.

 <Validation rule="age" target="ageText"/>

Start the application once more and enter a value outside the specified range into the new edit field. Hit the tab key and you will notice an exception being output in the Java console. Do the same with a value within the range and no exception is output.

To highlight the behavior of the validation a few input combinations are listed. For clarity enter some data into the firstname edit so that it does not trigger the mandatory validation.

• Clear the data in the age edit field and click the button. No exception is output as the mandatory attribute is set to false .
• Enter some invalid data into the edit field, hit the tab field to generate the exception and click the button. In this case the page level validation triggers an exception as the text entered into the field is outside the permissible range even though the mandatory flag is false .
• Change the mandatory flag to true and restart the application. Leave the age field blank and click the button. In this case an exception is triggered as the field cannot be blank.

Validation attribute evaluation

Aria 3.0 extends the use of evaluated attributes to most areas of the framework, including validations. Evaluated attributes allow you to change the behavior of a validation at runtime by way of callbacks to your code or to library code.

Handling exceptions

The attribute evaluator contains an exception handler that gets called in case of an exception and can override the result returned by the attribute evaluator. The evaluator may be of use in case, for example, an evaluation depends on a list selection and where that list may not have a selected values - the list would otherwise return a value such as null or -1 to indicate the error and this is probably not a valid value for the evaluated attribute. Say a path of a/b/${c}/d/e is enetered and ${c} depends on say a list selection and that list is not fully initialized.

Validation lifecycles

Validation can be invoked at various times within an application. For the most part the lifecylce of an individual validation instance is tied to the lifecycle of the component and page to which it is bound.

At the finest level a validation may be triggered by a change in a components data, or by intervention by the programmer, while at a courser level the validations can be triggered prior to page transition.

Validation on Page Transition

Normally validations are checked when a page transition occurs if the TriggerValidations startup property is set, however on versions of Aria prior to 3.2 this value was not added to the startup file by the New Aria Project wizard , so it wass necessary to set the value manually.

Once the TriggerValidations flag is set a validation error will prevent the page transition from occuring.

Writing a custom exception handler

The method of reporting the validations up to now is crude and does not give you much control of error reporting. In order to manage the validations a custom exception handler can be written.

Writing a custom exception handler is straightforward and allows you the same code to be used for error handling on all of pages in an application. A new class named ` ExceptionHandler ` which provides an implementation of the ExceptionHandler interface is created.

The ExceptionHandler interface contains two methods.

The handleException method definition

 public boolean handleException( Object c, Exception ex, Object checker );

The handleException method takes three parameters and returns a boolean value. The first parameter is the component being validated, the second the exception, and the third is the validator which is carrying out the validation. The method should return true if further validations are to be carried out and false if no more validations are required. This chaining of validations allows you to control how the validations are used and how error messages are displayed. Stopping a chain of validations allows you to prevent the user being bombarded with error messages if, for instance, a single input field triggers multiple validation errors.

The accumulateMessages method definition

 public int accumulateMessages( boolean accumulate, int level );

Another method is now required, the accumulateMessages method is called twice when the Page.checkValidation s method is invoked. The first time is before any validations have been done so as to inform the ExceptionHandler that page level validations have begun. In this case the first parameter is true . Then, it is called once more when all of the validations have completed and in this case the first parameter is false .

The second parameter indicates the most serious level of error encountered so far. the value of this parameter can be overridden within the implementation of the accumulateMessages method by returning a different value from the method. Otherwise it is expected that the second parameter is returned.

Now we will implement our custom ExceptionHandler class as shown below. The class is shown in its entirety as it is to explain it section by section when the context of each section can be seen.

The entire ExceptionHandler class

 package org.formaria.test;
 
 import java.util.*;
 import java.awt.*;
 import org.formaria.aria.*;
 import org.formaria.aria.exception.*;
 import org.formaria.aria.validation.*;
 
 public class ExceptionHandler implements ExceptionHandler
 {
   boolean pageValidation = false;
   private Page currentPage;
   Vector errors, warnings;
 
   public ExceptionHandler( Page page )
   {
     currentPage = page;
   }
 
   public boolean handleException( Object comp, Exception ex, Object xvalidator )
   {
     Validator validator = ( Validator )validator;
     if ( ( validator.getLevel() == validator.LEVEL_ERROR ) && ( ! pageValidation ) ){
       currentPage.showMessage( "Input error", ex.getMessage() );
       return true;
     }
     String msg = validator.getMessage();
     if ( validator.getLevel() == validator.LEVEL_ERROR )
       errors.add( msg );
     else
       warnings.add( msg );
 
     return true;
   }
 
   public int accumulateMessages( boolean start, int level )
   {
     pageValidation = start;
     if ( pageValidation ){
       errors = new Vector();
       warnings = new Vector();
     } else {
       if ( errors.size() > 0 || warnings.size() > 0 ) {
         Toolkit.getDefaultToolkit().beep();
         currentPage.showMessage( "Error", formatMessages() );
       }
     }
     return level;
   }
 
   private String formatMessages()
   {
     String msg = "";
     for ( int i = 0; i < errors.size(); i++ )
       msg += "error :" + errors.elementAt( i ) + "\n";
     for ( int i = 0; i < warnings.size(); i++ )
       msg += "warning :" + warnings.elementAt( i ) + "\n";
     return  msg;
   }
 }

The constructor takes the page being validated as a parameter. This is stored in a member variable for use when the validations are being done.

The ExceptionHandler constructor

   public ExceptionHandler( Page page )
   {
     currentPage = page;
   }

The handleException method handles component and page level validations. In the case of component validations the level will be XValidator.LEVEL_ERROR passed exception is simply displayed.

In the case where the pageValidation flag is true the message is added to the appropriate storage. The idea behind this is that the reporting of the errors can be controlled instead of having to display individual messages (and require the user to dismiss multiple error messages) or only most severe errors need be displayed.

Implementing the handleException method

   public boolean handleException( Object comp, Exception ex, Object xvalidator )
   {
     Validator validator = ( Validator )validator;
     if ( ( validator.getLevel() == validator.LEVEL_ERROR ) && ( ! pageValidation ) ){
       currentPage.showMessage( "Input error", ex.getMessage() );
       return true;
     }
     String msg = validator.getMessage();
     if ( validator.getLevel() == validator.LEVEL_ERROR )
       errors.add( msg );
     else
       warnings.add( msg );
 
     return true;
   }

The accumulateMessages method is shown below

Implementing the accumulateMessages method

   public int accumulateMessages( boolean start, int level )
   {
     pageValidation = start;
     if ( pageValidation ){
       errors = new Vector();
       warnings = new Vector();
     } else {
       if ( errors.size() > 0 || warnings.size() > 0 ) {
         Toolkit.getDefaultToolkit().beep();
         currentPage.showMessage( "Error", formatMessages() );
       }
     }
     return level;
   }

The first line sets the member variable ` pageValidation ' to the value passed in the ` start ' parameter.

If start is true the storage vectors are initialized; one to store warnings and the other to store errors.

Alternatively, if start is false something needs to be done with the errors and warnings that have been accumulated. In this case, the showMessage method of the currentPage is called which will display the errors and warnings in a simple text dialog with an OK button. A decision on what to do next can be made in the ` personal ' page where the checkValidations method was called depending on the values returned from the accumulateMessages method.

As mentioned above this error handling mechanism provides control over the error reporting mechanism and another way to handle the validations in the case where there are only warnings is to display a dialog listing the warnings and asking `Do you wish to continue?' along with ` Yes ' and ` No ' buttons. If the Yes button is clicked then the value XValidator.LEVEL_IGNORE can be returned which will give the page the impression that no validations were generated.

Writing a custom validation factory and custom validations

The basic ValidationFactory class can construct the validation types discussed so far but custom validations might be required, and this is done by means of writing a custom validation factory.

Start by creating the class AValidationFactory which extends the ValidationFactory class.

The custom AValidationFactory

 package org.formaria.test;
 
 import java.awt.*;
 
 import org.formaria.debug.*;
 import org.formaria.xml.*;
 import org.formaria.aria.build.*;
 import org.formaria.aria.validation.*;
 
 public class AValidationFactory extends ValidationFactory {
 
  public Validator getValidation( String validationName, Method m, int mask, Object page )
  {
     return super.getValidation( validationName, mask, page );
  }
 
 }

For now the new class simply implements the getValidation method and returns the call to the super method.

In order to start using this custom class the following line needs to be added to the startup.properties file

The startup.properties line

 ValidationFactory=org.formaria.test.ValidationFactory

If the application is run now, it will work exactly as before except that our new validation factory is now controlling the construction of the validation rules.

Now a custom validation class can be created. As an example a simple number validation class can be created which will make sure that entered data is numeric. Create a class called NumberValidation which extends the BaseValidator class. Create the validate method which carries out the validation. In the NumberValidator class the Double.parseDouble method is used to parse the text contained in the component. If an exception occurs it can be assumed that the validation has failed, the errorLevel is set and an exception is thrown.

The NumberValidation class

 package org.formaria.test;
 
 import java.awt.*;
 
 import org.formaria.aria.validation.*;
 
 public class NumberValidation extends BaseValidator {
 
   public void validate(Object c, boolean forceMandatory) throws Exception
   {
     String text = getText(c);
     if (text.trim().length() > 0) {
       try {
         Double.parseDouble(text);
       }
       catch (Exception ex) {
         errorLevel = LEVEL_ERROR;
         throwException();
       }
     }
   }

Now the custom validation factory class needs to be amended to create and return the NumberValidator class whenever the text ` number ' is passed in the validationName parameter of the getValidation function.

The modified getValidation method

   public Validator getValidation( String validationName, Method m, int mask, Object page )
   {
     XmlElement ele = ( XmlElement ) validations.get( validationName );
     String type = ele.getAttribute( "type" );
 
     if ( type.compareTo( "number" ) == 0 ) {
       NumberValidation validator = new NumberValidation();
       validator.setName( validationName );
       validator.setMask( mask );
       validator.setup( ele );
       return validator;
     } else {
      return super.getValidation( validationName, mask, page );
     }
   }