Oculus Layout System API Documentation
November 25, 2002

com.oculustech.layout
Class OculusLayout

java.lang.Object
  |
  +--com.oculustech.layout.OculusLayout
All Implemented Interfaces:
java.awt.LayoutManager, java.awt.LayoutManager2, OculusLayoutConstants, OculusLayoutInfo, java.io.Serializable

public class OculusLayout
extends java.lang.Object
implements java.awt.LayoutManager2, OculusLayoutConstants, OculusLayoutInfo, java.io.Serializable

For a detailed explanation of using the Oculus Layout system, see the docs for OculusLayoutHelper.

OculusLayout implements a Layout Manager that uses a nested boxes system of layout similar to javax.swing.Box, but with more control over how things are stretched, and the ability to align components that reside at different points in the box tree structure.

Invoke the static method OculusLayout.setLicenseNumber() with a valid license key to avoid the regular appearance of warning dialog boxes and to operate in registed mode. Visit www.javalayout.com to purchase a license key.

See Also:
Serialized Form

Field Summary
 java.io.PrintStream debugOut
           
 
Fields inherited from interface com.oculustech.layout.OculusLayoutConstants
BOTTOM_JUSTIFY, CENTER, HORIZONTAL, INFINITY, JUSTIFY_BOTTOM, JUSTIFY_CENTER, JUSTIFY_LEFT, JUSTIFY_RIGHT, JUSTIFY_TOP, LEFT_JUSTIFY, RIGHT_JUSTIFY, TOP_JUSTIFY, VERTICAL
 
Fields inherited from interface com.oculustech.layout.OculusLayoutInfo
ALIGNED_COMPONENT_SPACING, ALIGNMENT_SPACE_STRETCHING, CAN_BE_STRETCHED, LOW_PRIORITY_ALIGNMENT_SPACE_STRETCHING, MAX_STRETCHING_PREFERENCE, NO_STRETCH, START_NON_POINT_ALIGNMENT_STRETCHING_HERE, START_NORMAL_STRETCHING, START_STRETCHING_HERE, STRETCH_ONLY_TO_ALIGN, WANT_STRETCHED
 
Constructor Summary
OculusLayout()
          Default constructor here for Forte's sake.
OculusLayout(java.awt.Container target, int orientation)
          Same as above, but with default justification of LEFT for vertical boxes, and TOP for horizontal ones.
OculusLayout(java.awt.Container target, int orientation, int justification)
          Creates a layout manager that will lay out components either left to right, top to bottom, opposite to its parent.
OculusLayout(java.awt.Container target, int orientation, int justification, java.io.PrintStream debugOut)
          Same as above, but allows one to specify a debugging output stream.
 
Method Summary
 void addLayoutComponent(java.awt.Component comp, java.lang.Object constraints)
          Called by Container when a new component is added to it.
 void addLayoutComponent(java.lang.String name, java.awt.Component comp)
          Not used by this class.
static int arrayMax(int[] values)
           
static int arrayMax(int[] values, int startIndex, int endIndex)
           
static int arraySum(javax.swing.SizeRequirements[] values, int field)
           
static int arraySum(javax.swing.SizeRequirements[] values, int field, int startIndex, int endIndex)
           
protected  void clearDesiredAlignmentPointPositions()
          Resets the cached info on desired alignment point positions for this layout's container
 void clearSizePreferencesCache()
          Clears the cached sizing computations for this layout manager, prior to its having been stretched.
protected  void debugOutput(java.lang.String s)
           
protected  void debugOutput(java.lang.String s, boolean p_newline)
           
 java.awt.Point getAbsoluteComponentPosition(java.awt.Component c)
          This function does its best to return the absolute position of a given component relative to its top-level container based on what is thus far known of the layout.
protected  int[] getAlignmentPointPositions()
          Returns an array of the predicted/current positions of the alignment points in this layout's container.
protected  javax.swing.SizeRequirements[] getAlignmentRegionExtents()
          Returns a list of SizeRequirements denoting the min/max/preferred sizes of each of the regions that this layout's container's alignment points divide it into
protected  int[] getAlignmentRegionStretchings()
          Returns a list of stretching prefs of each of the regions that this layout's container's alignment points divide it into
 int getComponentHeight(java.awt.Component c)
          Returns the anticipated height of a given component in this container or another container, taking into account under-way OculusLayout computations.
