Q3DataTable Class Reference
[Qt3Support module]

Detailed Description

The Q3DataTable class provides a flexible SQL table widget that supports browsing and editing.

Q3DataTable supports various functions for presenting and editing SQL data from a Q3SqlCursor in a table.

If you want a to present your data in a form use QDataBrowser, or for read-only forms, use QDataView instead.

When displaying data, Q3DataTable only retrieves data for visible rows. If the driver supports the 'query size' property the Q3DataTable will have the correct number of rows and the vertical scroll bar will accurately reflect the number of rows displayed in proportion to the number of rows in the dataset. If the driver does not support the 'query size' property, rows are dynamically fetched from the database on an as-needed basis with the scroll bar becoming more accurate as the user scrolls down through the records. This allows extremely large queries to be displayed as quickly as possible, with minimum memory usage.

Q3DataTable inherits Q3Table's API and extends it with functions to sort and filter the data and sort columns. See setSqlCursor(), setFilter(), setSort(), setSorting(), sortColumn() and refresh().

When displaying editable cursors, cell editing will be enabled. (For more information on editable cursors, see Q3SqlCursor). Q3DataTable can be used to modify existing data and to add new records. When a user makes changes to a field in the table, the cursor's edit buffer is used. The table will not send changes in the edit buffer to the database until the user moves to a different record in the grid or presses Enter. Cell editing is initiated by pressing F2 (or right clicking and then clicking the appropriate popup menu item) and canceled by pressing Esc. If there is a problem updating or adding data, errors are handled automatically (see handleError() to change this behavior). Note that if autoEdit() is false navigating to another record will cancel the insert or update.

The user can be asked to confirm all edits with setConfirmEdits(). For more precise control use setConfirmInsert(), setConfirmUpdate(), setConfirmDelete() and setConfirmCancels(). Use setAutoEdit() to control the behavior of the table when the user edits a record and then navigates. (Note that setAutoDelete() is unrelated; it is used to set whether the Q3SqlCursor is deleted when the table is deleted.)

Since the data table can perform edits, it must be able to uniquely identify every record so that edits are correctly applied. Because of this the underlying cursor must have a valid primary index to ensure that a unique record is inserted, updated or deleted within the database otherwise the database may be changed to an inconsistent state.

Q3DataTable creates editors using the default Q3SqlEditorFactory. Different editor factories can be used by calling installEditorFactory(). A property map is used to map between the cell's value and the editor. You can use your own property map with installPropertyMap().

The contents of a cell is available as a QString with text() or as a QVariant with value(). The current record is returned by currentRecord(). Use the find() function to search for a string in the table.

Editing actions can be applied programmatically. For example, the insertCurrent() function reads the fields from the current record into the cursor and performs the insert. The updateCurrent() and deleteCurrent() functions perform similarly to update and delete the current record respectively.

Columns in the table can be created automatically based on the cursor (see setSqlCursor()). Columns can be manipulated manually using addColumn(), removeColumn() and setColumn().

The table automatically copies many of the properties of the cursor to format the display of data within cells (alignment, visibility, etc.). The cursor can be changed with setSqlCursor(). The filter (see setFilter()) and sort defined within the table are used instead of the filter and sort set on the cursor. For sorting options see setSort(), sortColumn(), sortAscending() and sortDescending(). Note that sorting operations will not behave as expected if you are using a QSqlSelectCursor because it uses user-defined SQL queries to obtain data.

The text used to represent NULL, true and false values can be changed with setNullText(), setTrueText() and setFalseText() respectively. You can change the appearance of cells by reimplementing paintField().

Whenever a new row is selected in the table the currentChanged() signal is emitted. The primeInsert() signal is emitted when an insert is initiated. The primeUpdate() and primeDelete() signals are emitted when update and deletion are initiated respectively. Just before the database is updated a signal is emitted; beforeInsert(), beforeUpdate() or beforeDelete() as appropriate.

Member Type Documentation

 QStringList list = myDataTable.sort();
 QStringList::Iterator it = list.begin();
 while( it != list.end() ) {
     myProcessing( *it );
     ++it;
 }