Data Controls

The Data Controls tab provides 8 data-aware controls that bind directly to database fields and result sets. These controls automatically display, navigate, and edit database data without manual synchronization code.

TBrowse CT_BROWSE = 79

High-performance data grid for browsing and editing tabular data. Supports both database-bound and virtual (code block) modes. The most powerful data display control in HarbourBuilder.

Property	Type	Default	Description
oDataSource	Object	NIL	Data Access component (TDBFTable, TSQLite, etc.)
aCols	Array	{}	Array of TBrowseColumn objects
nRowCount	Numeric	0	Number of visible rows (read-only)
nColCount	Numeric	0	Number of columns (read-only)
nRowPos	Numeric	1	Current row position in the visible area
nColPos	Numeric	1	Current column position
lEditable	Logical	.F.	Allow in-place cell editing
lVirtual	Logical	.F.	Use virtual mode (data supplied via code blocks)
nVirtualRows	Numeric	0	Total row count in virtual mode
lShowHeaders	Logical	.T.	Show column header row
lShowGrid	Logical	.T.	Show grid lines
lAlternateColors	Logical	.F.	Alternate row background colors
nClrRowOdd	Color	inherited	Odd row background color
nClrRowEven	Color	inherited	Even row background color
nClrSelected	Color	system	Selected row highlight color

TBrowseColumn Properties

Property	Type	Default	Description
cHeading	String	""	Column header text
cField	String	""	Database field name to bind
bBlock	Block	NIL	Code block that returns cell value (virtual mode)
nWidth	Numeric	100	Column width in pixels
nAlign	Numeric	0	Alignment (0=left, 1=center, 2=right)
cPicture	String	""	Display format picture clause
lEditable	Logical	.T.	Allow editing this column

TBrowse Events

Event	Category	Description
OnClick	Action	User clicked a cell. Params: nRow, nCol
OnDblClick	Action	User double-clicked a cell. Params: nRow, nCol
OnRowChange	Navigation	Current row changed. Params: nOldRow, nNewRow
OnColChange	Navigation	Current column changed. Params: nOldCol, nNewCol
OnHeaderClick	Action	Column header clicked (for sorting). Params: nCol
OnBeforeEdit	Edit	Before cell editing begins. Return .F. to cancel. Params: nRow, nCol
OnAfterEdit	Edit	After cell edit committed. Params: nRow, nCol, xOldValue, xNewValue
OnKeyDown	Keyboard	Key pressed while browse has focus. Params: nKey
OnPaint	Display	Custom cell painting. Params: nRow, nCol, oCanvas
OnVirtualData	Data	Request data for a virtual row. Params: nRow, nCol. Must return cell value

Platform	Native Widget
Windows	Custom owner-drawn ListView (WC_LISTVIEW)
macOS	NSScrollView + NSTableView
Linux	GtkScrolledWindow + GtkTreeView

TDBGrid CT_DBGRID = 80

Simplified data grid that auto-generates columns from the data source fields. Easier to use than TBrowse when full customization is not needed.

Property	Type	Default	Description
oDataSource	Object	NIL	Data Access component to bind
lAutoColumns	Logical	.T.	Automatically create columns from fields
lEditable	Logical	.F.	Allow in-place editing
lSortable	Logical	.T.	Allow sorting by clicking headers

Event	Category	Description
OnClick	Action	Cell clicked
OnDblClick	Action	Cell double-clicked
OnRowChange	Navigation	Current row changed
OnAfterEdit	Edit	Cell edit committed

TDBNavigator CT_DBNAVIGATOR = 81

Navigation bar with buttons for first, previous, next, last, insert, delete, edit, save, and cancel operations on a data source.

Property	Type	Default	Description
oDataSource	Object	NIL	Data Access component to navigate
lShowInsert	Logical	.T.	Show Insert button
lShowDelete	Logical	.T.	Show Delete button
lShowEdit	Logical	.T.	Show Edit button
lConfirmDelete	Logical	.T.	Prompt before deleting a record

