com.itmill.toolkit.ui
Class GridLayout

java.lang.Object
  extended by com.itmill.toolkit.ui.AbstractComponent
      extended by com.itmill.toolkit.ui.AbstractComponentContainer
          extended by com.itmill.toolkit.ui.AbstractLayout
              extended by com.itmill.toolkit.ui.GridLayout
All Implemented Interfaces:
MethodEventSource, Paintable, Sizeable, VariableOwner, Component, ComponentContainer, Layout, Layout.AlignmentHandler, Layout.MarginHandler, Layout.SpacingHandler, EventListener

public class GridLayout
extends AbstractLayout
implements Layout.AlignmentHandler, Layout.SpacingHandler

A container that consists of components with certain coordinates (cell position) on a grid. It also maintains cursor for adding component in left to right, top to bottom order.

Each component in a GridLayout uses a certain area (column1,row1,column2,row2) from the grid. One should not add components that would overlap with the existing components because in such case an GridLayout.OverlapsException is thrown. Adding component with cursor automatically extends the grid by increasing the grid height.

Since:
3.0
Version:
5.3.0
Author:
IT Mill Ltd.

Nested Class Summary
 class GridLayout.Area
          This class defines an area on a grid.
 class GridLayout.OutOfBoundsException
          An Exception object which is thrown when an area exceeds the bounds of the grid.
 class GridLayout.OverlapsException
          An Exception object which is thrown when two Items occupy the same space on a grid.
 
Nested classes/interfaces inherited from class com.itmill.toolkit.ui.AbstractComponent
AbstractComponent.ComponentErrorEvent, AbstractComponent.ComponentErrorHandler
 
Nested classes/interfaces inherited from interface com.itmill.toolkit.ui.Layout
Layout.AlignmentHandler, Layout.MarginHandler, Layout.MarginInfo, Layout.SpacingHandler
 
Nested classes/interfaces inherited from interface com.itmill.toolkit.ui.ComponentContainer
ComponentContainer.ComponentAttachEvent, ComponentContainer.ComponentAttachListener, ComponentContainer.ComponentDetachEvent, ComponentContainer.ComponentDetachListener
 
Nested classes/interfaces inherited from interface com.itmill.toolkit.ui.Component
Component.ErrorEvent, Component.ErrorListener, Component.Event, Component.Focusable, Component.Listener
 
Nested classes/interfaces inherited from interface com.itmill.toolkit.terminal.Paintable
Paintable.RepaintRequestEvent, Paintable.RepaintRequestListener
 
Field Summary
 
Fields inherited from class com.itmill.toolkit.ui.AbstractLayout
margins
 
Fields inherited from interface com.itmill.toolkit.ui.Layout.AlignmentHandler
ALIGNMENT_BOTTOM, ALIGNMENT_HORIZONTAL_CENTER, ALIGNMENT_LEFT, ALIGNMENT_RIGHT, ALIGNMENT_TOP, ALIGNMENT_VERTICAL_CENTER
 
Fields inherited from interface com.itmill.toolkit.terminal.Sizeable
SIZE_UNDEFINED, UNIT_SYMBOLS, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS
 
Constructor Summary
GridLayout()
          Constructs an empty grid layout that is extended as needed.
GridLayout(int columns, int rows)
          Constructor for grid of given size (number of cells).
 
Method Summary
 void addComponent(Component component)
          Adds the component into this container to the cursor position.
 void addComponent(Component c, int column, int row)
          Adds the component into this container to cells column1,row1 (NortWest corner of the area.)
 void addComponent(Component component, int column1, int row1, int column2, int row2)
           Adds a component with a specified area to the grid.
 float getColumnExpandRatio(int columnIndex)
          Returns the expand ratio of given column
 int getColumns()
          Get the number of columns in the grid.
 Component getComponent(int x, int y)
          Gets the Component at given index.
 Alignment getComponentAlignment(Component childComponent)
          Returns the current Alignment of given component.
 GridLayout.Area getComponentArea(Component component)
          Returns information about the area where given component is layed in the GridLayout.
 Iterator getComponentIterator()
          Gets an Iterator to the component container contents.
 int getCursorX()
          Gets the current cursor x-position.
 int getCursorY()
          Gets the current cursor y-position.
 float getRowExpandRatio(int rowIndex)
          Returns the expand ratio of given row.
 int getRows()
          Get the number of rows in the grid.
 String getTag()
          Gets the components UIDL tag.
 void insertRow(int row)
          Inserts an empty row at the chosen position in the grid.
 boolean isSpacingEnabled()
           
 void newLine()
          Force the next component to be added to the beginning of the next line.
 void paintContent(PaintTarget target)
          Paints the contents of this component.
 void removeAllComponents()
          Removes all components from the container.
 void removeComponent(Component component)
          Removes the given component from this container.
 void removeComponent(int column, int row)
          Removes the component specified with it's cell index.
 void removeRow(int row)
          Removes row and all components in the row.
 void replaceComponent(Component oldComponent, Component newComponent)
          Replaces the component in the container with another one without changing position.
 void setColumnExpandRatio(int columnIndex, float ratio)
          Sets the expand ratio of given column.
 void setColumns(int columns)
          Sets the number of columns in the grid.
 void setComponentAlignment(Component childComponent, Alignment alignment)
          Set alignment for one contained component in this layout.
 void setComponentAlignment(Component childComponent, int horizontalAlignment, int verticalAlignment)
          Set alignment for one contained component in this layout.
 void setComponentAlignment(Component component, String alignment)
           
 void setCursorX(int cursorX)
          Sets the current cursor x-position.
 void setCursorY(int cursorY)
          Sets the current cursor y-position.
 void setRowExpandRatio(int rowIndex, float ratio)
          Sets the expand ratio of given row.
 void setRows(int rows)
          Sets the number of rows in the grid.
 void setSpacing(boolean enabled)
          Enable spacing between child components within this layout.
 void space()
          Moves the cursor forwards by one.
 
