Oculus Layout System API Documentation
November 25, 2002

com.oculustech.layout
Class OculusGrid

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--javax.swing.JPanel
                          |
                          +--com.oculustech.layout.OculusGrid
All Implemented Interfaces:
javax.accessibility.Accessible, java.awt.image.ImageObserver, java.awt.MenuContainer, OculusLayoutConstants, OculusLayoutInfo, java.io.Serializable

public class OculusGrid
extends javax.swing.JPanel
implements OculusLayoutInfo, OculusLayoutConstants

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

This container implements an easy-to-use grid that dynamically sizes its rows and columns so as to accomodate their contents, paying attention to the stretching preferences of the components in each cell (as defined either by the components associated OculusLayoutInfo object, by the component itself if it implements OculusLayoutInfo, or as determined by the default stretching preferences defined by OculusLayoutConstraints.getDefaultConstraints()).

Rows in the grid will be tall enough to accomodate the tallest component in the row; the row will be stretched according to the maximum stretching preference of any component in the row. Likewise, columns in the grid will be wide enough to accomodate the widest component in the column; the column will be stretched according to the maximum stretching preference of any component in the column.

By default the contents of a grid cell are left justified and centered vertically, however grid cell justifications may be set on a cell-by-cell basis in both the horizontal and vertical directions.

See Also:
OculusLayoutHelper, OculusLayoutInfo, OculusLayoutConstraints, Serialized Form

Inner classes inherited from class javax.swing.JPanel
javax.swing.JPanel.AccessibleJPanel
 
Inner classes inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Inner classes inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Inner classes inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent
 
Field Summary
 java.io.PrintStream debugOut
           
static int DEFAULT_CELL_SPACING
          The default number of pixels between cells in the grid.
static int DEFAULT_JUSTIFICATION
           
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
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
 
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 java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
OculusGrid(int numOfCols, int numOfRows)
          Constructor for grid of given size
 
Method Summary
 java.awt.Component add(java.awt.Component comp)
          Adds the given component to the grid at the current cursor position, and then increments the cursor position.
 java.awt.Component add(java.awt.Component comp, int index)
          Override this method defined in Container so as to throw an exception since this method doesn't make sense for this object.
 java.awt.Component add(java.awt.Component comp, int column, int row)
          Adds a component to the grid, with the default justifications.
 java.awt.Component add(java.awt.Component comp, int column, int row, int horizontalJustification, int verticalJustification)
          Adds a component to the grid, with the specified justifications.
 void add(java.awt.Component comp, java.lang.Object constraints)
          Adds the given component to the grid at the current cursor position, and then increments the cursor position.
 void add(java.awt.Component comp, java.lang.Object constraints, int index)
          Override this method defined in Container so as to throw an exception since this method doesn't make sense for this object.
 java.awt.Component add(java.awt.Component comp, OculusLayoutInfo cont, int column, int row)
          Adds a component to the grid, with the given constraints.
 java.awt.Component add(java.awt.Component comp, OculusLayoutInfo cont, int column, int row, int horizontalJustification, int verticalJustification)
          Adds a component to the grid, with the specified justifications.
 java.awt.Component add(java.lang.String name, java.awt.Component comp)
          Override this method defined in Container so as to throw an exception since this method doesn't make sense for this object.
static double arraySum(int[] inp)
          Determines the sum of all the integers in inp, truncating summation at maximum of OculusLayout.INFINITY.
protected  void debugOutput(java.lang.String s)
           
 void doLayout()
          Overrides the container doLayout method.
 int getCellSpacing()
          Returns the number of pixels to be placed between cells in the grid.
 int getColumnCount()
          Returns the number of columns in this grid.
 java.awt.Component getComponentAt(int column, int row)
          Returns the component at the given column,row in this grid.
 int[] getComponentLocation(java.awt.Component component)
          Returns the column,row of the given component in this grid.
 java.awt.Dimension getMaximumSize()
          Overrides the component method.
 java.awt.Dimension getMinimumSize()
          Overrides the component method.
 java.awt.Dimension getPreferredSize()
          Overrides the component method.
 int getRowCount()
          Returns the number of rows in this grid.
 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()
          Determines the greatest X preference for all of the components in the grid and returns that preference.
 int getYPreference()
          Determines the greatest Y preference for all of the components in the grid and returns that preference.
 void invalidate()
          Overrides the JPanel.invalidate().
 void layout()
          Overrides the container layout method.
 void setCellSpacing(int numberOfPixels)
          Changes the number of pixels between cells in the grid.
 void setDebugOutStream(java.io.PrintStream x)
          Sets the PrintStream to output debugging information to.
 void setJustification(int column, int row, int xJustification, int yJustification)
          Sets the justification of the given grid cell.
 void setNextJustification(int xJustification, int yJustification)
          Sets the justification to be used for adding the next component.
 void setSameHeightAs(java.awt.Component c)
           
 void setSameWidthAs(java.awt.Component c)
           
 void setSize(int cols, int rows)
          Resize the grid to the given dimensions, keeping existing contents where possible.
 void setXJustification(int column, int row, int xJustification)
          Sets the justification of the given grid cell.
 void setYJustification(int column, int row, int yJustification)
          Sets the justification of the given grid cell.
 
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUIClassID, paramString, updateUI
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getNextFocusableComponent, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getVerifyInputWhenFocusTarget, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, hide, isDoubleBuffered, isFocusCycleRoot, isFocusTraversable, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processFocusEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
addContainerListener, addImpl, countComponents, deliverEvent, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentCount, getComponents, getLayout, insets, isAncestorOf, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setLayout, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, show, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_JUSTIFICATION