Event	Category	Description
OnBeforeAction	Action	Before a navigator action. Return .F. to cancel. Params: nAction
OnAfterAction	Action	After a navigator action completes. Params: nAction

TDBText CT_DBTEXT = 82

Data-aware label. Automatically displays the value of a bound database field as read-only text.

Property	Type	Default	Description
oDataSource	Object	NIL	Data Access component
cField	String	""	Field name to display
cPicture	String	""	Display format picture clause

TDBEdit CT_DBEDIT = 83

Data-aware text input. Binds a TEdit control to a database field for viewing and editing.

Property	Type	Default	Description
oDataSource	Object	NIL	Data Access component
cField	String	""	Field name to bind
cPicture	String	""	Input/display format picture clause
lReadOnly	Logical	.F.	Prevent editing

Event	Category	Description
OnChange	Action	Field value changed by user
OnValidate	Validation	Validate before saving. Return .F. to reject. Params: xValue

TDBComboBox CT_DBCOMBOBOX = 84

Data-aware combo box. Displays a drop-down list bound to a database field. Useful for lookup fields.

Property	Type	Default	Description
oDataSource	Object	NIL	Data Access component
cField	String	""	Field name to bind
aItems	Array	{}	List of selectable items
oLookupSource	Object	NIL	Optional lookup data source for items
cLookupField	String	""	Field from lookup source to display
cLookupKey	String	""	Key field from lookup source

Event	Category	Description
OnChange	Action	Selection changed

TDBCheckBox CT_DBCHECKBOX = 85

Data-aware check box. Binds a logical (boolean) database field to a check box control.

Property	Type	Default	Description
oDataSource	Object	NIL	Data Access component
cField	String	""	Logical field name to bind
cText	String	""	Label text beside the check box
xValueOn	Any	.T.	Value representing checked state
xValueOff	Any	.F.	Value representing unchecked state

Event	Category	Description
OnChange	Action	Check state changed

TDBImage CT_DBIMAGE = 86

Data-aware image display. Shows an image stored in a database BLOB field or referenced by a file path field.

Property	Type	Default	Description
oDataSource	Object	NIL	Data Access component
cField	String	""	BLOB or file path field name
lStretch	Logical	.F.	Stretch image to fill the control
lProportional	Logical	.T.	Maintain aspect ratio when stretching
lIsPath	Logical	.F.	Field contains a file path (not binary data)

Code Example: TBrowse with Database

// A data browsing form with TBrowse, navigator, and data-aware controls

FUNCTION Main()

   LOCAL oForm, oDB, oBrw, oNav

   // Create form
   oForm := TForm():New()
   oForm:cTitle := "Customer Browser"
   oForm:nWidth := 800
   oForm:nHeight := 500

   // Connect to database
   oDB := TSQLite():New()
   oDB:cFile := "customers.db"
   oDB:lAutoConnect := .T.

   // Create the browse control
   oBrw := TBrowse():New( oForm )
   oBrw:nLeft   := 10
   oBrw:nTop    := 10
   oBrw:nWidth  := 780
   oBrw:nHeight := 350
   oBrw:oDataSource := oDB
   oBrw:lAlternateColors := .T.

   // Define columns
   oBrw:AddColumn( "Id",    "id",    60,  2 )  // right-aligned
   oBrw:AddColumn( "Name",  "name",  200, 0 )  // left-aligned
   oBrw:AddColumn( "Email", "email", 250, 0 )
   oBrw:AddColumn( "City",  "city",  150, 0 )

   // Events
   oBrw:OnDblClick    := { |r,c| EditRecord( oDB, r ) }
   oBrw:OnHeaderClick := { |c| SortByColumn( oDB, oBrw, c ) }
   oBrw:OnRowChange   := { |o,n| UpdateStatus( n ) }

   // Add navigator bar
   oNav := TDBNavigator():New( oForm )
   oNav:nLeft := 10
   oNav:nTop  := 370
   oNav:oDataSource := oDB
   oNav:lConfirmDelete := .T.

   // Load data and activate
   oDB:Query( "SELECT * FROM customers ORDER BY name" )
   oForm:Activate()

RETURN NIL