get started




reference docs

case studies

knowledge base





Carousel zone

SourceForge.net Logo





mailing list
XUI Zone - articles

Introducing the GuideLayout, Part I


Part I: Introducing the GuideLayout
Part II: Using the GuideLayout oustide of XUI

By default when visually assembling a XUI page absolute positioning of components is used. 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.

For a localized application or for one that does not employ a fixed window size this can be a painful limitation. Java's built-in layout managers are useful but tend to be either limited in functionality or difficult to programme correctly. Support for layout managers is also limited and may even add to the complexity.

Traditionally graphical designers have used desktop publishing tools such as Quark and PageMaker to layout documents. These DTP applications have for a long time supported the notion of guides and in version 2.0 of XUI we try to emulate some of these solutions. XUI's NetBeans plug-in has for some time supported visual layout tools called guides to help explicitly align components. In version 2.0 we are introducing runtime support for this layout mechanism with the new GuideLayout layout manager.

Guides are simply lines drawn on the page at design time to assist layout. Components can snap to the guide position when dragged around a page at design time and in this way guides allow components to be aligned with respect to one another and with respect to the page instead of just the parent container. Visually the behaviour is obvious and from a programming perspective the guides are also easy to use with the component's layout constraints being automatically maintained. All the page designer need do is choose the GuideLayout for the container.

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 and the guides are numbered.

Figure 1 - Using guides in the Kalideoscope editor

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 grid and guide options that can be configured in this way include:

Listing 1 - Grid and guide options
Option Role
Show Guides Shows the alignment guides
Show Grid Show the grid (with a minimum display spacing of 10 pixels).
Snap to grid Turns on or off the snap to grid facility where by components that are moved align themselves to a grid point.
Snap to guides Turns on or off the facility whereby components snap to the nearest guide.
Set Grid Spacing The separation of grid points in pixels.
Guide sensitivity Specifies the distance in pixels within which a component must be for it to be affected by a guide line.
Setup Columns Displays a dialog that allows the addition or guides to support rows and columns for layout purposes
Guide options... Configure an individual guides. This option depends on the guide closest to the point where the mouse was clicked.

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. In the page designer adding guides is carried out by:

  • Clicking the button in the top left intersection of the rulers.
  • Click and drag from either of the rulers onto the page
  • Release the mouse at the location for the new guide
  • Drag an existing guide to adjust its position
  • 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.

Figure 2 - The guide option chooser

Several more options are available for configuration of the guides:

Listing 2 - Guide options
Parameter Usage
ID An ID used by the component constraint to identify the guide. This option is read-only and is automatically configured by the editor. Guides are renumbered as they are repositions so that the leftmost or topmost guide is always zero.
Orientation A read-only property identifying the guide as vertical or horizontal
Position The guide position. Absolute positioning means the guide is position relative to the top left of the page. Relative positioning means the guide is position relative to the previous guide (to the left or above).
Coordinate The coordinates express the position of the guide either in absolute terms of pixels or in terms of the page size (scaled). For a scaled coordinate system the location is expressed as a percentage of the page size.
Location The guide location is its position. For a relative position the location value is the offset from the previous guide, whereas for an absolute location the value is the distance from the top left of the page.
Minimum Not yet implemented
Maximum Not yet implemented

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 display 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.

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.

Figure 3 - The guide settings

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 teh 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 with 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.

Figure 4 - The running application

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

Listing 3 - Guide Layout
<XPage Layout="Guide">
<Layout/> <Guides width="640" height="480" vert="{0,10.0,2,0}{1,150.0,4,0,0}{2,10.0,4,0,1} {3,49.063,2,1}{4,10.0,4,0,3}{5,150.0,4,0,4} {6,10.0,4,0,5}{7,98.125,2,1}" horz="{0,10.0,2,0}{1,20.0,4,0,0}{2,10.0,4,0,1}{3,20.0,4,0,2}{4,10.0,4,0,3} {5,20.0,4,0,4}{6,10.0,4,0,5}{7,20.0,4,0,6}{8,30.0,4,0,7}{9,97.917,2,1}"/> <Components> <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> </XPage>

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 dimesions will be used to size and position the component as needed. In the above XML example all the edges are bound to guides so the explicit dimensions are redundant and could be omitted.

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.

Figure 5 - The resized application

Other layout tools

And if the guides aren't enough to help you layout the components the editor also provides a set of alignment tools for making components match width, height, alignment or spacing.

The editor also provides hints to assist layout as the components are moved or sized. The hints are shown briefly while moving or select components and connect edges of components that have matching coordinates. The components will by default snap to the coordinates of other components to self align. When JSE 6 is released we will add support for matching of the component baselines and user interface spacing, kind of like NetBeans's project Matisse.

Figure 6 - Spacing components in the editor

Using the GuideLayout outside of XUI

The GuideLayout can be used outside of XUI with a little work. However before the final release of XUI 2.0 we expect to have enhanced the API sufficient to make such use more convenient. The current API can be found here. Part II of this article describes use of the GuideLayout outside of XUI.

Further Enhancements

In future versions we also hope to extend the GuideLayout to include support for features such as alignment of baselines, autosizing columns (fit to say the maximum width of a column of labels) and some more advanced arrangements of the guides.


If you were logged in you could rate this article or add a comment.