public static final int DEFAULT_JUSTIFICATION

DEFAULT_CELL_SPACING

public static final int DEFAULT_CELL_SPACING
The default number of pixels between cells in the grid.

debugOut

public transient java.io.PrintStream debugOut
Constructor Detail

OculusGrid

public OculusGrid(int numOfCols,
                  int numOfRows)
Constructor for grid of given size
Parameters:
numOfRows - The number of rows the grid has.
numOfCols - The number of columns the grid has.
Method Detail

setSize

public void setSize(int cols,
                    int rows)
Resize the grid to the given dimensions, keeping existing contents where possible. It is up to the user to call revalidate and repaint after resizing a grid (and then adding whatever to it as necessary).
Overrides:
setSize in class java.awt.Component

getColumnCount

public int getColumnCount()
Returns the number of columns in this grid.

getRowCount

public int getRowCount()
Returns the number of rows in this grid.

setDebugOutStream

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

debugOutput

protected void debugOutput(java.lang.String s)

setNextJustification

public void setNextJustification(int xJustification,
                                 int yJustification)
Sets the justification to be used for adding the next component. After adding this next component, the default justifications will revert to the built-in defaults. This function is primarily for use from OculusLayoutHelper.

add

public java.awt.Component add(java.awt.Component comp)
                       throws java.lang.RuntimeException
Adds the given component to the grid at the current cursor position, and then increments the cursor position.
Overrides:
add in class java.awt.Container
Parameters:
comp - The component to be added
Returns:
value of parameter comp

add

public java.awt.Component add(java.awt.Component comp,
                              int index)
                       throws java.lang.RuntimeException
Override this method defined in Container so as to throw an exception since this method doesn't make sense for this object.
Overrides:
add in class java.awt.Container
Parameters:
comp - The component that won't be added.
index - Won't be used.
Returns:
Won't ever returned (throws RuntimeException).

add

public void add(java.awt.Component comp,
                java.lang.Object constraints)
         throws java.lang.RuntimeException
Adds the given component to the grid at the current cursor position, and then increments the cursor position.
Overrides:
add in class java.awt.Container
Parameters:
comp - the component to be added.
constraints - its associated constrains (should implement OculusLayoutInfo)

add

public void add(java.awt.Component comp,
                java.lang.Object constraints,
                int index)
         throws java.lang.RuntimeException
Override this method defined in Container so as to throw an exception since this method doesn't make sense for this object.
Overrides:
add in class java.awt.Container
Parameters:
comp - The component that won't be added.
constraints - Doesn't matter.
index - Doesn't matter.

add

public java.awt.Component add(java.lang.String name,
                              java.awt.Component comp)
                       throws java.lang.RuntimeException
Override this method defined in Container so as to throw an exception since this method doesn't make sense for this object.
Overrides:
add in class java.awt.Container
Parameters:
name - Doesn't matter.
comp - Doesn't matter.
Returns:
Doesn't matter.

add

public java.awt.Component add(java.awt.Component comp,
                              int column,
                              int row)
                       throws java.lang.ArrayIndexOutOfBoundsException
Adds a component to the grid, with the default justifications. The cell indexes start at 0.
Parameters:
comp - Component to be added to a cell.
row - Cell row where component will go.
column - Cell column where component will go.
Returns:
value of parameter comp

add

public java.awt.Component add(java.awt.Component comp,
                              int column,
                              int row,
                              int horizontalJustification,
                              int verticalJustification)
                       throws java.lang.ArrayIndexOutOfBoundsException
Adds a component to the grid, with the specified justifications. If the component implements OculusLayoutInfo then its stretching constraints are used. Otherwise default stretching constraints are used.
Parameters:
comp - Component to be added to a cell.
row - Cell row where component will go.
column - Cell column where component will go.
horizontalJustification - Horizontal justification.
verticalJustication - Vertical justification.
Returns:
value of parameter comp

add

public java.awt.Component add(java.awt.Component comp,
                              OculusLayoutInfo cont,
                              int column,
                              int row,
                              int horizontalJustification,
                              int verticalJustification)
                       throws java.lang.ArrayIndexOutOfBoundsException
