waba.ui
Class Grid

java.lang.Object
  |
  +--waba.ui.Control
        |
        +--waba.ui.Container
              |
              +--waba.ui.Grid

public class Grid

extends Container

This is a common grid component. The features are:

• Vertical scrollbar to scroll up and down the information on the grid
• Horizontal scrolling in case the columns widths are greater than the screen width
• An easy to use interface for adding/removing information to the grid
• Optional check column, this is a column that is clickable marking an specific line as checked/unchecked, this is usefull if you want the user to be able to select multiple lines displayed on the grid
• Columns can be resized so that the user can see all the information displayed in a given column
• Style configuration, you can set the color of captions boxes all the way thru the stripes colors and vertical line types. The grid is compatible with your application's style (Flat, WinCE, etc... )
• The GridEvent class contains the events generated by the grid.
• A column may be marked as editable. In this case, an Edit will be placed in the currently focused cell. A column can also have choices (ComboBox).
• The columns can be sorted by clicking in the title.
• If the text is bigger than the size of the column, you can click and hold in the cell to display a tooltip with the full text.
• When a cell's text is bigger than the column size, pressing a cell during 2 seconds will display a tool tip with the full text.
• You can customize cell back and fore colors, enabled state and choices by using the CellController class.

Here´s an example:

     Rect r = getClientRect();

     String []gridCaptions = {" WPT "," HDG "," DST "," ETE "," FUEL "};
     int gridWidths[] =
     {
      fm.getTextWidth(" ABCDE "),
      fm.getTextWidth(" 000 "),
      fm.getTextWidth(" 999.9 "),
      fm.getTextWidth(" 99:99 "),
      fm.getTextWidth(" 99.9 "),
     };
     int gridAligns[] = { LEFT, CENTER, RIGHT, CENTER, RIGHT };
     grid = new Grid(gridCaptions, gridWidths, gridAligns, false);
     add(grid);
     grid.setRect(LEFT+3,TOP+3,r.width/2,r.height/2);
     grid.secondStripeColor = new Color(235,235,235);

     String[][] data = new String[][]
     {
        {"0AAAA","000","000.0","00:00","00.0"},
        {"1BBBB","111","111.1","11:11","11.1"},
        {"2CCCC","222","222.2","22:22","22.2"},
        {"3DDDD","333","333.3","33:33","33.3"},
        {"4EEEE","444","444.4","44:44","44.4"},
        {"5FFFF","555","555.5","55:55","55.5"},
     };
     grid.setItems(data);
 

This will create a grid with the given captions, column widths, information alignment and a check column.

Don't forget to take a look at superwaba.samples.ui.grid.GridTest.

Starting in version 5.7, it is possible to assign a DataSource to a Grid.

Since:

SuperWaba 5.5

Inner Class Summary

static class	Grid.CellController Abstract class that must be implemented if you want to get a fine control of each cell in the grid.
static interface	Grid.DataSource Interface that can be used to fetch data on demmand.

Field Summary

static int	ALL_CHECKED When the user clicks on the header check to check all, a CHECK_CHANGED_EVENT is dispatched, and the row is set as ALL_CHECKED.
static int	ALL_UNCHECKED When the user clicks on the header check, to uncheck all, a CHECK_CHANGED_EVENT is dispatched, and the row is set as ALL_UNCHECKED.
boolean	boldCheck Set it to true to draw a bold check
boolean	canClickSelectAll Set to false to disable the click on the check column of the captions to select all and unselect all
java.lang.String[]	captions The column captions.
Color	captionsBackColor Sets the captions box background color.
Color	checkColor Default check color
boolean	disableSort Set to true to disable sorting when clicking in the column header.
boolean	drawCheckBox Set this to false if you dont want the check column to have the rect underneath the check mark
boolean	drawStripes Set to false to don't draw the stripes
boolean	enableColumnResize Set this to false if you dont want to let the user resize the columns
int	extraHorizScrollButtonHeight The extra height of the horizontal scroll buttons.
Color	firstStripeColor first stripe color.
Color	highlightColor The color of the selected (highlighted) row
protected int	linesPerPage How many lines fits in a page
java.lang.String	oldCellText The text that was in the cell before the user had editted it.
Color	secondStripeColor second stripe color.
protected int	selectedLine The current selected line, or -1 if none.
ToolTip	tip The tooltip used to display a column's text when it exceeds the column width
static int	VERT_DOT used in the property verticalLineStyle
static int	VERT_LINE used in the property verticalLineStyle
static int	VERT_NONE used in the property verticalLineStyle
int	verticalLineStyle Sets the vertical line style of the grid.

Fields inherited from class waba.ui.Container

