# 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.

.section Widgets
.topic widget.dbgrid
.title DbGrid
.toc 0 DbGrid
.index DbGrid
.index wgtDbGrid
.index Database Grid

.h2 DbGrid

A database grid widget that displays all records from a Data control in a scrollable, sortable table. Columns auto-populate from the Data control's column names and can be hidden, resized (by dragging a column border), and renamed by the application. Clicking a column header sorts the display ascending/descending. Selecting a row syncs the Data control's cursor position. The grid reads directly from the Data control's cached rows, so there is no separate copy of the data.

The grid supports alternating row shading, vertical and horizontal scrollbars, keyboard navigation (arrows, Page Up/Down, Home, End), and double-click activation (fires onDblClick).

Header: widgets/dbGrid.h

.h3 Creation

.code
WidgetT *grid = wgtDbGrid(parent);
dbGridSetDataWidget(grid, dataCtrl);
.endcode

.h3 API Functions

.index dbGridRefresh
.index dbGridSetColumnVisible
.index dbGridSetColumnHeader
.index dbGridSetColumnWidth
.index dbGridGetSelectedRow

.table
  Function                                                   Description
  --------                                                   -----------
  WidgetT *dbGridCreate(parent)                              Create a database grid widget. Exposed as create in the API struct.
  void dbGridSetDataWidget(w, dataWidget)                    Bind the grid to a Data control. Auto-populates columns from the Data control's column names.
  void dbGridRefresh(w)                                      Re-read the Data control's state and repaint the grid. Rebuilds the sort index if sorting is active.
  void dbGridSetColumnVisible(w, fieldName, visible)         Show or hide a column by field name.
  void dbGridSetColumnHeader(w, fieldName, header)           Set a display header for a column (overrides the field name).
  void dbGridSetColumnWidth(w, fieldName, width)             Set a column's width (tagged size, 0 = auto).
  int32_t dbGridGetSelectedRow(w)                            Get the index of the currently selected data row (-1 if none).
.endtable

.h3 API Struct (wgtRegisterApi "dbgrid")

.table
  Slot                 Function
  ----                 --------
  create               dbGridCreate
  setDataWidget        dbGridSetDataWidget
  refresh              dbGridRefresh
  setColumnVisible     dbGridSetColumnVisible
  setColumnHeader      dbGridSetColumnHeader
  setColumnWidth       dbGridSetColumnWidth
  getSelectedRow       dbGridGetSelectedRow
.endtable

.h3 Properties (BASIC Interface)

.table
  Property     Type       Access       Description
  --------     ----       ------       -----------
  GridLines    Boolean    Read/Write   Whether to draw grid lines between cells (default: true).
.endtable

.h3 Methods (BASIC Interface)

.table
  Method       Description
  ------       -----------
  Refresh      Re-read the Data control and repaint.
.endtable

.h3 Events

.table
  Event        Description
  -----        -----------
  Click        Fires when a row is clicked (selection change).
  DblClick     Fires when a row is double-clicked. Default event.
.endtable

.h3 Default Event

"DblClick" (VB basName: DBGrid, namePrefix: DBGrid).