Adds a component to the grid, with the specified justifications. Given constraints are used for stretching.
Parameters:
comp - Component to be added to a cell.
cont - The constraints for comp, if comp is an instance of OculusLayoutInfo, this field is ignored
row - Cell row where component will go.
column - Cell column where component will go.
horizontalJustification - Horizontal justification.
verticalJustication - Vertical justification.
Returns:
value of parameter comp

add

public java.awt.Component add(java.awt.Component comp,
                              OculusLayoutInfo cont,
                              int column,
                              int row)
                       throws java.lang.ArrayIndexOutOfBoundsException
Adds a component to the grid, with the given constraints.
Parameters:
comp - Component to be added to a cell.
cont - The OculusLayoutInfo constraints for comp.
row - Cell row where component will go.
column - Cell column where component will go.
Returns:
value of parameter comp

getComponentAt

public java.awt.Component getComponentAt(int column,
                                         int row)
Returns the component at the given column,row in this grid. If no component has been added to that grid cell, returns null.
Overrides:
getComponentAt in class java.awt.Container

getComponentLocation

public int[] getComponentLocation(java.awt.Component component)
Returns the column,row of the given component in this grid. If given component isn't in this grid, returns null.

setJustification

public void setJustification(int column,
                             int row,
                             int xJustification,
                             int yJustification)
Sets the justification of the given grid cell. Grid cell must have already had something added to it at time this is called. This method automatically revalidates and repaints the container.

setXJustification

public void setXJustification(int column,
                              int row,
                              int xJustification)
Sets the justification of the given grid cell. Grid cell must have already had something added to it at time this is called. This method automatically revalidates and repaints the container.

setYJustification

public void setYJustification(int column,
                              int row,
                              int yJustification)
Sets the justification of the given grid cell. Grid cell must have already had something added to it at time this is called. This method automatically revalidates and repaints the container.

layout

public void layout()
Overrides the container layout method.
Overrides:
layout in class java.awt.Container

doLayout

public void doLayout()
              throws java.lang.RuntimeException
Overrides the container doLayout method. Lays out components according to overview of this class.
Overrides:
doLayout in class java.awt.Container

invalidate

public void invalidate()
Overrides the JPanel.invalidate(). Used to properly invalidate our layout, and our children's layout, if necessary, which the default AWT implementation doesn't do.
Overrides:
invalidate in class java.awt.Container

getPreferredSize

public java.awt.Dimension getPreferredSize()
Overrides the component method. Takes the maximum preferred size of all of the components, per row or column, and then adds each dimension together.
Overrides:
getPreferredSize in class javax.swing.JComponent
Returns:
Preferred Size

getMaximumSize

public java.awt.Dimension getMaximumSize()
Overrides the component method. Takes the maximum max size of all of the components and then multiplies its dimensions by the num of rows and columns.
Overrides:
getMaximumSize in class javax.swing.JComponent
Returns:
Preferred Size

getMinimumSize

public java.awt.Dimension getMinimumSize()
Overrides the component method. Takes the maximum x size of the max x sized component in each column, sums them up and returns that value. Same with y.
Overrides:
getMinimumSize in class javax.swing.JComponent
Returns:
Preferred Size

setCellSpacing

public void setCellSpacing(int numberOfPixels)
Changes the number of pixels between cells in the grid.
Parameters:
numberOfPixels - The number of pixels to set the spacing to.

getCellSpacing

public int getCellSpacing()
Returns the number of pixels to be placed between cells in the grid.

arraySum

public static double arraySum(int[] inp)
Determines the sum of all the integers in inp, truncating summation at maximum of OculusLayout.INFINITY.
Parameters:
inp - The array whose elements' sum is returned.
Returns:
The sum.

getXPreference

public int getXPreference()
Determines the greatest X preference for all of the components in the grid and returns that preference.
Specified by:
getXPreference in interface OculusLayoutInfo
Returns:
the greatest X preference for all components.

getYPreference

public int getYPreference()
Determines the greatest Y preference for all of the components in the grid and returns that preference.
Specified by:
getYPreference in interface OculusLayoutInfo
Returns:
the greatest Y preference for all components.

setSameHeightAs

public void setSameHeightAs(java.awt.Component c)

getSameHeightAs

public java.awt.Component getSameHeightAs()
Description copied from interface: OculusLayoutInfo
Gets the component whose height is being matched.
Specified by:
getSameHeightAs in interface OculusLayoutInfo
Following copied from interface: com.oculustech.layout.OculusLayoutInfo
Returns:
The component whose height is being matched, or null if not applicable.

setSameWidthAs

public void setSameWidthAs(java.awt.Component c)

getSameWidthAs

public java.awt.Component getSameWidthAs()
Description copied from interface: OculusLayoutInfo
Gets the component whose height is being matched.
Specified by:
getSameWidthAs in interface OculusLayoutInfo
Following copied from interface: com.oculustech.layout.OculusLayoutInfo
Returns:
The component whose height is being matched, or null if not applicable.

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.