Docs / Reference / xBase Commands

xBase Commands Reference

HarbourBuilder uses Harbour's #xcommand and #translate preprocessor directives to provide a familiar xBase/Clipper-style syntax for creating and configuring controls. These commands are defined in hbbuilder.ch and are expanded at compile time into Harbour OOP method calls.

How xBase commands work

When you write DEFINE FORM oForm TITLE "My App", the Harbour preprocessor transforms it into Harbour OOP code that creates a TForm object and sets its properties. This happens at compile time — the generated OOP code is what actually gets compiled and executed. You can use either style; the commands are simply a more readable shorthand.

Command Expansion Architecture

graph LR A[".prg source
with xBase commands"] --> B["Harbour Preprocessor
#xcommand / #translate"] B --> C["Harbour OOP code
TForm:New(), oBtn:SetText()"] C --> D["Harbour Compiler
harbour.exe"] D --> E["C code
.c files"] E --> F["Native binary"] style A fill:#58a6ff,stroke:#388bfd,color:#0d1117 style B fill:#8b5cf6,stroke:#7c3aed,color:#fff style C fill:#f59e0b,stroke:#d97706,color:#0d1117 style D fill:#3fb950,stroke:#2ea043,color:#0d1117 style E fill:#f59e0b,stroke:#d97706,color:#0d1117 style F fill:#3fb950,stroke:#2ea043,color:#0d1117

Form Commands

Command	Syntax	Description	OOP Equivalent
`DEFINE FORM`	`DEFINE FORM <oForm> [TITLE <cTitle>] [SIZE <nW>, <nH>] [FONT <cFont>, <nSize>]`	Creates a new form window with optional title, size, and font.	`oForm := TForm():New( nil )` `oForm:cTitle := cTitle` `oForm:nWidth := nW` `oForm:nHeight := nH`
`ACTIVATE FORM`	`ACTIVATE FORM <oForm> [CENTERED] [MAXIMIZED] [MODAL]`	Displays the form and starts the event loop. Blocks until the form is closed.	`oForm:Show()` `if CENTERED: oForm:lCentered := .T.` `if MAXIMIZED: oForm:nWindowState := 2`
`ON INIT`	`ON INIT <oForm> <code>`	Assigns an initialization code block to the form's OnInit event.	`oForm:OnInit := { \|\| <code> }`
`ON CLOSE`	`ON CLOSE <oForm> <code>`	Assigns a cleanup code block to the form's OnClose event.	`oForm:OnClose := { \|\| <code> }`

Form Command Example

--- xBase command style ---
local oForm

DEFINE FORM oForm TITLE "Main Window" ;
   SIZE 800, 600 FONT "Segoe UI", 10

ON INIT oForm MsgInfo( "Form initialized" )

ACTIVATE FORM oForm CENTERED

--- What the preprocessor generates (OOP equivalent) ---
oForm := TForm():New( nil )
oForm:cTitle  := "Main Window"
oForm:nWidth  := 800
oForm:nHeight := 600
oForm:SetFont( "Segoe UI", 10 )
oForm:OnInit  := { || MsgInfo( "Form initialized" ) }
oForm:lCentered := .T.
MsgRun( oForm )   /// activates and enters event loop

Control Creation Commands

@ row, col Syntax (Screen Coordinate Style)

The classic Clipper-style @ row, col syntax creates controls at specific coordinates within a parent container:

Command	Syntax	Description	OOP Equivalent
`@ ... BUTTON`	`@ <row>, <col> BUTTON <oBtn> PROMPT <cCaption> OF <oParent> [SIZE <nW>, <nH>] [ACTION <code>]`	Creates a push button at the specified position.	`oBtn := TButton():New( oParent )` `oBtn:nLeft := col` `oBtn:nTop := row` `oBtn:cCaption := cCaption`
`@ ... LABEL`	`@ <row>, <col> LABEL <oLbl> VALUE <cText> OF <oParent> [SIZE <nW>, <nH>]`	Creates a static text label.	`oLbl := TLabel():New( oParent )` `oLbl:nLeft := col` `oLbl:nTop := row` `oLbl:cValue := cText`
`@ ... EDIT`	`@ <row>, <col> EDIT <oEdt> [VALUE <cText>] OF <oParent> [SIZE <nW>, <nH>]`	Creates a single-line text input field.	`oEdt := TEdit():New( oParent )` `oEdt:nLeft := col` `oEdt:nTop := row`
`@ ... COMBOBOX`	`@ <row>, <col> COMBOBOX <oCbo> ITEMS <aItems> OF <oParent> [SIZE <nW>, <nH>]`	Creates a dropdown combo box.	`oCbo := TComboBox():New( oParent )` `oCbo:nLeft := col` `oCbo:nTop := row` `oCbo:aItems := aItems`
`@ ... LISTBOX`	`@ <row>, <col> LISTBOX <oLbx> ITEMS <aItems> OF <oParent> [SIZE <nW>, <nH>]`	Creates a list box control.	`oLbx := TListBox():New( oParent )` `oLbx:nLeft := col` `oLbx:nTop := row`
`@ ... CHECKBOX`	`@ <row>, <col> CHECKBOX <oChk> PROMPT <cCaption> OF <oParent> [SIZE <nW>, <nH>]`	Creates a check box.	`oChk := TCheckBox():New( oParent )` `oChk:nLeft := col` `oChk:nTop := row`
`@ ... GROUPBOX`	`@ <row>, <col> GROUPBOX <oGrp> PROMPT <cCaption> OF <oParent> [SIZE <nW>, <nH>]`	Creates a group box (framed container with caption).	`oGrp := TGroupBox():New( oParent )` `oGrp:nLeft := col` `oGrp:nTop := row`
`@ ... MEMO`	`@ <row>, <col> MEMO <oMemo> [VALUE <cText>] OF <oParent> [SIZE <nW>, <nH>]`	Creates a multi-line text edit control.	`oMemo := TMemo():New( oParent )` `oMemo:nLeft := col` `oMemo:nTop := row`
`@ ... IMAGE`	`@ <row>, <col> IMAGE <oImg> PICTURE <cFile> OF <oParent> [SIZE <nW>, <nH>]`	Creates an image display control.	`oImg := TImage():New( oParent )` `oImg:nLeft := col` `oImg:nTop := row` `oImg:cPicture := cFile`
`@ ... PROGRESSBAR`	`@ <row>, <col> PROGRESSBAR <oPb> OF <oParent> [SIZE <nW>, <nH>]`	Creates a progress bar control.	`oPb := TProgressBar():New( oParent )` `oPb:nLeft := col` `oPb:nTop := row`
`@ ... TIMER`	`@ <row>, <col> TIMER <oTmr> INTERVAL <nMs> OF <oParent> [ACTION <code>]`	Creates a timer control (non-visual).	`oTmr := TTimer():New( oParent )` `oTmr:nInterval := nMs`

@ row, col Example

local oForm, oBtn, oLabel, oEdit

DEFINE FORM oForm TITLE "Sample Form" ;
   SIZE 400, 300

@ 20, 30 LABEL oLabel VALUE "Enter your name:" ;
   OF oForm SIZE 150, 24

@ 50, 30 EDIT oEdit OF oForm SIZE 200, 26

@ 90, 30 BUTTON oBtn PROMPT "Submit" ;
   OF oForm SIZE 100, 30 ;
   ACTION MsgInfo( "Hello, " + oEdit:GetValue() )

ACTIVATE FORM oForm CENTERED

Property Modifier Commands

These commands can be appended to any control definition to set additional properties:

Modifier	Syntax	Description
`SIZE`	`SIZE <nWidth>, <nHeight>`	Sets the control's width and height in pixels.
`FONT`	`FONT <cName>, <nSize> [BOLD] [ITALIC]`	Sets the control's font with optional style modifiers.
`COLOR`	`COLOR <nFore> [, <nBack>]`	Sets the foreground and optional background color.
`VISIBLE`	`VISIBLE <lVisible>`	Sets initial visibility (.T. / .F.).
`ENABLED`	`ENABLED <lEnabled>`	Sets initial enabled state (.T. / .F.).
`VALUE`	`VALUE <xValue>`	Sets the initial value (text for Edit, checked state for CheckBox, etc.).
`PROMPT`	`PROMPT <cCaption>`	Sets the caption/label text.
`OF`	`OF <oParent>`	Specifies the parent container (required for all controls except DEFINE FORM).
`ACTION`	`ACTION <code>`	Assigns a code block to the control's default event (OnClick for buttons, OnChange for edits).
`WHEN`	`WHEN <lCondition>`	Conditional expression that determines if the control is enabled.
`VALID`	`VALID <lCondition>`	Validation expression checked when the control loses focus.
`PICTURE`	`PICTURE <cFile>`	Sets the image file for Image controls.
`ITEMS`	`ITEMS <aArray>`	Sets the list of items for ListBox, ComboBox, and similar controls.
`INTERVAL`	`INTERVAL <nMs>`	Sets the timer interval in milliseconds.
`MESSAGE`	`MESSAGE <cHint>`	Sets the tooltip/hint text.

Modifier Example

@ 30, 40 BUTTON oBtn PROMPT "<S>ave" ;
   OF oForm ;
   SIZE 100, 30 ;
   FONT "Segoe UI", 10 BOLD ;
   COLOR CLR_WHITE, CLR_BLUE ;
   ACTION SaveData() ;
   WHEN lDataModified ;
   MESSAGE "Save current changes (Ctrl+S)"

Command	Syntax	Description
`DEFINE POPUP`	`DEFINE POPUP <oMenu> [MENU]`	Creates a popup/menu object.
`DEFINE BAR`	`DEFINE BAR <nId> OF <oMenu> PROMPT <cText> [ACTION <code>]`	Adds a menu item (bar) to a menu.
`DEFINE TOOLBAR`	`DEFINE TOOLBAR <oTb> [OF <oForm>]`	Creates a toolbar container on the form.
`DEFINE BUTTON`	`DEFINE BUTTON <oTbBtn> OF <oTb> PROMPT <cCaption> [ACTION <code>]`	Adds a button to a toolbar.

Dialog Commands

Command	Syntax	Description
`MsgInfo()`	`MsgInfo( <cMessage> [, <cTitle> ] )`	Displays an information message box.
`MsgStop()`	`MsgStop( <cMessage> [, <cTitle> ] )`	Displays an error/stop message box.
`MsgYesNo()`	`MsgYesNo( <cMessage> [, <cTitle> ] ) → nResponse`	Displays a Yes/No dialog. Returns 6 (Yes) or 7 (No).
`MsgYesNoCancel()`	`MsgYesNoCancel( <cMessage> [, <cTitle> ] ) → nResponse`	Displays a Yes/No/Cancel dialog. Returns 6 (Yes), 7 (No), or 2 (Cancel).
`MsgRun()`	`MsgRun( <oForm> )`	Activates a form and enters the event loop. Equivalent to ACTIVATE FORM.

Complete Command Summary

Command	Category	Header File
`DEFINE FORM`	Form	hbbuilder.ch
`ACTIVATE FORM`	Form	hbbuilder.ch
`ON INIT`	Form	hbbuilder.ch
`ON CLOSE`	Form	hbbuilder.ch
`@ ... BUTTON`	Control	hbbuilder.ch
`@ ... LABEL`	Control	hbbuilder.ch
`@ ... EDIT`	Control	hbbuilder.ch
`@ ... COMBOBOX`	Control	hbbuilder.ch
`@ ... LISTBOX`	Control	hbbuilder.ch
`@ ... CHECKBOX`	Control	hbbuilder.ch
`@ ... GROUPBOX`	Control	hbbuilder.ch
`@ ... MEMO`	Control	hbbuilder.ch
`@ ... IMAGE`	Control	hbbuilder.ch
`@ ... PROGRESSBAR`	Control	hbbuilder.ch
`@ ... TIMER`	Control	hbbuilder.ch
`DEFINE POPUP`	Menu	hbbuilder.ch
`DEFINE BAR`	Menu	hbbuilder.ch
`DEFINE TOOLBAR`	Toolbar	hbbuilder.ch
`DEFINE BUTTON`	Toolbar	hbbuilder.ch

Commands vs. OOP

Both styles are fully supported. The xBase commands are more concise and familiar to Clipper/xBase developers. The OOP style gives you more fine-grained control and is preferred for dynamic control creation at runtime. The Form Designer generates xBase commands by default, but you can switch to OOP-style code at any time — the two-way parser understands both.

Getting Started Component Palette IDE Features Tutorials Reference Platforms Command Expansion Architecture Form Commands Form Command Example Control Creation Commands @ row, col Syntax (Screen Coordinate Style) @ row, col Example Property Modifier Commands Modifier Example Menu and Toolbar Commands Dialog Commands Complete Command Summary

Getting Started

Component Palette

IDE Features

Tutorials

Reference

Platforms