static int getComponentIndex(java.awt.Component x)
          Returns the index of the given component in its containers components list.
 int getComponentWidth(java.awt.Component c)
          Returns the anticipated width of a given component in this container or another container, taking into account under-way OculusLayout computations.
 int getInterComponentSpacing()
          Returns this layout manager's intercomponent spacing.
 int getJustification()
          Returns this layout manager's justification.
 float getLayoutAlignmentX(java.awt.Container target)
          This layout always center things, unless forced to do otherwise.
 float getLayoutAlignmentY(java.awt.Container target)
          This layout always centers things, unless forced to do otherwise.
static java.lang.String getLicenseNumber()
          Returns the license number for the OculusLayout system previously set by setLicenseNumber.
 int getNonce()
          Returns a unique integer identifying this OculusLayout instance.
protected  int getNumberAlignmentPoints()
          Returns the number of AlignmentPointSpacings in this layout's container.
static int getOppositeOrientation(int orientation)
          If orientation is horizontal, returns vertical, otherwise returns horizontal
 int getOrientation()
          Get the orientation for this layout
protected  int getRegionEndIndex(int regionIndex)
          Returns the ending component index of the region given by regionIndex.
protected  int getRegionStartIndex(int regionIndex)
          Returns the starting component index of the region given by regionIndex.
 java.awt.Point getRelativeComponentPosition(java.awt.Component x)
          returns the given component's position relative to the container associated with this layout manager.
 java.awt.Component getSameHeightAs()
          Gets the component whose height is being matched.
 java.awt.Component getSameWidthAs()
          Gets the component whose height is being matched.
 int getXPreference()
          returns the X-Stretching preferences for this layout.
 int getXPreference(java.awt.Container target)
          returns the X-Stretching preferences for this layout.
 int getYPreference()
          returns the Y-Stretching preferences for this layout.
 int getYPreference(java.awt.Container target)
          returns the Y-Stretching preferences for this layout.
protected  void invalidateDescendentsSizePreferences()
          Invalidates cached size/layout computations in all descendents of this layout's container (but not this container itself).
 void invalidateLayout(java.awt.Container target)
          Indicates that a child has changed its layout related information, and thus any cached calculations should be flushed.
protected  void invalidateOthersSizePreferences()
          This function clears the size preferences cache for all containers that come later than this one in a depth-first ordering of the tree starting from this containers root.
 void layoutContainer(java.awt.Container target)
          Called by the AWT when the specified container needs to be laid out.
 java.awt.Dimension maximumLayoutSize(java.awt.Container target)
          Returns the maximum dimensions the target container can use to lay out the components it contains.
 java.awt.Dimension minimumLayoutSize(java.awt.Container target)
          Returns the minimum dimensions needed to lay out the components contained in the specified target container.
 java.awt.Dimension preferredLayoutSize(java.awt.Container target)
          Returns the preferred dimensions for this layout, given the components in the specified target container.
 void removeLayoutComponent(java.awt.Component comp)
          Called by Container when a component is removed.
protected  void setContainsAlignToComponent(boolean pContainsAlignToComponent)
          Inform Layout manager that it contains a component to which another component is aligned.
 void setDebugOutStream(java.io.PrintStream x)
          Sets the PrintStream to output debugging information to.
protected  void setDesiredAlignmentPointPosition(int index, int pcoord)
          Sets the desired position for the specified alignment point.
 void setInterComponentSpacing(int icspacing)
          Sets this layout manager's intercomponent spacing.
 void setJustification(int newJustification)
          Sets this layout manager's justification.
static void setLicenseNumber(java.lang.String ln)
          Sets license number for OculusLayout System.
 void setOrientation(int orientation)
          Sets the orientation for this layout.
static void storeMaximums(int[] destination, int[] other)
          For every value in destination, stores the maximum of the value in destination or the corresponding value in other into destination
static void storeMaximums(int[] destination, int[] other, int startIndex, int endIndex)
          For every value in destination within given index range, stores the maximum of the value in destination or the corresponding value in other into destination
static void storeMaximums(javax.swing.SizeRequirements[] destination, javax.swing.SizeRequirements[] other)
          For each of preferred, minimum, and maximum (independently), for every value in destination, stores the maximum of the value in destination or the corresponding value in other into destination
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

debugOut

