|
Oculus Layout System API Documentation November 25, 2002 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.oculustech.layout.OculusLayoutHelper
Overview:
OculusLayoutHelper provides a convenient interface for using the Oculus layout system. In general, it is the top level class via which one should create all layouts.
The Oculus Layout system uses the metaphor of nested boxes & grids to specify layouts. Each box is either vertically or horizontally oriented; grids are of fixed numbers of columns & rows (but columns and rows will dynamically size themselves appropriately). In general, it possible to get 90 percent of the layout that you want using only nested boxes, in combination with per-component stretching preferences. The remaining 10 percent can be accomplished by one of two means: the first is OculusGrid, which allows you to lay things out easily in a grid with arbitrary column and row sizes; the second is to add alignment constraints, which specify that certain components from diverse boxes should line up.
The entire Oculus layout system uses per-component stretching preferences, which are specified for both the X and Y dimensions. They may take on any of the following values:
OculusLayoutInfo.NO_STRETCH
OculusLayoutInfo.STRETCH_ONLY_TO_ALIGN
OculusLayoutInfo.ALIGNMENT_SPACE_STRETCHING
OculusLayoutInfo.CAN_BE_STRETCHED
OculusLayoutInfo.WANT_STRETCHED
No stretch means the component should not be stretched in the given dimension. Stretch only to align indicates that the component can be stretched along the auxiliary dimension of the box, but solely for the purpose of aligning the edges of the component to the edges of the box. (The auxillary dimension of a vertically oriented box is horizontal, and the auxillary dimension of a horizontally oriented box is vertical). Alignment space stretching only stretches components along the primary orientation of the box. This is used mainly for filler spaces to enforce alignment of other components. Can be stretched indicates that it's OK to grow and shrink the component in the given dimension. Want to be stretched indicates that it's not only okay to stretch and shrink the component, but that this component wants to receive all stretching available in its box, pre-empting any can-be-stretched components. See OculusLayoutConstraints.getDefaultConstraints for a list of default stretching preferneces for common Swing components.
When adding a component to a layout using the add method, you can specify stretching preferences in both the X and Y dimensions. If you don't specify stretching preferences, the system will assume reasonable defaults based on the type of component you've added. Stretching preferences are honored by OculusBox, and OculusGrid, and OculusLayout.
OculusLayoutHelper uses a cursor based system to assist you in laying out
complicated, nested structures. When you have created an OculusLayoutHelper,
an OculusBox is implicitly created, and the cursor is placed inside it. The
next call to the add
method will add the component at the
current cursor position, and advance the cursor (cursor advances to the left
for a horizontal box, and down for a vertical box; for grids, it advances
from left to right and then top to bottom). At any time, you can call
nestBox()
, which will nest a new OculusBox at the current cursor
position, and put the cursor inside of it. Future calls to add
,
then, will add the component into this new, nested OculusBox. When you have
finished adding components to the nested box, you can call the
parent()
method to pop the cursor into the parent box at the
position immediately following the nested box. Besides nesting Oculus Boxes,
you can also call nestGrid()
to nested a new OculusGrid at the
current cursor position, and put your cursor into it. Adding components will
then place them into the grid from left-to-right, top-to-bottom.
Let's consider an example, in which you want to lay out a list box, below which are add and remove buttons, and to the right of which are two labeled text fields. Your code might look like:
OculusLayoutHelper helper = new OculusLayoutHelper(OculusLayout.HORIZONTAL);
helper.nestBox(OculusLayout.VERTICAL);
{
helper.add(myListBox);
helper.nestBox(OculusLayout.HORIZONTAL);
{
helper.add(myAddButton);
helper.add(myRemoveButton);
helper.parent();
}
helper.parent();
}
helper.nestBox(OculusLayout.HORIZONTAL);
{
helper.setJustification(OculusLayout.JUSTIFY_CENTER);
helper.nestGrid(2,2);
{
helper.add(myLabel1);
helper.add(myTextField1);
helper.add(myLabel2);
helper.add(myTextField2);
helper.parent();
}
helper.parent();
}
JPanel myPanel = helper.getRoot();
The one interesting tidbit to notice in the code above is the use of
setJustification
. Both OculusGrids and OculusBoxes have a
notion of justification, however their notions are subtly different.
OculusGrid lets you specify vertical and horizontal justifications for each
grid cell, which determine how the contents of the grid cell are placed.
OculusBox lets you set the justification that is used for the auxillary
dimension of the box. Thus, setting the justification on a Horizontal box
controls how components are aligned vertically, and setting the justification
on a Vertical box controls how components are aligned horizontally. In order
to control the justification of a OculusBox along its primary dimension, you
have to use AlignmentSpaces.
An AlignmentSpace is a space component that grows to fill any left-over space
in its box that can't be taken up by stretching CAN_BE_STRETCHED and
WANT_STRETCHED components. If there are multiple AlignmentSpace components
in a box, they are made equal sizes such that together they take up all extra
space. To center a series of components along the primary dimensions of a
box, you simply put an AlignmentSpace before them, and then another one after
them. This is done with the addAlignmentSpacing()
method of
OculusLayoutHelper (an alternative method that does the same thing is
addFiller()
, a name many people find more intuitive).
Besides AlignmentSpaces, you can add spaces of fixed sizes by adding Spacing
components. Spacing components are regular components that render as empty
space. You can set their preferred, min, and max sizes, and establish their
stretching preferences just as with any other component. See the Spacing
component class for details. You can call addSpace()
on
OculusLayoutHelper to add a space component of a given size.
Another important feature of OculusBox-based layouts is the use of Alignment points. Alignment points mark corresponding positions in the layout of two or more boxes that should be made to line up. For instance, a common use of alignment points is to right-align labels against text widgets, keeping the text widgets all the same size regardless of the label length (grids are also frequently used for this purpose). For example, consider the following code:
OculusLayoutHelper helper = new OculusLayoutHelper(OculusLayout.HORIZONTAL);
helper.nestBox(OculusLayout.VERTICAL);
{
helper.nestBox(OculusLayout.HORIZONTAL);
{
helper.addFiller();
helper.add(new JLabel("Name:"));
helper.addAlignmentPoint();
helper.add(new JTextField("Doe, John"));
helper.addAlignmentPoint();
helper.add(new JLabel("(Last, First)"));
helper.parent();
}
helper.nestBox(OculusLayout.HORIZONTAL);
{
helper.addFiller();
helper.add(new JLabel("Address:"));
helper.addAlignmentPoint();
helper.add(new JTextField("123 Anywhere Street"));
helper.addAlignmentPoint();
helper.add(new JLabel("(No P.O. Boxes)"));
helper.parent();
}
helper.parent();
}
JPanel myPanel = helper.getRoot();
The corresponding alignment points in sibling boxes (boxes that share the same immediate parent) will be made to line up. Only Alignments Points in sibling boxes of opposite orientation to their common parent box are considered in computing the layout.
The final trick that can be used to tweak layouts as necessary is to specify that given edges of arbitrary components should align. The components can be anywhere in the layout, regardless of box/grid boundaries. The implementation will attempt to align the Aligned Component to the Align-to component by inserting space before the Aligned Component as necessary. Note that it will never insert space before the Align-to component, even if it can't satisfy the constraint any other way; in this latter case, the alignment will be ignored. Also note that the Align-to component must be added to the layout prior to the Aligned Component (forward references in the layout tree are not supported). It is suggested that this feature be used as sparingly as possible, due to its complexity and subtlety. Most layouts can be achieved solely with combinations of nested boxes and grids, and at most one or two alignment constraints.
Finally, the OculusLayoutHelper class has a few convenience methods, the most
commonly used of which is addBorder()
. addBorder()
adds either an arbitrary Border object or a TitledBorder it creates from a
string to the current container (in which the cursor currently resides).
This is a convenient way of putting a titled border around an area of your
layout.
Note that, without a valid license key, any program that uses the
OculusLayout API will run in demo mode and regularly pop up dialog boxes. To
avoid these dialogs, invoke the static method
OculusLayout.setLicenseNumber()
with a valid license key. Visit
www.javalayout.com to
purchase a license key.
OculusLayout.setLicenseNumber(java.lang.String)
,
OculusLayoutConstraints.getDefaultConstraints(java.awt.Component)
Field Summary | |
protected javax.swing.JComponent |
current
Current container, wherein cursor resides at moment. |
protected java.io.PrintStream |
debugOut
|
static int |
DEFAULT_ORIENTATION
|
protected OculusBox |
root
The root of the layout of this OculusLayoutHelper |
Constructor Summary | |
OculusLayoutHelper()
Empty constructor which creates a new OculusBox with HORIZONTAL orientation for a new root OculusBox. |
|
OculusLayoutHelper(int orientation)
Empty constructor which creates a new OculusBox. |
|
OculusLayoutHelper(OculusBox rootBox)
Constructs a new OculusLayoutHelper based in the given root box. |
Method Summary | |
java.awt.Component |
add(java.awt.Component c)
Same as addComponent(Component) |
void |
add(java.awt.Component[] c)
Adds all components in c to current container, incrementing cursor position between each as appropriate |
java.awt.Component |
add(java.awt.Component c,
java.awt.Component sameWidthAs,
java.awt.Component sameHeightAs)
Same as addComponent(c,sameWidthAs,sameHeightAs) |
java.awt.Component |
add(java.awt.Component c,
int xStretching,
int yStretching)
Same as addComponent(c,xStretching,yStretching) |
java.awt.Component |
add(java.awt.Component c,
int xStretching,
int yStretching,
java.awt.Component sameWidthAs,
java.awt.Component sameHeightAs)
Same as addComponent(c,xStretching,yStretching,sameWidthAs,sameHeightAs) |
java.awt.Component |
add(java.awt.Component c,
OculusLayoutInfo theOculusLayoutConstraints)
Same as addComponent(c,theOculusLayoutConstraints) |
AlignmentPointSpacing |
addAlignmentPoint()
Adds an AlignmentPointSpacing object at the current cursor position. |
AlignmentSpacing |
addAlignmentSpacing()
Same as addFiller() |
void |
addBorder(javax.swing.border.Border theBorder)
Adds given border to the current box. |
void |
addBorder(java.lang.String name)
Adds a titled border with the given name to the current box. |
java.awt.Component |
addComponent(java.awt.Component c)
Adds a new component at the current cursor position with the default stretching preferences. |
java.awt.Component |
addComponent(java.awt.Component c,
java.awt.Component sameWidthAs,
java.awt.Component sameHeightAs)
Adds a new component at the current cursor position that is the same width and/or height as the given other components. |
java.awt.Component |
addComponent(java.awt.Component c,
int xStretching,
int yStretching)
Adds a new component at the current cursor position with the given stretching preferences. |
java.awt.Component |
addComponent(java.awt.Component c,
int xStretching,
int yStretching,
java.awt.Component sameWidthAs,
java.awt.Component sameHeightAs)
Adds given component to this container with a new OculusLayoutInfo OculusLayoutConstraints object that specifies the given stretching and same-size-as preferences. |
java.awt.Component |
addComponent(java.awt.Component c,
OculusLayoutInfo theOculusLayoutConstraints)
Adds a new component at the current cursor position with the given OculusLayoutConstraints. |
AlignmentSpacing |
addFiller()
Adds a new AlignmentSpacingComponent at the current cursor position. |
AlignmentSpacing |
addLowPriorityAlignmentSpacing()
Adds especially low priority filler (alignment) spacing at current cursor position. |
Space |
addSpace(int pixels)
Same as addSpace(pixels,false) |
Space |
addSpace(int pixels,
boolean p_LastComponentInBox)
Adds a fixed-size space between previous component and the next one along the primary axis of the current box. |
AlignedComponentSpacing |
alignNextComponentTo(java.awt.Component alignToComponent,
int alignToEdge,
int alignedEdge)
Adds a new AlignedComponentSpacing at the current cursor position. |
protected void |
debugOutput(java.lang.String s)
Print to this layout helper's debug output stream, if any. |
javax.swing.JComponent |
getCurrentContainer()
returns the current Component relative to which all operations are interpreted by this helper |
int |
getInterComponentSpacing()
Get the intercomponent spacing of the current box/grid. |
OculusBox |
getRoot()
returns the root OculusBox constructed by this helper |
OculusBox |
nestBox(int orientation)
Nests a new OculusBox at the current cursor, and moves the cursor into it. |
OculusBox |
nestBox(int orientation,
int justification)
Nests a new OculusBox at the current cursor, and moves the cursor into it. |
OculusBox |
nestBoxAsTab(java.lang.String tabName,
int orientation)
Nests a box at the current cursor, which is presumed to be in a tabbed pane, setting the tab name as given. |
OculusBox |
nestBoxAsTab(java.lang.String tabName,
int orientation,
int justification)
Nests a box at the current cursor, which is presumed to be in a tabbed pane, setting the tab name as given. |
OculusBox |
nestBoxInSplitPane(java.lang.String location,
int orientation)
Nests a box at the current cursor, which is presumed to be in a split pane, setting the location as given. |
OculusBox |
nestBoxInSplitPane(java.lang.String location,
int orientation,
int justification)
Nests a box at the current cursor, which is presumed to be in a split pane, setting the location as given. |
javax.swing.JComponent |
nestContainer(javax.swing.JComponent container)
Nests the given new container into this layout at the current cursor position, and then moves the cursor into the given container. |
OculusGrid |
nestGrid(int columns,
int rows)
Nests a new OculusGrid at current cursor position, and moves the cursor into it at the 0,0 position. |
javax.swing.JSplitPane |
nestSplitPane()
Nests a new JSplitPane at the current cursor, and moves the cursor into it. |
javax.swing.JSplitPane |
nestSplitPane(int orientation)
Nests a new JSplitPane at the current cursor, and moves the cursor into it. |
javax.swing.JTabbedPane |
nestTabbedPane()
Nests a new JTabbedPane at the current cursor, and moves the cursor into it. |
javax.swing.JTabbedPane |
nestTabbedPane(int tabPlacement)
Nests a new JTabbedPane at the current cursor, and moves the cursor into it. |
void |
parent()
Pops the cursor to the next position in the parent box of the current box. |
protected void |
popCurrent()
Pops the last container off the stack into the current container variable |
protected void |
pushCurrent()
Pushes the current container variable onto the container stack |
void |
setDebugOutStream(java.io.PrintStream x)
Sets the debugging output stream of the current box/grid to the given PrintStream. |
void |
setGridCellJustification(int xJustification,
int yJustification)
|
void |
setInterComponentSpacing(int pixels)
Sets the intercomponent spacing to use for this box/grid, and all its nested boxes/grids. |
void |
setJustification(int justification)
|
void |
setLayoutHelperDebugOutStream(java.io.PrintStream x)
Sets the debugging output stream of this layout helper. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int DEFAULT_ORIENTATION
protected javax.swing.JComponent current
protected OculusBox root
protected transient java.io.PrintStream debugOut
Constructor Detail |
public OculusLayoutHelper()
public OculusLayoutHelper(int orientation)
orientation
- The orientation of the root Box. Either HORIZONTAL,
VERTICAL, SAME_AS_PARENT, or OPPOSITE_OF_PARENTpublic OculusLayoutHelper(OculusBox rootBox)
Method Detail |
public java.awt.Component addComponent(java.awt.Component c)
public java.awt.Component add(java.awt.Component c)
public void add(java.awt.Component[] c)
public java.awt.Component addComponent(java.awt.Component c, int xStretching, int yStretching)
public java.awt.Component add(java.awt.Component c, int xStretching, int yStretching)
public java.awt.Component addComponent(java.awt.Component c, java.awt.Component sameWidthAs, java.awt.Component sameHeightAs)
public java.awt.Component add(java.awt.Component c, java.awt.Component sameWidthAs, java.awt.Component sameHeightAs)
public java.awt.Component addComponent(java.awt.Component c, int xStretching, int yStretching, java.awt.Component sameWidthAs, java.awt.Component sameHeightAs)
public java.awt.Component add(java.awt.Component c, int xStretching, int yStretching, java.awt.Component sameWidthAs, java.awt.Component sameHeightAs)
public java.awt.Component addComponent(java.awt.Component c, OculusLayoutInfo theOculusLayoutConstraints)
public java.awt.Component add(java.awt.Component c, OculusLayoutInfo theOculusLayoutConstraints)
public AlignmentSpacing addLowPriorityAlignmentSpacing()
public AlignmentSpacing addAlignmentSpacing()
public AlignmentPointSpacing addAlignmentPoint()
public AlignmentSpacing addFiller()
public Space addSpace(int pixels, boolean p_LastComponentInBox)
Returns null if no space needs to be added to accomodate given pixel spacing (due to intercomponent spacing being big enough).
If this newly added space object is to be the last component in an OculusBox, pass true as the value of p_LastComponentInBox argument.
public Space addSpace(int pixels)
public void setInterComponentSpacing(int pixels)
public int getInterComponentSpacing()
public AlignedComponentSpacing alignNextComponentTo(java.awt.Component alignToComponent, int alignToEdge, int alignedEdge)
Note that the only thing the layout system can do to satisfy this constraint is to add space at the point in the layout where this AlignedComponentSpacing object is added. If it would have to add space elsewhere, this constraint will be ignored.
It is recommended that this feature be used sparingly; in many cases, the desired alignments will be better achieved using an OculusGrid.
alignToComponent
- the component to which the next component
placed in this box should be aligned.
REQUIRES: This component must come prior to this spacing in a depth-first
ordering of the component/container tree. (i.e., no forward references).alignToEdge
- the edge of the alignToComponent to which the
given edge of the next component placed in this box should be aligned.
This must be one of AlignedComponentSpacing.LEADING_EDGE, or
AlignedComponentSpacing.TRAILING_EDGE. Leading/trailing is relative
to the primary axis of the current box (not the alignToComponent's box).alignedEdge
- the edge of the next component to align with the
given edge of the alignToComponent. This must be one of
AlignedComponentSpacing.LEADING_EDGE, or
AlignedComponentSpacing.TRAILING_EDGE. Leading/trailing is relative
to the primary axis of the current box.public void addBorder(java.lang.String name)
public void addBorder(javax.swing.border.Border theBorder)
public OculusBox getRoot()
public javax.swing.JComponent getCurrentContainer()
public void setLayoutHelperDebugOutStream(java.io.PrintStream x)
protected void debugOutput(java.lang.String s)
public void setDebugOutStream(java.io.PrintStream x)
public OculusBox nestBox(int orientation, int justification)
public void setJustification(int justification)
public void setGridCellJustification(int xJustification, int yJustification)
public OculusGrid nestGrid(int columns, int rows)
public OculusBox nestBox(int orientation)
public javax.swing.JTabbedPane nestTabbedPane(int tabPlacement)
public javax.swing.JTabbedPane nestTabbedPane()
public OculusBox nestBoxAsTab(java.lang.String tabName, int orientation)
public OculusBox nestBoxAsTab(java.lang.String tabName, int orientation, int justification)
public javax.swing.JSplitPane nestSplitPane(int orientation)
public javax.swing.JSplitPane nestSplitPane()
public OculusBox nestBoxInSplitPane(java.lang.String location, int orientation)
public OculusBox nestBoxInSplitPane(java.lang.String location, int orientation, int justification)
public javax.swing.JComponent nestContainer(javax.swing.JComponent container)
public void parent()
protected void pushCurrent()
protected void popCurrent()
|
Oculus Layout System API Documentation November 25, 2002 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |