Michael L Brereton - 02 February 2008, http://www.ewesoft.com/
<<
Previous: Drawing On Controls
>>
Next: Tree Controls
The eve.ui.table.TableControl is one of the most useful
and powerful controls in the Eve GUI library. It can be used as is for
displaying tabulated data, or it can be extended to provide more advanced
controls (e.g. the eve.ui.table.TreeControl inherits from the
TableControl).
A Table rendered on screen is actually made up of two parts.
The TableControl control itself is the on-screen UI component
responsible for laying out the table on the screen and for interpreting user
pen presses. A TableModel is used by the TableControl to specify a
number of different aspects of the table, including:
ü The
number of rows and columns in the table, and whether row and column headers are
to be used.
ü The
width of columns and the height of rows.
ü The
data, textual or otherwise, to be displayed in each cell.
ü The
display attributes for each cell, including fill (background) color, border
style, font, insets, etc.
Apart from the first set of data listed above, all the rest
of the information is provided through method calls in TableModel that you can
override to provide your own functionality and appearance. You do not need to
extend TableModel to display your own data in a Table. You can use a GridTableModel
to display a simple grid of textual data (see the API on how to use a
GridTableModel). However there are two disadvantages of this method:
1. All
of the data to be displayed must be pre-created and placed in a Grid. For very
large tables, this will use a lot of memory.
2. You
still will not be able to customize the appearance of individual cells without overriding
the GridTableModel.
Overall it will usually be best to override the TableModel,
especially when the data to be displayed is very large, or is easily generated
dynamically given the row and column of a particular cell.
numRows and numCols specify the number of rows
and columns in the table. This value does not include the row and column
headers – set the hasRowHeaders and hasColumnHeaders to be true
or false depending if these headers are being used.
Override calculateColWidth(int col) and calculateRowHeight(int
row) to return the size (in pixels) of a particular column and row. The
values of col and row will start from 0. A col or row
value of –1 indicates the row headers width or column headers height. You
may still be given a parameter of –1 even if you have
hasRowHeaders/hasColumnHeaders set to false. Therefore you should always check
if the parameter is –1 and return 0 in that instance if you are not using
headers.
There are two methods that are called to determine the data
to be displayed in a cell – either of which has the option of returning null.
The first is boolean getCellText(int row,int col,StringList destination).
This method should append text data for the cell to the destination StringList
using one of the add() methods of StringList. If there is no text data for that
cell, this method should return false. If you are displaying nothing but text
data in your table, then you just need to override this method.
The second method is getCellData(int row,int col).
This method can return any data – however the default implementation of
TableModel is only able to render a String, an array of Strings, an IImage
object, a Control or a ControlProxy. If you return null from getCellText() and
return a value from getCellData() which is not one of the ones listed above,
you will have to override paintCellData() to paint your custom data.
This is a very important aspect – it determines the
appearance of a particular cell and the text within it. This is determined
through the method: getCellAttributes(int row,int col,boolean
isSelected,TableCellAttributes ta).
This method returns a TableCellAttributes object that
can be the same one provided in the parameter, or it can be a completely
different one. The TableCellAttributes object contains all the information
needed by the TableControl to render the cell – including the cell text/data.
In fact, it is in the default getCellAttributes() method that the getCellText()
and getCellData() methods are called.
When overriding the getCellAttributes() method you should
(in most cases) call the superclass implementation of the method to setup the
attributes to be the default values. You should then modify the individual
elements of the attributes to customize the appearance of particular cells.
The method canSelect(int row,int col) should return
true or false to determine whether a particular cell can be selected or not.
Note that if it returns true for cases where row or col values are –1, then the
entire row/column will be selected.
The method made() gets called when a make() is called on the containing TableControl. This gives you an opportunity to do preparations for display. At this stage you will be able to get FontMetrics from the Table that is displaying the model, for example.
The TableControl itself has some useful methods that you can
use and override. Most of these are fairly simple to use and are documented in
the API.