public transient java.io.PrintStream debugOut
Constructor Detail

OculusLayout

public OculusLayout()
Default constructor here for Forte's sake. This layout will irreversibly connect itself to the first container that is passed to one of its methods. It will be a horizontal container. Use OculusVerticalLayout, which is a trivial extension of this class, to make vertical layouts in Forte.

OculusLayout

public OculusLayout(java.awt.Container target,
                    int orientation,
                    int justification)
Creates a layout manager that will lay out components either left to right, top to bottom, opposite to its parent. as specified in the axis parameter.
Parameters:
target - the container that needs to be laid out
orientation - the axis to lay out components along. For left-to-right layout, specify OculusLayout.HORIZONTAL; for top-to-bottom layout, specify OculusLayout.VERTICAL; for opposite-of-parent layout, specify OculusLayout.OPPOSITE (opposite not yet implemented);
Throws:
java.awt.AWTError - if the value of axis is invalid

OculusLayout

public OculusLayout(java.awt.Container target,
                    int orientation)
Same as above, but with default justification of LEFT for vertical boxes, and TOP for horizontal ones.

OculusLayout

public OculusLayout(java.awt.Container target,
                    int orientation,
                    int justification,
                    java.io.PrintStream debugOut)
Same as above, but allows one to specify a debugging output stream.
Parameters:
dbg - the stream to which debugging messages should be sent, null if none
Method Detail

getNonce

public int getNonce()
Returns a unique integer identifying this OculusLayout instance. (Used primarily for debugging purposes).

setDebugOutStream

public void setDebugOutStream(java.io.PrintStream x)
Sets the PrintStream to output debugging information to.

setOrientation

public void setOrientation(int orientation)
Sets the orientation for this layout.

getOrientation

public int getOrientation()
Get the orientation for this layout

debugOutput

protected void debugOutput(java.lang.String s)

debugOutput

protected void debugOutput(java.lang.String s,
                           boolean p_newline)

setInterComponentSpacing

public void setInterComponentSpacing(int icspacing)
Sets this layout manager's intercomponent spacing. Default is 3

getInterComponentSpacing

public int getInterComponentSpacing()
Returns this layout manager's intercomponent spacing.

setJustification

public void setJustification(int newJustification)
Sets this layout manager's justification. Default is TOP for vertical boxes, LEFT for horizontal boxes.

getJustification

public int getJustification()
Returns this layout manager's justification.

invalidateLayout

public void invalidateLayout(java.awt.Container target)
Indicates that a child has changed its layout related information, and thus any cached calculations should be flushed. TAKEN OUT: This needs also to invalidate the layouts of this containers children, since the AWT doesn't automatically do this due to dumbness.
Specified by:
invalidateLayout in interface java.awt.LayoutManager2
Parameters:
target - the affected container
Throws:
java.awt.AWTError - if the target isn't the container specified to the BoxLayout constructor

addLayoutComponent

public void addLayoutComponent(java.lang.String name,
                               java.awt.Component comp)
Not used by this class.
Specified by:
addLayoutComponent in interface java.awt.LayoutManager
Parameters:
name - the name of the component
comp - the component

removeLayoutComponent

public void removeLayoutComponent(java.awt.Component comp)
Called by Container when a component is removed.
Specified by:
removeLayoutComponent in interface java.awt.LayoutManager
Parameters:
comp - the component

addLayoutComponent

public void addLayoutComponent(java.awt.Component comp,
                               java.lang.Object constraints)
Called by Container when a new component is added to it.
Specified by:
addLayoutComponent in interface java.awt.LayoutManager2
Parameters:
comp - the component
constraints - constraints

preferredLayoutSize

public java.awt.Dimension preferredLayoutSize(java.awt.Container target)
Returns the preferred dimensions for this layout, given the components in the specified target container.
Specified by:
preferredLayoutSize in interface java.awt.LayoutManager
Parameters:
target - the container that needs to be laid out
Returns:
the dimensions >= 0 && <= INFINITY
Throws:
java.awt.AWTError - if the target isn't the container specified to the BoxLayout constructor
See Also:
Container, minimumLayoutSize(java.awt.Container), maximumLayoutSize(java.awt.Container)

minimumLayoutSize

