Eve Application Development

Michael L Brereton - 02 February 2008, http://www.ewesoft.com/

 

Beginners Guide - Contents

<< Previous: Drawing On Controls

>> Next: Tree Controls

Table Controls

Eve Application Development 1

Table Controls. 1

Extending the TableModel 1

 

 

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.

Extending the TableModel

 

Row and Column Attributes

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.

Cell Data

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.

Cell Attributes

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.

Miscellaneous Methods

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.