.section Widgets
.topic widget.datactrl
.title DataCtrl
.toc 0 Data Widgets
.toc 0 DataCtrl
.index DataCtrl
.index wgtDataCtrl
.index Database Binding
.index Master-Detail

.h2 DataCtrl

A VB3-style Data control for database binding. Displays a visible navigation bar that connects to a SQLite database via dvxSql* functions. Reads all rows from the RecordSource query into an in-memory cache for bidirectional navigation. Fires Reposition events when the cursor moves so bound controls can update. Supports master-detail linking between Data controls.

Header: widgets/widgetDataCtrl.h

.h3 Creation

.code
WidgetT *data = wgtDataCtrl(parent);
.endcode

.h3 Macros

.index wgtDataCtrlRefresh
.index wgtDataCtrlMoveFirst
.index wgtDataCtrlMoveNext
.index wgtDataCtrlGetField
.index wgtDataCtrlSetField
.index wgtDataCtrlUpdate
.index wgtDataCtrlAddNew
.index wgtDataCtrlDelete

.table
  Macro                                          Description
  -----                                          -----------
  wgtDataCtrl(parent)                            Create a Data control.
  wgtDataCtrlRefresh(w)                          Re-execute the RecordSource query and rebuild the row cache.
  wgtDataCtrlMoveFirst(w)                        Move the cursor to the first row.
  wgtDataCtrlMovePrev(w)                         Move the cursor to the previous row.
  wgtDataCtrlMoveNext(w)                         Move the cursor to the next row.
  wgtDataCtrlMoveLast(w)                         Move the cursor to the last row.
  wgtDataCtrlGetField(w, colName)                Get the value of a column in the current row. Returns const char *.
  wgtDataCtrlSetField(w, colName, value)         Set the value of a column in the current row (marks the row dirty).
  wgtDataCtrlUpdateRow(w)                        Write the current row's pending changes back to the database.
  wgtDataCtrlUpdate(w)                           Flush all pending changes to the database.
  wgtDataCtrlAddNew(w)                           Begin a new row. Sets dirty state; call Update to commit.
  wgtDataCtrlDelete(w)                           Delete the current row from the database.
  wgtDataCtrlSetMasterValue(w, val)              Set the master-detail filter value for this control.
  wgtDataCtrlGetRowCount(w)                      Get the total number of cached rows.
  wgtDataCtrlGetColCount(w)                      Get the number of columns in the result set.
  wgtDataCtrlGetColName(w, col)                  Get the name of a column by index. Returns const char *.
  wgtDataCtrlGetCellText(w, row, col)            Get the text of a specific cell by row and column index. Returns const char *.
  wgtDataCtrlSetCurrentRow(w, row)               Set the current row by index (0-based).
.endtable

.h3 Properties (BASIC Interface)

.table
  Property       Type       Access       Description
  --------       ----       ------       -----------
  DatabaseName   String     Read/Write   Path to the SQLite database file.
  RecordSource   String     Read/Write   SQL query or table name for the result set.
  KeyColumn      String     Read/Write   Primary key column name (used for UPDATE/DELETE).
  MasterSource   String     Read/Write   Name of the master Data control for master-detail linking.
  MasterField    String     Read/Write   Column in the master control to read for the filter value.
  DetailField    String     Read/Write   Column in this table to filter by the master value.
  Caption        String     Read/Write   Text displayed on the navigation bar.
  BOF            Boolean    Read-only    True when the cursor is before the first row.
  EOF            Boolean    Read-only    True when the cursor is past the last row.
.endtable

.h3 Methods (BASIC Interface)

.table
  Method         Description
  ------         -----------
  AddNew         Begin a new row.
  Delete         Delete the current row.
  MoveFirst      Move to the first row.
  MoveLast       Move to the last row.
  MoveNext       Move to the next row.
  MovePrevious   Move to the previous row.
  Refresh        Re-execute the query and rebuild the cache.
  Update         Write pending changes to the database.
.endtable

.h3 Events

.table
  Event          Description
  -----          -----------
  Reposition     Fires when the current row changes (navigation, refresh, etc.). Default event.
  Validate       Fires before writing changes. Return false to cancel.
.endtable