public java.awt.Dimension minimumLayoutSize(java.awt.Container target)
Returns the minimum dimensions needed to lay out the components contained in the specified target container.
Specified by:
minimumLayoutSize in interface java.awt.LayoutManager
Parameters:
target - the container that needs to be laid out
Returns:
the dimensions >= 0 && <= INFINITY
Throws:
java.awt.AWTError - if the target isn't the container specified to the BoxLayout constructor
See Also:
preferredLayoutSize(java.awt.Container), maximumLayoutSize(java.awt.Container)

maximumLayoutSize

public java.awt.Dimension maximumLayoutSize(java.awt.Container target)
Returns the maximum dimensions the target container can use to lay out the components it contains.
Specified by:
maximumLayoutSize in interface java.awt.LayoutManager2
Parameters:
target - the container that needs to be laid out
Returns:
the dimenions >= 0 && <= INFINITY
Throws:
java.awt.AWTError - if the target isn't the container specified to the BoxLayout constructor
See Also:
preferredLayoutSize(java.awt.Container), minimumLayoutSize(java.awt.Container)

getLayoutAlignmentX

public float getLayoutAlignmentX(java.awt.Container target)
This layout always center things, unless forced to do otherwise.
Specified by:
getLayoutAlignmentX in interface java.awt.LayoutManager2
Parameters:
target - the container
Returns:
0.5 always

getLayoutAlignmentY

public float getLayoutAlignmentY(java.awt.Container target)
This layout always centers things, unless forced to do otherwise.
Specified by:
getLayoutAlignmentY in interface java.awt.LayoutManager2
Parameters:
target - the container
Returns:
0.5 alwyas

getXPreference

public int getXPreference(java.awt.Container target)
returns the X-Stretching preferences for this layout. See OculusLayoutInfo for more information.

getXPreference

public int getXPreference()
returns the X-Stretching preferences for this layout. See OculusLayoutInfo for more information.
Specified by:
getXPreference in interface OculusLayoutInfo
Following copied from interface: com.oculustech.layout.OculusLayoutInfo
Returns:
One of stretching preference final ints defined in OculusLayoutInfo

getYPreference

public int getYPreference(java.awt.Container target)
returns the Y-Stretching preferences for this layout. See OculusLayoutInfo for more information.

getYPreference

public int getYPreference()
returns the Y-Stretching preferences for this layout. See OculusLayoutInfo for more information.
Specified by:
getYPreference in interface OculusLayoutInfo
Following copied from interface: com.oculustech.layout.OculusLayoutInfo
Returns:
One of stretching preference final ints defined in OculusLayoutInfo

getSameHeightAs

public java.awt.Component getSameHeightAs()
Gets the component whose height is being matched.
Specified by:
getSameHeightAs in interface OculusLayoutInfo
Returns:
The component whose height is being matched.

getSameWidthAs

public java.awt.Component getSameWidthAs()
Gets the component whose height is being matched.
Specified by:
getSameWidthAs in interface OculusLayoutInfo
Returns:
The component whose height is being matched.

layoutContainer

public void layoutContainer(java.awt.Container target)
Called by the AWT when the specified container needs to be laid out.
Specified by:
layoutContainer in interface java.awt.LayoutManager
Parameters:
target - the container to lay out
Throws:
java.awt.AWTError - if the target isn't the container specified to the BoxLayout constructor

getComponentIndex

public static int getComponentIndex(java.awt.Component x)
Returns the index of the given component in its containers components list.

getComponentWidth

public int getComponentWidth(java.awt.Component c)
Returns the anticipated width of a given component in this container or another container, taking into account under-way OculusLayout computations.

getComponentHeight

public int getComponentHeight(java.awt.Component c)
Returns the anticipated height of a given component in this container or another container, taking into account under-way OculusLayout computations.

getAbsoluteComponentPosition

public java.awt.Point getAbsoluteComponentPosition(java.awt.Component c)
This function does its best to return the absolute position of a given component relative to its top-level container based on what is thus far known of the layout. Will be accurate after a container is completely laid out, and will be best-knowledge-so-far up until that time.

getRelativeComponentPosition

public java.awt.Point getRelativeComponentPosition(java.awt.Component x)
returns the given component's position relative to the container associated with this layout manager. REQUIRES: x be in same component tree as myContainer.

setContainsAlignToComponent

