Builder Xcessory facilitates working with layout and geometry management objects. With combinations of direct manipulation and specialized editors, Builder Xcessory provides WYSIWYG ("What You See Is What You Get") access to the powerful, but complex and otherwise difficult to use manager widgets-- most notably the Motif Form widget and the Java AWT objects with their various layout policies such as the GridBag.
Managing Your UI Layout
As you plan the layout of your user interface, you spend a large percentage of your time allowing for changes the end-user will make to the interface. These changes can be as simple as resizing a window, or as complex as changing fonts, the language used in your labels, and menus.
Generally, you can cede a certain amount of control to a container with a powerful (and typically complex) layout policy, or you can retain control over the layout. The latter approach results in a great deal of work on your part, or an interface with very limited flexibility. In practice, you will find some situations where you want to limit the flexibility and some situations where you want to use as much of the power from your UI toolkit as possible by using the more complex containers and layout policies.
Builder Xcessory has an invisible object placement grid that makes it easier to place and resize objects so that they are aligned. When you place, or move, an object into your interface, its upper-left hand corner snaps to the nearest grid point. When you use the mouse to resize an object in your interface, the edge that you are moving snaps to the nearest grid point.
To change the size, or resolution, of the Layout Grid, select the General tab of the User Preferences dialog (Browser:Options), and specify a value (in pixels) for the grid size in the Grid Units field.
To turn off the Layout Grid, deselect the Snap To Grid toggle from the Browser View menu.
Note: Changing the Grid size, or disabling the Grid has no effect on objects already placed in your interface.
Aligning and Distributing Objects
When you align a set of selected objects, you line up one edge or the center of the selected objects with that of some reference object. For example, to make a horizontal left alignment is to line up the left edges of all selected objects with the left edge of the object located farthest to the left on the interface. The selected objects are moved so that the left edge of every object lines up with that of the left-most object.
When you distribute a set of objects, you space them evenly without moving the outermost objects. For example, to distribute horizontal centers is to space the horizontal centers of all selected objects equally between the center of the left-most object and the center of the right-most object.
When you choose Java as your code generation language, you can only directly move or align objects (with the mouse, the Alignment Editor, etc.) if you have selected No Layout (in source code terms, foo.setLayout(null); ) for the parent. In all other cases, the layout policies of the parent object dictate the size and placement of the object.
Note: Frequently, geometry management policies of an object's parent dictate the size of the object. In these cases, the mouse, the placement grid, and the alignment menus and editors are all ignored.
You can rapidly align any set of existing objects with Builder Xcessory using the Align item from the Browser Edit menu (and also the MB3 Quick Access menu).
1. Select the objects you want to align with one of the following methods:
- · Search/Select Area in the Browser
- · Shift-MB1 Drag to circle the objects in the Browser, or your interface
- · Ctrl-MB1 to select or deselect individual objects
2. Select Align from the Browser Edit menu or MB3.
3. Select the desired alignment from the resulting menu.
- · Left, Right, Top, Bottom, Horizontal Center, Vertical Center
- · Alignment Editor
The Alignment Editor provides extensive control over the positions of your objects. You can both align and distribute your objects. The Alignment Editor also displays an example of your alignment and distribution options, allowing you to view the effects of your changes before you commit them.
Alignment Editor describes the elements of the Alignment Editor window:
The following sections describe other techniques for layouts.
To reorder the items in a menu, select Raise or Lower from the Browser Edit (or MB3 Quick Access) menu. The selected option moves up or down within its menu.
Place an object with Ctrl held down to create the object without setting its width and height resources. The object is sized according to a complex algorithm governed by its own sizing policies. For these policies, refer to the object's description in See Palette Objects .
You can also remove explicit height and width settings from an existing object by selecting Natural Size from Browser:Edit or the MB3 Quick Access menu.
Using Motif Geometry Managers
OSF/Motif contains a number of geometry managers that govern the layout and resize behavior of their children. They range from the straightforward and easy-to-use XmBulletinBoard, to the complex and difficult-to-use XmForm. Builder Xcessory helps you use these managers effectively, from experimenting with different managers, to selecting the appropriate manager, to fine-tuning your final choice of resource settings.
In general, to use the simple managers described in the following section, you create the manager, create the children, and, depending on the particular manager, move and resize the children directly with the mouse, or set resources on the manager using the Resource Editor.
The Motif BulletinBoard is the simplest of the Motif managers, and does not control the size or the position of its children. When you use a BulletinBoard with Builder Xcessory, you can take maximum advantage of direct manipulation. Using the mouse, the Layout Grid, and Alignment facilities with the BulletinBoard, what you see is exactly what you get. The flip side of this ease-of-use is that you'll need to manage the x, y, width, and height of all the children in your application code to deal with resize actions from the user. The BulletinBoard is most commonly used when such actions are disallowed, for example, in dialogs.
Hint: Many Builder Xcessory users begin a layout with a BulletinBoard, rather than paper and pencil, to get an initial idea of the screen. They then change the BulletinBoard (by editing the Class Name in the Resource Editor) to a more sophisticated container, such as a Form, and continue work on resize behavior. By changing the class, you maintain the rest of your interface.
The ScrolledWindow is typically used to provide a viewing area onto a larger widget. Its scrollbars are easily controlled from the Resource Editor.
Hint: It is often easier to create the ScrolledWindow's child before placing it in the ScrolledWindow, because Builder Xcessory does not allow scrolling in Build Mode. To reparent a widget, see Copying and Reparenting Widgets .
The MainWindow is frequently used as a top-level window and is designed to manage a MenuBar, a work area with scrollbars, a command area, and a message area. All of these children are optional. The MainWindow manages the size and position of these children, placing the menu bar at the top of the window, stretched to its full width, and placing the message area child at the base of the window, again stretching to its full width. The MainWindow places the command area child above, or below the work area child, and creates and manages the scrollbars on the work area for you.
The MainWindow automatically recognizes and manages the MenuBar. When you create a MenuBar, size does not matter, as a child of a MainWindow, Builder Xcessory automatically manages and sizes it correctly. Add PulldownMenus to the MenuBar and the MenuBar size is again set correctly.
The various MainWindow children are easy to handle with Builder Xcessory. Create the desired objects and place them as children of the MainWindow. Then use the Resource Editor to set resource values on the MainWindow to specify which child belongs in which area. For example, set the value of the workWindow resource to the desired widget instance name by typing the name directly into the field, or using an extended editor to choose the name from a list of the MainWindow children.
The ViewKit Application Framework supports the notion of a primary, or main window for an application. Specifically, it provides two classes, VkWindow and VkSimpleWindow. The basic element in both of these classes is the XmMainWindow widget, with the VkWindow also including a menu bar with several pre-built menus.
Typically, you never instantiate a VkWindow or VkSimpleWindow directly, rather, you build and use subclasses. If you use a Motif MainWindow directly from the Palette, rather than a ViewKit component, Builder Xcessory automatically detects this when generating ViewKit code and outputs a VkWindow or VkSimpleWindow as appropriate.
The Motif RowColumn manages its children into rows and columns. There are a number of resources, easily accessed through the Builder Xcessory Resource Editor, that control the exact layout.
In addition to the straightforward row-column layout, there are a number of special cases of the RowColumn, (some of which involve additional widgets) including the RadioBox, MenuBar, PulldownMenu, and PopupMenu. Builder Xcessory facilitates using these variations by providing individual Palette icons. Selecting the PulldownMenu Palette icon, for instance, automatically creates a CascadeButton, a RowColumn configured as a PushButton menu item.
Hint: To reorder the items in a RowColumn (any variation, including menus) use the Raise/Lower menu items on the Browser Edit menu or use the MB3 Quick Access menu.
Builder Xcessory helps you work effectively with menus. It automatically creates all of the necessary constituent parts for you, along with an initial PushButton. Then, whenever you have a menu selected, Builder Xcessory posts all of the menu items upon which you are able to perform normal Builder Xcessory functions, including drag and drop. This includes the PopupMenu, which is normally invisible.
You can disable this behavior with the Show Menu Children toggle on the Browser View menu.
Generally speaking, to use the managers described in the following sections (complex managers), you create the manager, create the children, and use the Resource Editor to set resources on both the manager, and the children . To simplify use of the most complex of these managers, the Form, Builder Xcessory graphically shows the constraints, or attachments, of all Form children and allows you to directly manipulate the attachments with the mouse.
Note: Constraint Resources are always listed after the normal resources in the Resource Editor. If the selected widget is not currently a child of a complex manager, no constraint resources are listed.
The Frame widget manages a WorkArea child and a Label child. The WorkArea child is surrounded by the Frame; the Label child is placed above the WorkArea child. The Frame automatically resizes itself to contain its WorkArea child. You specify which child is the label and which the WorkArea child by means of constraint resources on the children.
The PanedWindow places each of its children into its own vertically tiled region. Constraint resources on its children control their positions and preferred sizes.
Hint: Use the Resource Manager Widget menu to show and hide particular panes in the PanedWindow by managing and unmanaging the Pane's children.
The Form widget is probably the most powerful, but most complex Motif manager. It allows you to manage the layout and resize behavior of its children by setting constraint resources on its children. The large number of possible values for these constraints, and the interactions between them, are what make this widget difficult to use.
Builder Xcessory simplifies this for you by graphically depicting these constraints and allowing you to manipulate them directly with the mouse. You can also set them with the Resource Editor and its extended editors.
Each child of a Form widget has four constraint resources (attachment, offset, position, widget) for each of its four sides (left, right, top, bottom). These sixteen resources (for example, leftAttachment or bottomPosition) determine how the object behaves when the Form parent is resized.
Builder Xcessory provides attachment handles and the Attachment Editor (see Attachment Editor ) to assist you in setting Form constraint resources, as described in the following sections.
Hint: Save the interface before using the Attachment Editor. If unexpected changes occur when you make large changes in geometry, select Revert from the Browser Edit menu to reload the last saved version of your interface.
An attachment is a resource that binds an edge of an object to either an edge of another object or to a position in the Form.
When working with a Form widget, the order of the creation of its children can affect the resizing properties. For example, when attaching widgets side-to-side, the last widget created resizes when the Form resizes. Use Raise and Lower (from the Browser Edit menu or MB3) to alter the creation order of objects.
To change the attachment of an object edge, use one of the following methods:
· Click on an attachment handle, drag the attachment to the edge of another child of the form, and release MB1 to set the attachment.
· Hold down MB3 on an attachment handle and choose an attachment from the popup menu. Only attachments for the appropriate edge of the object are displayed.
· Select the object, update the Resource Editor, and set the constraint resources in their respective text fields.
A side's offset is the distance maintained between that side and its attachment.
A side's position is the relative x or y location to which that side is explicitly attached, and is expressed as a ratio with respect to theXmNfractionBase resource.
Note: The position can only be set if attachment is set to XmATTACH_POSITION.
To display the constraint resource values for an edge of any Form's child, follow these steps:
1. Hold down Ctrl.
2. Move the cursor over the Form child's attachment icon until the cursor takes the shape of the icon.
3. Hold down MB3.
Any attachment, offset, position and widget values not set to NULL are displayed.
To change the offset or position of an edge of an object that is the child of a Form, follow these steps:
1. Move the cursor over the object's attachment icon until the cursor takes the shape of the icon.
2. Hold down Ctrl + MB3.
3. Move the cursor to the left or right for a left or right edge, or up or down for a top or bottom edge. The value of the position or offset increments or decrements, depending on the edge being set and the direction the cursor is moved.
The EnhancementPak widget set, part of the BX PRO product, provides a number of manager widgets that simplify many geometry management tasks. Virtually all of the EnhancementPak widgets are used in the Builder Xcessory interface.
Note: You can experiment with the EnhancementPak widgets at any time by setting the Start with EPak Widgets toggle on the Behavior tab (Browser:Options: User Preferences), but you must license the libraries to compile and use an application built with them.
See See Palette Objects for more detailed information about EPak widgets.
Combines some of the features of RowColumn and Form, evenly distributing its children into a single row or column. ButtonBoxknows how to center a child. ButtonBoxes are used throughout Builder Xcessory and are found in most of its dialogs and extended editors.
Combines child objects with optional labels in separate columns, and allows you to specify their relative position.
Similar to RowColumn, IconBox adds the concept of an absolute cell position.
Manages its children into an indented list form. It is a class sibling of the Tree widget. The various icon groups on the Palette are managed by an Outline widget.
Note: Using the Outline widget for the Palette allows the user to hide a group.
Similar to the Motif PanedWindow, but allows horizontally-tiled panes in addition to vertically-tiled panes. Paned is used in the Browser and Resource Editor to control the layout of those windows.
A special purpose manager, Plotter manages any number of the various Plot types (Pie Plot, Bar Plot, etc.) included in EnhancementPak.
Similar to Motif ScrolledWindow, but used in conjunction with the Panner to provide two-dimensional scrolling, a more efficient way to navigate around a viewing region. Porthole is used in the Browser, allowing you to navigate through your instance and class trees.
Similar to Frame, Stretch provides the added functionality of allowing the end-user to resize the Stretch widget and its child with the mouse. Stretch is used in the Builder Xcessory Browser, allowing you to resize the Panner.
This container is a simple manager with the visual appearance of a stack of manila folders, and allows you to fit multiple interfaces into a limited space. Tabstack is used extensively in Builder Xcessory's preference dialogs and is seen frequently in Microsoft Windows interfaces.
Similar to Motif RowColumn, Toolbar adds the notion of toolbar groups, the ability for you to group sets of children together, and the Popup Labels feature, similar to Microsoft's WinTips. Toolbars are used in the Browser and the Resource Editor.
Manages its children into a tree layout, optionally giving the user the ability to collapse and expand sections of the tree. Tree is used in the Browser Interface hierarchy display area. This is evident in the Browser and several of the Manager windows.
Java Layouts
A number of layouts are available in AWT for arranging components in your application. Builder Xcessory allows you to work with these layouts intuitively.
When programming Java manually, use the following procedure to lay out and manage the objects in your interface:
1. Create the parent object (the container).
2. Create the children (the objects to be managed).
3. Create a layout object.
4. Pass the layout object to the parent.
5. Pass the children to the parent.
However, when using the powerful and flexible GridBagLayout, programming manually becomes time-consuming, as follows:
1. Create the parent object (the container).
2. Create the children (the objects to be managed).
3. Create the GridBagLayout (GBL) object.
4. Pass the GBL to the parent.
5. Create a GridBagConstraints (GBC) object.
6. Set the GBC values for a particular child.
7. Pass the GBC and the child to the GridBagLayout object.
8. Pass the child to the parent.
9. Repeat steps 5-8 for each child to be managed.
With Builder Xcessory, this is considerably simpler. With any layout, including the GridBagLayout, use the following procedure:
1. Create the parent object (the container) and the children (the objects to be managed).
2. Use the Resource Editor to set the desired layout (on the parent).
3. Use the Resource Editor to set the desired constraints (on each of the children).
Builder Xcessory automatically synthesizes all of this information to create the appropriate layout objects for you. You can change the layout, add children of any type at any time, or nest layouts. All changes are reflected immediately and automatically in your interface so you can see the results of your changes as you make them.
The four AWT containers for which you can specify a layout policy include:
· Frame
· Panel
· Applet
· Dialog
Builder Xcessory uses a default layout policy of No Layout for all four containers to help you when creating and placing children. In nearly all cases, you will select a specific layout policy. These policies are described briefly in the following sections.
Generally with Builder Xcessory, the container (or parent) has resources corresponding to the type of layout object created, and any information passed to the layout object's constructor. The children typically have resources related to the position or resize behavior of that particular child. These resources are treated as constraints and are listed last in the Resource Editor.
It is possible, though rare, to create a Java application that does not use a layout manager (similar to using a Motif Bulletin Board). Any object you place into a container with No Layout specified remains in its initial position and size. With Builder Xcessory, this is the only layout policy where you can manipulate objects directly with the mouse and various alignment facilities. The AWT method:
-
setBounds(int x, int y, int width, int height)
The Flow layout causes the container to line up its children horizontally. When room on one line is exhausted, the Flow layout creates an additional line for its children. You can specify how the Flow positions the children on each line: centered, left aligned, or right aligned.
Resizing the container results in the (possible) rearrangement of the children into however many rows are appropriate, but children are not resized.
Set the following resources for the container:
- Layout: Flow Layout
- Alignment: center|left|right
Children have the following constraints:
- None
The Border layout causes the container to place its children into five areas: north, south, east, west, and center (see Border Layout ). The borders are set first, with the remaining space taken up by the center child. Each area can have only one visible child.
Resizing the container does not change the thickness of the borders, but changes both the height and width of the "center" child.
Set the following resources for the container:
- Layout: Border Layout
Children have the following constraints:
The Card layout causes the container to place its children atop one another, providing show , first , last , next , and previousmethods to control which child is visible.
The card layout sizes its child to fill the entire space of the container. Resizing the container resizes its children.
Set the following resources for the container:
- Layout: Card Layout
Children have the following constraints:
- None
The Grid layout causes the container to manage its children into rows and columns. You specify how many rows and columns to create. Children are placed into the rows from left to right, one row at a time, in the order in which you add them to the container. All children are identically sized. Resizing the container resizes its children.
Set the following resources for the container:
- Layout: Grid Layout
- Columns: [integer]
- Rows: [integer]
Children have the following constraints:
- None
Hint: To change the order in which the children are laid out, use the Raise/Lower operations (Browser:Edit or MB3 Quick Access menu).
The GridBag is the most powerful and the most complex layout in the AWT (the only AWT layout object that requires its own, distinct constraints object). With the GridBag, you can control where each individual child is placed, how it is moved, and how it is resized.
Each child is placed at a cell position with the gridx and gridy resources. You can then specify how many columns wide and how many rows high each child is with the gridwidth and gridheight resources. The GridBag automatically calculates the total number of rows and columns.
Note: The GridBag automatically uses the fewest possible number of rows and columns. Specifying particular gridy and gridxvalues does not guarantee that the GridBag will work with that number of rows or columns.
Within each allocated position, you can specify whether or not the child should grow to fill extra space in the grid cell with the fillresource. This extra space might be present because the default size of the child is smaller than the cell size, or the space might become available when the container is resized. If a child is not set to fill the entire area available, you use the anchor resource to align the child within its grid cell.
For partial fills, use the resources ipadx , ipady , and the various insets . The ipad resources specify internal padding, that is, how much bigger than its default size the child should be. The insets specify external padding, in other words, margins.
The two most powerful constraints for GridBag children are weightx and weighty . While fill controls how the children grow to fill a grid cell, weightx and weighty control how the actual grid cells grow (or shrink) when the container is resized, that is, how new space is apportioned to the grid cells. Values for weightx and weighty are proportional. A value of 0.0 indicates that the cell does not grow (or shrink). A cell with a weight of 10 grows twice as much as a cell with a weight of 5. Cells with identical weights grow the same amount.
Set the following resources for the container:
- Layout: GridBag Layout
Children have the following constraints:
- Gridx: [integer]
- Gridy: [integer]
- Gridwidth: [integer]
- Gridheight: [integer]
- Fill: horizontal|vertical|both|none
-
Anchor:center|east|north|northeast|northwest|south|
southeast|southwest|west - Ipadx: [integer]
- Ipady: [integer]
- TopInset: [integer]
- RightInset: [integer]
- BottomInset: [integer]
- LeftInset: [integer]
- Weightx: [double]
- Weighty: [double]
Figures GridBag After Resize with All Weights Equal to Zero and GridBag After Resize with Weights as Indicated show the results of resizing a GridBag with weights set to 0 and non-zero, respectively.
Notice that with all the weights set to zero, the GridBag does not increase the size of any of its cells, but maintains the grid centered in the container.
When you add weights , the grid resizes in accordance to the weight values. Notice that fills now come into play, along withanchor positions.
Examining the weightx values, we see that objects A and D do not resize at all, but objects B and C do. Because neither B nor C is in column 0, that column does not resize. Column 1 resizes to take up all of the remaining space. Notice that B and C have different values for weightx . Because they are proportional to the other columns (column 0), the difference becomes irrelevant.
Looking at the weighty values, we see that the sole object (D) in the bottom row does not resize, but all others do resize. The rows occupied by object A take up 100% of the new space. The rows occupied by objects B and C share the new space equally.
The weight values are also be used by the GridBag, along with the object sizes, to calculate the initial row heights and column widths.