Class

DBKit.Table

Description

Displays rows of records from the database table assigned to it.

Only the members declared by DBKit.Table itself are described here; for the inherited members, see the parent classes.

Properties

Name	Type	Read-Only	Shared
AllowDirectCellEditing	Boolean
ColumnFormats	String
ColumnNames	String
EditableColumnNames	String
NoRelatedRowFoundMessage	String
OrderBy	String
TableName	String

Methods

Name	Parameters	Returns
Average	columnName As String	Double
CellValueAt	row As Integer, column As Integer, formatted As Boolean = False	Variant
HeaderAt	index As Integer	String
Maximum	columnName As String	Double
Minimum	columnName As String	Double
NewRow
PrimaryKeyAt	index As Integer	String
Refresh	whereClause As String = "", searchValues() As Variant = Nil
RowCount		Integer
Sum	columnName As String	Double
TableName		String

Events

Name	Parameters	Returns
DoublePressed		DBKit.Window
RowChanged	row As DBKit.Row
RowCreated	row As DBKit.Row
RowDeleted	row As DBKit.Row
RowDisplayed	row As DBKit.Row
RowEditing	row As DBKit.Row
RowLoaded	row As DBKit.Row
RowNotSelected
RowSaved	row As DBKit.Row
RowSaving	row As DBKit.Row
RowUndone	row As DBKit.Row
SelectionChanged

Property descriptions

DBKit.Table.AllowDirectCellEditing

AllowDirectCellEditing As Boolean

If True, the user can edit the values of cells directly in the Table.

The default is False.

DBKit.Table.ColumnFormats

ColumnFormats As String

A comma-separated list of format strings, one for each column of the Table, used when formatting numeric values.

DBKit.Table.ColumnNames

ColumnNames As String

A comma-separated list of the database column names displayed by the Table, one for each column of the Table.

The number of column names must match the number of columns in the Table.

To display a column from a related table, qualify it with the table name, for example products.name. When the tables are related in more than one way, follow the column with a colon and the foreign key column in tableName.columnName form to specify which relationship to use.

DBKit.Table.EditableColumnNames

EditableColumnNames As String

A comma-separated list of the database column names whose values the user can edit.

DBKit.Table.NoRelatedRowFoundMessage

NoRelatedRowFoundMessage As String

The message displayed when no related row is found.

The default is "No row found with that value."

DBKit.Table.OrderBy

OrderBy As String

Specifies the order in which the rows are displayed, as a SQL ORDER BY clause (without the words ORDER BY).

DBKit.Table.TableName

TableName As String

The name of the database table whose rows this control displays.

Method descriptions

DBKit.Table.Average

Average(columnName As String) As Double

Returns the average of the values in the column with the given name, over the rows found. An unsaved new row is not included.

DBKit.Table.CellValueAt

CellValueAt(row As Integer, column As Integer, formatted As Boolean = False) As Variant

The value of a cell. By default the underlying, unformatted value with its own type (a Double for a price, for example). With formatted = True, the text as the user sees it. Works for any row, whether or not it has been displayed yet.

DBKit.Table.HeaderAt

HeaderAt(index As Integer) As String

Returns the header of the column at the given index.

(Desktop only.)

DBKit.Table.Maximum

Maximum(columnName As String) As Double

Returns the largest value in the column with the given name, over the rows found. Raises an exception if there are no rows.

DBKit.Table.Minimum

Minimum(columnName As String) As Double

Returns the smallest value in the column with the given name, over the rows found. Raises an exception if there are no rows.

DBKit.Table.NewRow

NewRow()

Creates a new row.

DBKit.Table.PrimaryKeyAt

PrimaryKeyAt(index As Integer) As String

Returns the primary key of the row at the given index.

DBKit.Table.Refresh

Refresh(whereClause As String = "", searchValues() As Variant = Nil)

Reloads the Table's rows from the database, applying the given WHERE clause (without the word WHERE) and search values.