protected void setContainsAlignToComponent(boolean pContainsAlignToComponent)
Inform Layout manager that it contains a component to which another component is aligned. This let's the layout manager know that it should invalidate the cached size computations of all layout managers that come later in a depth-first sort order.

clearSizePreferencesCache

public void clearSizePreferencesCache()
Clears the cached sizing computations for this layout manager, prior to its having been stretched. Has no effect once stretching has begun.

invalidateOthersSizePreferences

protected void invalidateOthersSizePreferences()
This function clears the size preferences cache for all containers that come later than this one in a depth-first ordering of the tree starting from this containers root.

invalidateDescendentsSizePreferences

protected void invalidateDescendentsSizePreferences()
Invalidates cached size/layout computations in all descendents of this layout's container (but not this container itself).

getAlignmentPointPositions

protected int[] getAlignmentPointPositions()
Returns an array of the predicted/current positions of the alignment points in this layout's container. Positions are pcoords, that is they start at zero for this container (regardless of insets), and increase along this containers' primary axis. Returns null if this container has no alignment points.

getNumberAlignmentPoints

protected int getNumberAlignmentPoints()
Returns the number of AlignmentPointSpacings in this layout's container.

setDesiredAlignmentPointPosition

protected void setDesiredAlignmentPointPosition(int index,
                                                int pcoord)
Sets the desired position for the specified alignment point. If the index is greater than the number of alignment points in this container, call is ignored.

clearDesiredAlignmentPointPositions

protected void clearDesiredAlignmentPointPositions()
Resets the cached info on desired alignment point positions for this layout's container

getAlignmentRegionExtents

protected javax.swing.SizeRequirements[] getAlignmentRegionExtents()
Returns a list of SizeRequirements denoting the min/max/preferred sizes of each of the regions that this layout's container's alignment points divide it into

getRegionEndIndex

protected int getRegionEndIndex(int regionIndex)
Returns the ending component index of the region given by regionIndex. Regions are implicitly defined by the AlignmentPointSpacing objects in this container. Note that there will be 1 more region than there is AlignmentPointSpacing objects (a single fencepost divides the fence into two sections, two fenceposts divide it into three, etc.).

getRegionStartIndex

protected int getRegionStartIndex(int regionIndex)
Returns the starting component index of the region given by regionIndex. Regions are implicitly defined by the AlignmentPointSpacing objects in this container. Note that there will be 1 more region than there is AlignmentPointSpacing objects

getAlignmentRegionStretchings

protected int[] getAlignmentRegionStretchings()
Returns a list of stretching prefs of each of the regions that this layout's container's alignment points divide it into

getOppositeOrientation

public static int getOppositeOrientation(int orientation)
If orientation is horizontal, returns vertical, otherwise returns horizontal

storeMaximums

public static void storeMaximums(int[] destination,
                                 int[] other,
                                 int startIndex,
                                 int endIndex)
For every value in destination within given index range, stores the maximum of the value in destination or the corresponding value in other into destination

storeMaximums

public static void storeMaximums(int[] destination,
                                 int[] other)
For every value in destination, stores the maximum of the value in destination or the corresponding value in other into destination

storeMaximums

public static void storeMaximums(javax.swing.SizeRequirements[] destination,
                                 javax.swing.SizeRequirements[] other)
For each of preferred, minimum, and maximum (independently), for every value in destination, stores the maximum of the value in destination or the corresponding value in other into destination

arrayMax

public static int arrayMax(int[] values,
                           int startIndex,
                           int endIndex)

arrayMax

public static int arrayMax(int[] values)

arraySum

public static int arraySum(javax.swing.SizeRequirements[] values,
                           int field)

arraySum

public static int arraySum(javax.swing.SizeRequirements[] values,
                           int field,
                           int startIndex,
                           int endIndex)

setLicenseNumber

public static void setLicenseNumber(java.lang.String ln)
Sets license number for OculusLayout System. Without a valid license, the OculusLayout system will operate in demo mode, and pop up warning dialogs on a regular basis.

getLicenseNumber

public static java.lang.String getLicenseNumber()
Returns the license number for the OculusLayout system previously set by setLicenseNumber. If no license has been set, returns "EVAL".

Oculus Layout System API Documentation
November 25, 2002

Copyright 2001-2002 Oculus Technologies Corporation. 103 Broad Street, 5th Floor,
Boston, Massachusetts, 02110, U.S.A. All Rights Reserved.