BORDER_LOWERED, BORDER_NONE, BORDER_RAISED, BORDER_SIMPLE, children, lastH, lastW, lastX, lastY, parentWindow, started, tabOrder, tail

Fields inherited from class waba.ui.Control

AFTER, appId, appObj, asContainer, asWindow, backColor, backDis, BEFORE, BOTTOM, CENTER, clearValueInt, clearValueStr, enabled, FILL, FIT, fm, fmH, focusLess, focusTraversable, font, foreColor, foreDis, height, highlightRectsCount, isHighlighting, LEFT, parent, PREFERRED, RANGE, RIGHT, SAME, TOP, uiCE, uiFlat, uiPalm, uiVista, visible, width, x, x2, y, y2

Constructor Summary

Grid(java.lang.String[] captions, boolean checkEnabled)
This will create a grid with the given captions and an optional multi-selection check column so that the user can select multiple lines of the grid.

Grid(java.lang.String[] captions, int[] widths, int[] aligns, boolean checkEnabled)
This will create a grid with the given captions, column widths, information alignment and an optional multi-selection check column so that the user can select multiple lines of the grid

Method Summary

void	add(java.lang.String[] item) Add a new line to the end of the grid.
void	add(java.lang.String[] item, int row) Add a new line at the given index position of the grid.
void	clear() Clears the grid contents, leaving it blank.
boolean	del(int row) Remove the given line index from the grid.
java.lang.String	getCellText(int row, int col) Returns the text's column of the given row number.
java.lang.String	getColumnText(int row, int col) Deprecated. Use getCellText instead.
java.lang.String[]	getItem(int row) Returns the line corresponding to the given index.
Vector	getItemsVector() Return a vector containing all information inside the grid.
int	getPreferredHeight() Returns the preffered height of this control.
int	getPreferredWidth() Returns the preffered width of this control.
java.lang.String[]	getSelectedItem() Get the information on the currently selected line.
int	getSelectedLine() Deprecated. Use getSelectedRow instead.
int	getSelectedRow() Get the number of the currently selected row.
boolean	horizontalScroll(boolean toLeft) Scrolls the grid horizontaly as needed
boolean	isChecked(int row) Check if a given lineIndex is checked
protected void	onBoundsChanged() Called after a setRect.
protected void	onColorsChanged(boolean colorsChanged) Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container.
void	onEvent(Event e) Called to process key, pen, control and other posted events.
protected void	onFontChanged() Called after a setFont
void	onPaint(Graphics g) Draws the border (if any).
protected void	onStart() Called when this container can be initialized.
void	qsort(int col) Performs a quicksort in the items of the given column.
void	replace(java.lang.String[] item, int row) Replace a given line by the specified by its index with the supplied one.
void	setCellController(Grid.CellController cc) Sets the CellController instance for this grid.
void	setCellText(int row, int col, java.lang.String text) Sets the text of a column.
void	setChecked(int row, boolean check) Checks or unchecks the given index based on the second argument.
void	setColumnChoices(int col, java.lang.String[] choices) Makes the given column ComboBox-like.
Edit	setColumnEditable(int col, boolean editable) Sets the given column as an editable one.
void	setColumnText(int row, int col, java.lang.String text) Deprecated. Use setCellText instead.
void	setDataSource(Grid.DataSource ds, int nrItems) Sets the data source of this grid to be the given one.
void	setItems(java.lang.String[][] items) Sets the grid items to be displayed, notice that it needs to be conforming to the numbers of columns that the grid currently have.
void	setSelectedLine(int row) Deprecated. Use setSelectedRow instead.
void	setSelectedRow(int row) Sets the selected line to the given one.
int	size() Returns the number of lines in this grid

Methods inherited from class waba.ui.Container

add, add, add, broadcastEvent, findChild, getChildren, getClientRect, getClientRect, onAdd, onRemove, paintChildren, remove, setBorderStyle, setEnabled, setHighlighting, swapToTopmostWindow

Methods inherited from class waba.ui.Control

addTimer, changeHighlighted, contains, createGraphics, drawHighlight, getAbsoluteRect, getBackColor, getFont, getFontMetrics, getForeColor, getNext, getParent, getParentWindow, getPos, getRect, getSize, isDisplayed, isEnabled, isVisible, onWindowPaintFinished, postEvent, removeTimer, repaint, repaintNow, requestFocus, setBackColor, setBackForeColors, setFocusLess, setFont, setForeColor, setRect, setRect, setRect, setVisible, translateFromOrigin, uiStyleChanged

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERT_LINE

public static final int VERT_LINE

used in the property verticalLineStyle

VERT_DOT

public static final int VERT_DOT

used in the property verticalLineStyle

VERT_NONE

public static final int VERT_NONE

used in the property verticalLineStyle

ALL_CHECKED

public static final int ALL_CHECKED