Methods inherited from class com.itmill.toolkit.ui.AbstractLayout
getMargin, setMargin, setMargin, setMargin
 
Methods inherited from class com.itmill.toolkit.ui.AbstractComponentContainer
addListener, addListener, attach, detach, fireComponentAttachEvent, fireComponentDetachEvent, moveComponentsFrom, removeListener, removeListener, requestRepaintAll, setEnabled, setHeight, setWidth
 
Methods inherited from class com.itmill.toolkit.ui.AbstractComponent
addListener, addListener, addListener, addListener, addStyleName, changeVariables, childRequestedRepaint, fireComponentErrorEvent, fireComponentEvent, fireEvent, getApplication, getCaption, getComponentError, getData, getDebugId, getDescription, getErrorHandler, getErrorMessage, getHeight, getHeightUnits, getIcon, getLocale, getParent, getStyle, getStyleName, getWidth, getWidthUnits, getWindow, handleError, isEnabled, isImmediate, isReadOnly, isVisible, paint, removeListener, removeListener, removeListener, removeListener, removeListener, removeStyleName, requestRepaint, requestRepaintRequests, setCaption, setComponentError, setData, setDebugId, setDescription, setErrorHandler, setHeight, setHeight, setHeightUnits, setIcon, setImmediate, setLocale, setParent, setReadOnly, setSizeFull, setSizeUndefined, setStyle, setStyleName, setWidth, setWidth, setWidthUnits, setVisible
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.itmill.toolkit.ui.ComponentContainer
addListener, addListener, moveComponentsFrom, removeListener, removeListener, requestRepaintAll
 
Methods inherited from interface com.itmill.toolkit.ui.Component
addListener, addStyleName, attach, childRequestedRepaint, detach, getApplication, getCaption, getIcon, getLocale, getParent, getStyleName, getWindow, isEnabled, isReadOnly, isVisible, removeListener, removeStyleName, setCaption, setEnabled, setIcon, setParent, setReadOnly, setStyleName, setVisible
 
Methods inherited from interface com.itmill.toolkit.terminal.Paintable
addListener, getDebugId, paint, removeListener, requestRepaint, requestRepaintRequests, setDebugId
 
Methods inherited from interface com.itmill.toolkit.terminal.VariableOwner
changeVariables, isImmediate
 
Methods inherited from interface com.itmill.toolkit.terminal.Sizeable
getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeight, setHeightUnits, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidth, setWidthUnits
 

Constructor Detail

GridLayout

public GridLayout(int columns,
                  int rows)
Constructor for grid of given size (number of cells). Note that grid's final size depends on the items that are added into the grid. Grid grows if you add components outside the grid's area.

Parameters:
columns - Number of columns in the grid.
rows - Number of rows in the grid.

GridLayout

public GridLayout()
Constructs an empty grid layout that is extended as needed.

Method Detail

addComponent

public void addComponent(Component component,
                         int column1,
                         int row1,
                         int column2,
                         int row2)
                  throws GridLayout.OverlapsException,
                         GridLayout.OutOfBoundsException

Adds a component with a specified area to the grid. The area the new component should take is defined by specifying the upper left corner (column1, row1) and the lower right corner (column2, row2) of the area.

If the new component overlaps with any of the existing components already present in the grid the operation will fail and an GridLayout.OverlapsException is thrown.

