HOWTO implement a new table cell

Main Page Modules Class Hierarchy Alphabetical List Compound List File List Compound Members Related Pages Examples

HOWTO implement a new table cell

Individual cells may be implemented by subclassing QdbtBaseCell (or a subclass thereof) and (re)implementing virutal methods as necessary.

The are example implementation available with the tabular package. These are QdbtTableCell (an example for 'feepy creaturism' ( ;-) ), which was in consquence the reason for implementing abstact cells, the QdbtIntCell, QdbtFloatCell and QdbtComboCell.

Components involved

Roughly, a cell is capable of interacting with two other components. These are it's 'private' editor, which is related to the cell's type as has to be implemented for each cell individually, and the table comopnent (not to be confused with the tabular aka QdbtBaseTabular or QdbtTabular).

Interaction between the table components and the cell

In order to be able to implement a new cell, the interaction between the table components and the individual cells must be described first. Lets start with the visualisation of the cell:

QdbtBaseCell::paint() - This virtual method is expected to paint the cell. It reveives the cells width and height, a painter (the cell's offset is 0,0, its extents are width and height) and modifiers which specify, if cells is to be painted in selected mode or if it is currently being edited. For reference reasons the pointer to the base instance (QdbtBaseTabular) is being passed the the paint method.
QdbtBaseCell::paintFocus() - This virtual method is just expected to paint a focus rectangle onto a previously painted cell. For this a painter, the width and the height of the cell are passed as well as the base instance (QdbtBaseTabular).

After a cell can be visualized and a keyboard focus rect can be placed onto that cell, it can be displayed with a tabular. The next challange is to enable this cell to be edited. A 'normal' editing session looks approximately like this:

The user traverses to cell by means of cursor keys or on single mouse click with the left mouse button. Except for drawing of the cells and the focus rects of the currently focused cell (see below), this is handled by the table components.
The user presses ENTER or RETURN while a cell is focused. This action resolves in the cell being edited, which is archieved by the QdbtBaseCell::beginEdit() method being called. This method is virtual and may this be reimplemented by any subclass.
The user modifies the cell's content and pressed RETURN or ENTER once more to finish the editing session or ESC to cancel the current session and revert the cell to its original state . This user action is expected to be resolved by the cell's editor (described below) into QdbtBaseCell::acceptEdit() or QdbtBaseCell::cancelEdit().

In order to allow a cell to modify behaviour of the table components, it receives keyEvents and mouseEvents and may intercept them in order to add specific additional functionality. For example, the QdbtCombCell reimplements QdbtComboCell::keyEvent() to enable responding to pressing SPACE, ENTER or RETURN by raising the combo box section. In addition a single mouse click with the left mouse button is resolved into this editing behaviour as well (accomplished by reimplementing QdbtComboCell::mouseEvent() ). If a cells decides on itself to start a new editing session, it should negotiate with the table components if this is possible (it might be that currently an editing session is running, and it is not clear if this session may be ended). This negotiation is done by the base cell's protected method QdbtBaseCell::aboutToBeEdited(). It may be considered good style to honour the reply of this method, since it might confuse the user if more than just one edit sessions are active simultaneously.

Utilities and Tools for implementing new cells

As mentioned in the change log, a developer documentation exists besides the 'normal' application programmers documentation. This developer documentation includes serveral additional tool classes as well as documentation of (private) member variables. To generate this documentation, please aquire a recent version of doxygen, get accustomed to its usage and prepare a documentation using the doxygen preprocessor to define INTERNAL_DOCUMENTATION (as PREDEFINED ).

1.2.15-20020421