When the user clicks on the header check to check all, a CHECK_CHANGED_EVENT is dispatched, and the row is set as ALL_CHECKED.

ALL_UNCHECKED

public static final int ALL_UNCHECKED

When the user clicks on the header check, to uncheck all, a CHECK_CHANGED_EVENT is dispatched, and the row is set as ALL_UNCHECKED.

drawCheckBox

public boolean drawCheckBox

Set this to false if you dont want the check column to have the rect underneath the check mark

checkColor

public Color checkColor

Default check color

disableSort

public boolean disableSort

Set to true to disable sorting when clicking in the column header.

enableColumnResize

public boolean enableColumnResize

Set this to false if you dont want to let the user resize the columns

captions

public java.lang.String[] captions

The column captions. Can be directly assigned, but always make sure it has the same number of elements of the widths array, set with the setWidths method.

drawStripes

public boolean drawStripes

Set to false to don't draw the stripes

firstStripeColor

public Color firstStripeColor

first stripe color. WHITE by default.

secondStripeColor

public Color secondStripeColor

second stripe color. BRIGHT by default

highlightColor

public Color highlightColor

The color of the selected (highlighted) row

captionsBackColor

public Color captionsBackColor

Sets the captions box background color. BRIGHT by default

verticalLineStyle

public int verticalLineStyle

Sets the vertical line style of the grid. VERT_DOT by default

selectedLine

protected int selectedLine

The current selected line, or -1 if none.

linesPerPage

protected int linesPerPage

How many lines fits in a page

oldCellText

public java.lang.String oldCellText

The text that was in the cell before the user had editted it.

canClickSelectAll

public boolean canClickSelectAll

Set to false to disable the click on the check column of the captions to select all and unselect all

boldCheck

public boolean boldCheck

Set it to true to draw a bold check

tip

public ToolTip tip

The tooltip used to display a column's text when it exceeds the column width

extraHorizScrollButtonHeight

public int extraHorizScrollButtonHeight

The extra height of the horizontal scroll buttons. Defaults to 4

Constructor Detail

Grid

public Grid(java.lang.String[] captions,
            int[] widths,
            int[] aligns,
            boolean checkEnabled)

This will create a grid with the given captions, column widths, information alignment and an optional multi-selection check column so that the user can select multiple lines of the grid

Parameters:

captions - Captions for the columns. Cannot be null!

widths - Widths of the columns. If the total width is less than the grid's width, the last column will fill until the grid width. If null, the caption widths will be computed and used as the row width.

aligns - Alignment of information on the given column. If null, all aligns will be LEFT.

checkEnabled - True if you want the multi-selection check column, false otherwise

Grid

public Grid(java.lang.String[] captions,
            boolean checkEnabled)

This will create a grid with the given captions and an optional multi-selection check column so that the user can select multiple lines of the grid. The widths will be computed as the width of the grid captions and the alignment will be all LEFT.

Parameters:

captions - Captions for the columns

checkEnabled - True if you want the multi-selection check column, false otherwise

Method Detail

setCellController

public void setCellController(Grid.CellController cc)

Sets the CellController instance for this grid. Read the javadocs of the top of this page for more information.

Since:

SuperWaba 5.8

setColumnEditable

public Edit setColumnEditable(int col,
                              boolean editable)

Sets the given column as an editable one. Note that setting an editable column as not editable will remove all its formats. Returns the previous Edit or the new one, so you can easily change its formats. Important: this must be called AFTER the grid has set its bounds.

setColumnChoices

public void setColumnChoices(int col,
                             java.lang.String[] choices)

Makes the given column ComboBox-like. The given choice array is used to create a PopList that is shown when the user clicks on the column. Note that calling this method removes any Edit assigned to this column. Passing a null value removes any ComboBox assigned to the column. You can change dynamically the choices by extending the CellController class.

Since:

SuperWaba 5.7

See Also:

setCellController(waba.ui.Grid.CellController)

onFontChanged

protected void onFontChanged()

Description copied from class: Control

Called after a setFont

Overrides:

onFontChanged in class Control

setItems

public void setItems(java.lang.String[][] items)

Sets the grid items to be displayed, notice that it needs to be conforming to the numbers of columns that the grid currently have. This method removes any assigned datasource.

setDataSource

public void setDataSource(Grid.DataSource ds,
                          int nrItems)

Sets the data source of this grid to be the given one. Note that when using data sources, the add, remove, insert, etc methods CANNOT BE USED. A data source is mostly used to assign a ResultSet to it, so its nonsense any data modification. Note that the scroll is made not live scrolling to speedup data retrieval.

Since:

SuperWaba 5.7

add

public void add(java.lang.String[] item)

Add a new line to the end of the grid. Its up to the user to call repaint() afterwards. This method does not work if there's a datasource assigned.