Parameters:
c - the component to be added.
column1 - the column of the upper left corner of the area c is supposed to occupy.
row1 - the row of the upper left corner of the area c is supposed to occupy.
column2 - the column of the lower right corner of the area c is supposed to occupy.
row2 - the row of the lower right corner of the area c is supposed to occupy.
Throws:
GridLayout.OverlapsException - if the new component overlaps with any of the components already in the grid.
GridLayout.OutOfBoundsException - if the cells are outside the grid area.

addComponent

public void addComponent(Component c,
                         int column,
                         int row)
                  throws GridLayout.OverlapsException,
                         GridLayout.OutOfBoundsException
Adds the component into this container to cells column1,row1 (NortWest corner of the area.) End coordinates (SouthEast corner of the area) are the same as column1,row1. Component width and height is 1.

Parameters:
c - the component to be added.
column - the column index.
row - the row index.
Throws:
GridLayout.OverlapsException - if the new component overlaps with any of the components already in the grid.
GridLayout.OutOfBoundsException - if the cell is outside the grid area.

newLine

public void newLine()
Force the next component to be added to the beginning of the next line. By calling this function user can ensure that no more components are added to the right of the previous component.

See Also:
space()

space

public void space()
Moves the cursor forwards by one. If the cursor goes out of the right grid border, move it to next line.

See Also:
newLine()

addComponent

public void addComponent(Component component)
Adds the component into this container to the cursor position. If the cursor position is already occupied, the cursor is moved forwards to find free position. If the cursor goes out from the bottom of the grid, the grid is automatically extended.

Specified by:
addComponent in interface ComponentContainer
Overrides:
addComponent in class AbstractComponentContainer
Parameters:
c - the component to be added.
See Also:
ComponentContainer.addComponent(Component)

removeComponent

public void removeComponent(Component component)
Removes the given component from this container.

Specified by:
removeComponent in interface ComponentContainer
Overrides:
removeComponent in class AbstractComponentContainer
Parameters:
c - the component to be removed.
See Also:
ComponentContainer.removeComponent(Component)

removeComponent

public void removeComponent(int column,
                            int row)
Removes the component specified with it's cell index.

Parameters:
column - the Component's column.
row - the Component's row.

getComponentIterator

public Iterator getComponentIterator()
Gets an Iterator to the component container contents. Using the Iterator it's possible to step through the contents of the container.

Specified by:
getComponentIterator in interface ComponentContainer
Returns:
the Iterator of the components inside the container.

paintContent

public void paintContent(PaintTarget target)
                  throws PaintException
Paints the contents of this component.

Overrides:
paintContent in class AbstractLayout
Parameters:
target - the Paint Event.
Throws:
PaintException - if the paint operation failed.

getComponentAlignment

public Alignment getComponentAlignment(Component childComponent)
Description copied from interface: Layout.AlignmentHandler
Returns the current Alignment of given component.

Specified by:
getComponentAlignment in interface Layout.AlignmentHandler
Returns:
the Alignment

getTag

public String getTag()
Gets the components UIDL tag.

Specified by:
getTag in class AbstractLayout
Returns:
the Component UIDL tag as string.
See Also:
AbstractComponent.getTag()

setColumns

public void setColumns(int columns)
Sets the number of columns in the grid. The column count can not be reduced if there are any areas that would be outside of the shrunk grid.

Parameters:
columns - the new number of columns in the grid.

getColumns

public final int getColumns()
Get the number of columns in the grid.

Returns:
the number of columns in the grid.

setRows

public void setRows(int rows)
Sets the number of rows in the grid. The number of rows can not be reduced if there are any areas that would be outside of the shrunk grid.

Parameters:
rows - the new number of rows in the grid.

getRows

public final int getRows()
Get the number of rows in the grid.

Returns:
the number of rows in the grid.

getCursorX

public int getCursorX()
Gets the current cursor x-position. The cursor position points the position for the next component that is added without specifying its coordinates (grid cell). When the cursor position is occupied, the next component will be added to first free position after the cursor.

Returns:
the grid column the Cursor is on.

setCursorX

public void setCursorX(int cursorX)
Sets the current cursor x-position. This is usually handled automatically by GridLayout.

Parameters:
cursorX -

getCursorY

public int getCursorY()
Gets the current cursor y-position. The cursor position points the position for the next component that is added without specifying its coordinates (grid cell). When the cursor position is occupied, the next component will be added to first free position after the cursor.

Returns:
the grid row the Cursor is on.

setCursorY

public void setCursorY(int cursorY)
Sets the current cursor y-position. This is usually handled automatically by GridLayout.

Parameters:
cursorY -

replaceComponent

public void replaceComponent(Component oldComponent,
                             Component newComponent)