DBKit.Table.RowCount

RowCount() As Integer

Returns the number of rows in the Table.

DBKit.Table.Sum

Sum(columnName As String) As Double

Returns the sum of the values in the column with the given name.

DBKit.Table.TableName

TableName() As String

Returns the name of the database table for this control: the TableName property if set, otherwise the table name of the control's layout.

Event descriptions

DBKit.Table.DoublePressed

DoublePressed() As DBKit.Window

The user double-pressed a row.

Implement this event to return the layout to display for the row: the DBKit.Window in desktop projects or the DBKit.Page in web projects.

DBKit.Table.RowChanged

RowChanged(row As DBKit.Row)

The current row (passed to the event) has been changed.

DBKit.Table.RowCreated

RowCreated(row As DBKit.Row)

A new row (passed to the event) was just created and is now the current row.

DBKit.Table.RowDeleted

RowDeleted(row As DBKit.Row)

The current row (passed to the event) has been deleted.

DBKit.Table.RowDisplayed

RowDisplayed(row As DBKit.Row)

The current row (passed to the event) is being displayed.

Implement this event to set calculated column values, since RowChanged does not fire while rows are being displayed.

DBKit.Table.RowEditing

RowEditing(row As DBKit.Row)

The current row (passed to the event) is being edited by the user.

DBKit.Table.RowLoaded

RowLoaded(row As DBKit.Row)

The current row (passed to the event) has been loaded.

DBKit.Table.RowNotSelected

RowNotSelected

There is no row currently selected.

DBKit.Table.RowSaved

RowSaved(row As DBKit.Row)

The current row (passed to the event) has been saved.

DBKit.Table.RowSaving

RowSaving(row As DBKit.Row)

The current row (passed to this event) is about to be saved.

DBKit.Table.RowUndone

RowUndone(row As DBKit.Row)

The changes made to the current row (passed to this event) have been undone.

DBKit.Table.SelectionChanged

SelectionChanged()

The selected row changed.

Notes

Loading its own rows

The Table loads its rows in its own Opening event, so no layout code is needed to display rows. Rows are loaded from the database on demand as the user scrolls.

Which rows are displayed

The Table displays all rows of its table by default. If the layout's Where property (Window, Page, Container) provides a WHERE clause, only the matching rows are displayed. When the user searches with a DBKit.SearchField, the Table displays the search results instead.

Editing cells with the keyboard

When AllowDirectCellEditing is True, pressing Tab moves to the next editable cell and Shift-Tab moves to the previous editable cell.

Decimal places come from the column format

For numeric columns, the number of decimal places the user may enter is determined by the column's format in ColumnFormats.

Displaying a detail layout

Implement DoublePressed to return a new instance of the detail layout for the double-pressed row. Pass the Table to the new layout's constructor so the layout is bound to it.

One Table per layout table

A layout can contain only one Table whose TableName matches the layout's TableName. Adding a second one raises an exception. To display more than one list of rows from the same table, place the additional Tables on DBKit.Containers.

Calculated columns

Use the RowDisplayed event to compute a column value from other columns, setting the value on the row passed to the event, for example row.Column("linetotal") = row.Column("quantity").IntegerValue * row.Column("price").DoubleValue. RowChanged does not fire while rows are being displayed, so implement RowDisplayed to keep calculated values up to date. RowDeleted fires when a row is deleted, so implement it to keep any totals current.

Saving a row updates the Table

When a row is saved, DBKit updates the Table columns that display the row's values, adding the row to the Table and selecting it if it is new. This happens whether the row was edited on the same layout as the Table or on a separate detail layout.

Localization

Localize the control's user-facing text (NoRelatedRowFoundMessage) the standard Xojo way: assign a dynamic constant to each property and provide translations for as many languages as you need, or localize the property values directly.

Compatibility

Project Types	Desktop, Web
Operating Systems	All