Parameters:

item - string containing the information on the row

add

public void add(java.lang.String[] item,
                int row)

Add a new line at the given index position of the grid. Its up to the user to call repaint() afterwards. This method does not work if there's a datasource assigned.

Parameters:

item - string containing the information on the row

row - index position to insert the row in

replace

public void replace(java.lang.String[] item,
                    int row)

Replace a given line by the specified by its index with the supplied one. This method does not work if there's a datasource assigned.

Parameters:

item - string containing the information of the new line

row - index position to insert the row in

del

public boolean del(int row)

Remove the given line index from the grid. Its up to the user to call repaint(). This method does not work if there's a datasource assigned. afterwards

getColumnText

public java.lang.String getColumnText(int row,
                                      int col)

Deprecated. Use getCellText instead.

Returns the text's column of the given row number. If the grid has a check column, col must start from 1.

getCellText

public java.lang.String getCellText(int row,
                                    int col)

Returns the text's column of the given row number. If the grid has a check column, col must start from 1.

getSelectedItem

public java.lang.String[] getSelectedItem()

Get the information on the currently selected line.

getSelectedLine

public int getSelectedLine()

Deprecated. Use getSelectedRow instead.

Get the number of the currently selected line.

getSelectedRow

public int getSelectedRow()

Get the number of the currently selected row.

setChecked

public void setChecked(int row,
                       boolean check)

Checks or unchecks the given index based on the second argument. This method only works with a grid that has checks and repaint must be called.

isChecked

public boolean isChecked(int row)

Check if a given lineIndex is checked

getItemsVector

public Vector getItemsVector()

Return a vector containing all information inside the grid. Note that if a datasource is assigned, this method returns null.

getItem

public java.lang.String[] getItem(int row)

Returns the line corresponding to the given index. This method works with or without a datasource.

onColorsChanged

protected void onColorsChanged(boolean colorsChanged)

Description copied from class: Control

Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container. If colorsChanged is true, it was called from setForeColor/setBackColor/Container.add; otherwise, it was called from setEnabled

Overrides:

onColorsChanged in class Container

onPaint

public void onPaint(Graphics g)

Description copied from class: Container

Draws the border (if any). If you override this method, be sure to call super.onPaint(g);, or the border will not be drawn.

Overrides:

onPaint in class Container

Tags copied from class: Control

Parameters:

g - the graphics object for drawing

See Also:

Graphics

onStart

protected void onStart()

Description copied from class: Container

Called when this container can be initialized. This differs from the onAdd method by that this method is called only once. When the container is being setup, the onStart method is called, followed by onAdd; then, the onAdd is called every time the container is added again.

Overrides:

onStart in class Container

getPreferredWidth

public int getPreferredWidth()

Description copied from class: Control

Returns the preffered width of this control.

Overrides:

getPreferredWidth in class Control

getPreferredHeight

public int getPreferredHeight()

Description copied from class: Control

Returns the preffered height of this control.

Overrides:

getPreferredHeight in class Control

onBoundsChanged

protected void onBoundsChanged()

Description copied from class: Control

Called after a setRect.

Overrides:

onBoundsChanged in class Control

clear

public void clear()

Clears the grid contents, leaving it blank. Removes any assigned datasource.

Overrides:

clear in class Container

horizontalScroll

public boolean horizontalScroll(boolean toLeft)

Scrolls the grid horizontaly as needed

setColumnText

public void setColumnText(int row,
                          int col,
                          java.lang.String text)

Deprecated. Use setCellText instead.

Sets the text of a column. If the grid has a check column, col must start from 1.

Since:

SuperWaba 5.7

setCellText

public void setCellText(int row,
                        int col,
                        java.lang.String text)

Sets the text of a column. If the grid has a check column, col must start from 1.

Since:

SuperWaba 5.8

onEvent

public void onEvent(Event e)

Description copied from class: Control

Called to process key, pen, control and other posted events.

Overrides:

onEvent in class Control

Tags copied from class: Control

Parameters:

event - the event to process

See Also:

Event, KeyEvent, PenEvent

qsort

public void qsort(int col)

Performs a quicksort in the items of the given column. This method does not work if there's a datasource assigned.

setSelectedLine

public void setSelectedLine(int row)

Deprecated. Use setSelectedRow instead.

Sets the selected line to the given one. Note: if this grid has checks, the selected line is used to scroll to mark the line that may be checked; if the grid does not have checks, then it acts like a normal selected line.

setSelectedRow

public void setSelectedRow(int row)

Sets the selected line to the given one. Note: if this grid has checks, the selected line is used to scroll to mark the line that may be checked; if the grid does not have checks, then it acts like a normal selected line.

size

public int size()

Returns the number of lines in this grid