Description copied from interface: ComponentContainer
Replaces the component in the container with another one without changing position.

This method replaces component with another one is such way that the new component overtakes the position of the old component. If the old component is not in the container, the new component is added to the container. If the both component are already in the container, their positions are swapped. Component attach and detach events should be taken care as with add and remove.

Specified by:
replaceComponent in interface ComponentContainer
Parameters:
oldComponent - the old component that will be replaced.
newComponent - the new component to be replaced.

removeAllComponents

public void removeAllComponents()
Description copied from class: AbstractComponentContainer
Removes all components from the container. This should probably be re-implemented in extending classes for a more powerful implementation.

Specified by:
removeAllComponents in interface ComponentContainer
Overrides:
removeAllComponents in class AbstractComponentContainer

setComponentAlignment

public void setComponentAlignment(Component childComponent,
                                  int horizontalAlignment,
                                  int verticalAlignment)
Description copied from interface: Layout.AlignmentHandler
Set alignment for one contained component in this layout. Alignment is calculated as a bit mask of the two passed values.

Specified by:
setComponentAlignment in interface Layout.AlignmentHandler
Parameters:
childComponent - the component to align within it's layout cell.
horizontalAlignment - the horizontal alignment for the child component (left, center, right). Use ALIGNMENT constants.
verticalAlignment - the vertical alignment for the child component (top, center, bottom). Use ALIGNMENT constants.

setComponentAlignment

public void setComponentAlignment(Component childComponent,
                                  Alignment alignment)
Description copied from interface: Layout.AlignmentHandler
Set alignment for one contained component in this layout. Use predefined alignments from Alignment class. Example: layout.setComponentAlignment(myComponent, Alignment.TOP_RIGHT);

Specified by:
setComponentAlignment in interface Layout.AlignmentHandler
Parameters:
childComponent - the component to align within it's layout cell.
alignment - the Alignment value to be set

setSpacing

public void setSpacing(boolean enabled)
Description copied from interface: Layout.SpacingHandler
Enable spacing between child components within this layout.

NOTE: This will only affect spaces between components, not also all around spacing of the layout (i.e. do not mix this with HTML Table elements cellspacing-attribute). Use Layout.setMargin(boolean) to add extra space around the layout.

Specified by:
setSpacing in interface Layout.SpacingHandler

isSpacingEnabled

public boolean isSpacingEnabled()
Specified by:
isSpacingEnabled in interface Layout.SpacingHandler
Returns:
true if spacing, layout leaves space between components

insertRow

public void insertRow(int row)
Inserts an empty row at the chosen position in the grid.

Parameters:
row - Number of the row the new row will be inserted before

removeRow

public void removeRow(int row)
Removes row and all components in the row. Components which span over several rows are removed if the selected row is the component's first row.

Parameters:
row - The row number to remove

setColumnExpandRatio

public void setColumnExpandRatio(int columnIndex,
                                 float ratio)
Sets the expand ratio of given column. Expand ratio defines how excess space is distributed among columns. Excess space means the space not consumed by non relatively sized components.

By default excess space is distributed evenly.

Note, that width needs to be defined for this method to have any effect.

Parameters:
columnIndex -
ratio -
See Also:
AbstractComponentContainer.setWidth(float, int)

getColumnExpandRatio

public float getColumnExpandRatio(int columnIndex)
Returns the expand ratio of given column

Parameters:
columnIndex -
Returns:
the expand ratio, 0.0f by default
See Also:
setColumnExpandRatio(int, float)

setRowExpandRatio

public void setRowExpandRatio(int rowIndex,
                              float ratio)
Sets the expand ratio of given row. Expand ratio defines how excess space is distributed among rows. Excess space means the space not consumed by non relatively sized components.

By default excess space is distributed evenly.

Note, that height needs to be defined for this method to have any effect.

Parameters:
rowIndex -
ratio -
See Also:
AbstractComponentContainer.setHeight(float, int)

getRowExpandRatio

public float getRowExpandRatio(int rowIndex)
Returns the expand ratio of given row.

Parameters:
rowIndex -
Returns:
the expand ratio, 0.0f by default
See Also:
setRowExpandRatio(int, float)

getComponent

public Component getComponent(int x,
                              int y)
Gets the Component at given index.

Parameters:
x - x-index
y - y-index
Returns:
Component in given cell or null if empty

getComponentArea

public GridLayout.Area getComponentArea(Component component)
Returns information about the area where given component is layed in the GridLayout.

Parameters:
component - the component whose area information is requested.
Returns:
an Area object that contains information how component is layed in the grid

setComponentAlignment

public void setComponentAlignment(Component component,
                                  String alignment)


Copyright © 2000-2009 IT Mill Ltd. All Rights Reserved.