# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.topic ctrl.data
.title Data
.toc 1 Data Controls
.toc 1 Data
.index Data
.index Database
.index SQLite
.index DatabaseName
.index RecordSource
.index MoveFirst
.index MoveNext
.index AddNew
.index Reposition
.index Validate

.h1 Data

VB Equivalent: Data -- DVX Widget: data | Name Prefix: Data

A data access control that connects to a SQLite database and provides record navigation. Other controls bind to a Data control via their DataSource and DataField properties. The Data control cache is populated by calling Refresh. Move operations auto-save the current row if dirty.

.link ctrl.databinding See Data Binding for details

.h2 Type-Specific Properties

.table
  Property       Type      Description
  ------------   -------   -------------------------------------------
  DatabaseName   String    Path to the SQLite database file.
  RecordSource   String    Table name or SQL SELECT query for the recordset.
  KeyColumn      String    Primary key column name (used for UPDATE/DELETE operations).
  Caption        String    Text displayed on the navigator bar.
  BOF            Boolean   True if the current position is the first record or there are no records (read-only).
  EOF            Boolean   True if the current position is past the last record or there are no records (read-only).
  MasterSource   String    Name of a master Data control (for master-detail binding).
  MasterField    String    Column in the master recordset to read for the filter value.
  DetailField    String    Column in this recordset that matches the master field.
.endtable

.h2 Type-Specific Methods

.table
  Method         Parameters   Description
  ------------   ----------   -------------------------------------------
  MoveFirst      (none)       Navigate to the first record.
  MoveLast       (none)       Navigate to the last record.
  MoveNext       (none)       Navigate to the next record.
  MovePrevious   (none)       Navigate to the previous record.
  AddNew         (none)       Append a blank record and move to it.
  Delete         (none)       Delete the current record.
  Refresh        (none)       Re-query the database and reload records.
  Update         (none)       Write pending changes to the database.
.endtable

.h2 Type-Specific Events

.table
  Event        Parameters          Description
  ----------   -----------------   -------------------------------------------
  Reposition   (none)              Fires after the current record changes. Default event.
  Validate     Cancel As Integer   Fires before writing. Set Cancel = 1 to abort.
.endtable

Default Event: Reposition

.h2 Example

.code
Begin Data Data1
    DatabaseName = "books.db"
    RecordSource = "titles"
    KeyColumn    = "id"
End

Begin TextBox Text1
    DataSource = "Data1"
    DataField  = "title"
End

Sub Form_Load ()
    Data1.Refresh
End Sub
.endcode

.link ctrl.common.props Common Properties, Events, and Methods
.link ctrl.databinding Data Binding
.link ctrl.dbgrid DBGrid
