Docs / Reference / Methods A-Z

Methods Reference A-Z

This page documents the most commonly used methods across HarbourBuilder controls. Methods are functions called on control objects to perform actions, query state, or trigger behavior. They complement property assignments and event handlers in the HarbourBuilder programming model.

Methods vs. Properties

Use properties to read or set a control's state (e.g., oBtn:nWidth := 200). Use methods to trigger actions (e.g., oBtn:Show()) or to query computed values that are not stored as simple properties. In HarbourBuilder's OOP layer, methods are invoked with the :method() syntax on any object reference.

Construction and Destruction

Method	Parameters	Returns	Description	Available For
`New()`	`oParent`	Control object	Creates a new control instance within the specified parent. This is the constructor method used by the xBase preprocessor to expand `DEFINE` and `@` commands. Usually called implicitly by the code generator.	All controls
`Create()`	none	Self (the control)	Realizes the control on the native platform by calling the backend API (CreateWindowEx, NSView alloc, gtk_widget_new). Called automatically during form activation.	All visual controls
`Release()`	none	nil	Destroys the control and frees its native resources. On the backend, this calls DestroyWindow, release, or gtk_widget_destroy. After Release(), the object reference becomes invalid.	All controls
`Close()`	none	nil	Closes the form. Triggers OnCloseQuery (which can cancel the close), then OnClose, then onDestroy. For non-form controls, this method is not available.	Form

Construction Examples

--- New() and Create() are usually called by the preprocessor ---
--- This is what the code generator produces from DEFINE FORM: ---

oForm := TForm():New( nil )
oForm:cTitle   := "My Window"
oForm:nWidth   := 640
oForm:nHeight  := 480
oForm:Create()

--- Creating a button programmatically ---
oBtn := TButton():New( oForm )
oBtn:cCaption  := "Click Me"
oBtn:nLeft     := 50
oBtn:nTop      := 30
oBtn:nWidth    := 120
oBtn:nHeight   := 32
oBtn:Create()

--- Destroying a control ---
oOldBtn:Release()   /// removes and frees the native widget

Visibility and Focus

Method	Parameters	Returns	Description	Available For
`Show()`	none	nil	Makes the control visible. For forms, this also activates the form and shows it on screen. Triggers the OnShow event. For child controls, makes them visible within their parent.	All visual controls
`Hide()`	none	nil	Hides the control without destroying it. The control still exists and can be shown again. Triggers the OnHide event on forms.	All visual controls
`SetFocus()`	none	nil	Gives input focus to the control. The control must be visible, enabled, and have lTabStop set to .T. Triggers the OnEnter event. For forms, brings the form to the foreground.	All focusable controls

Visibility and Focus Examples

--- Show/hide a panel based on a checkbox ---
oCheck:OnClick := { || ;
   if oCheck:lCheck
      oPanel:Show()
   else
      oPanel:Hide()
   endif ;
}

--- Set focus to the first field when the form opens ---
oForm:OnInit := { || ;
   oNameEdit:SetFocus() ;
}

--- Show a modal dialog and return ---
oDialog:Show()
oDialog:SetFocus()   /// ensure focus is on the dialog

Value Methods

Method	Parameters	Returns	Description	Available For
`GetValue()`	none	Current value	Returns the current value of the control. For Edit/Memo, returns the text string. For CheckBox, returns .T./.F. For ListBox/ComboBox, returns the selected item. For TrackBar/UpDown, returns the numeric position.	Edit, Memo, MaskEdit, CheckBox, Radio, ListBox, ComboBox, TrackBar, UpDown, LabeledEdit
`SetValue( xValue )`	`xValue` (any)	nil	Sets the control's value. For Edit/Memo, sets the text. For CheckBox, sets the check state. For ListBox/ComboBox, selects the matching item. Triggers the OnChange event.	Edit, Memo, MaskEdit, CheckBox, Radio, ListBox, ComboBox, TrackBar, UpDown, LabeledEdit
`SetText( cText )`	`cText` (string)	nil	Sets the displayed text of the control. Equivalent to SetValue() for text controls, but also works for Label, StaticText, Button caption, etc. Does not trigger OnChange.	Label, StaticText, Button, Edit, Memo, LabeledEdit, StatusBar, GroupBox
`GetText()`	none	String	Returns the displayed text. For Edit/Memo, this is the text content. For Label/StaticText, the caption. For Button, the prompt.	Label, StaticText, Button, Edit, Memo, LabeledEdit

Value Method Examples

--- Read and write values ---
oBtn:OnClick := { || ;
   local cName := oNameEdit:GetValue()   /// read the edit box
   MsgInfo( "Hello, " + cName + "!" ), ;
   oNameEdit:SetValue( "" )              /// clear it
}

--- GetText vs. GetValue ---
/// GetValue() returns the underlying value (may be typed)
/// GetText() always returns a string

oCheck:OnClick := { || ;
   local lChecked := oCheck:GetValue()  /// returns .T. or .F.
   oStatusLabel:SetText( ;
      if( lChecked, "Checked", "Unchecked" ) ;
   ) ;
}

--- Set text on multiple controls ---
oTitleLabel:SetText( "Welcome to the Application" )
oStatus:SetText( "Ready" )

Position and Size Methods

Method	Parameters	Returns	Description	Available For
`SetBounds( nLeft, nTop, nWidth, nHeight )`	Four numbers	nil	Sets the position and size of the control in a single call. More efficient than setting each property separately because it triggers only one native resize/redraw.	All visual controls
`SetPosition( nLeft, nTop )`	Two numbers	nil	Sets only the position (left, top) without changing size. Alias: `MoveTo()`.	All visual controls
`SetSize( nWidth, nHeight )`	Two numbers	nil	Sets only the size (width, height) without changing position.	All visual controls
`GetSize()`	none	Array `{ nWidth, nHeight }`	Returns the current width and height as a two-element array.	All visual controls
`GetPosition()`	none	Array `{ nLeft, nTop }`	Returns the current left and top as a two-element array.	All visual controls

Position and Size Examples

--- SetBounds: position and size in one call ---
oBtn:SetBounds( 50, 30, 120, 32 )

--- Resize a grid to fill the form ---
oForm:OnResize := { | nW, nH | ;
   oGrid:SetBounds( 10, 10, nW - 20, nH - 60 ) ;
}

--- Get current size ---
aSize := oForm:GetSize()
MsgInfo( "Width: " + LTrim( Str( aSize[ 1 ] ) ) + ;
         ", Height: " + LTrim( Str( aSize[ 2 ] ) ) )

Font Methods

Method	Parameters	Returns	Description	Available For
`SetFont( cName, nSize, [lBold], [lItalic], [lUnderline] )`	Font name, size, optional style flags	nil	Sets the font for the control in a single call. Style parameters are optional and default to .F. This is a convenience method that sets cFontName, nFontSize, lFontBold, etc. all at once.	All controls with text
`GetFont()`	none	Font object (or array)	Returns the current font descriptor. The return type depends on the backend but typically contains font name, size, and style information.	All controls with text

Font Method Examples

--- SetFont: set the complete font in one call ---
oTitleLabel:SetFont( "Segoe UI", 14, .T. )     /// bold
oEdit:SetFont( "Consolas", 11, .F., .T. )      /// italic
oBtn:SetFont( "Arial", 12, .T., .F., .T. )     /// bold + underline

--- Get current font ---
oFont := oLabel:GetFont()
MsgInfo( "Font: " + oFont:cName + " Size: " + LTrim( Str( oFont:nSize ) ) )

Display and Refresh Methods

Method	Parameters	Returns	Description	Available For
`Refresh()`	none	nil	Forces an immediate redraw of the control. This invalidates the control's display area and triggers the OnPaint event. Use when you have changed properties that affect appearance and need an immediate visual update.	All visual controls
`Update()`	none	nil	Processes any pending paint messages immediately. Unlike Refresh() which forces a repaint, Update() only repaints areas that are already marked as needing redraw. Useful during long operations to keep the UI responsive.	All visual controls
`Invalidate()`	none	nil	Marks the control's entire area as needing repaint, but does not force an immediate redraw. The actual painting happens during the next paint cycle. More efficient than Refresh() when you plan to make multiple changes before the display updates.	All visual controls

Refresh Examples

--- Refresh after changing appearance properties ---
oShape:nBrushColor := CLR_RED
oShape:nPenWidth   := 3
oShape:Refresh()    /// immediate visual update

--- Refresh a custom-drawn PaintBox ---
oPaintBox:OnTimer := { || ;
   UpdateData(), ;       /// recalculate data
   oPaintBox:Invalidate() /// mark for repaint
}

Complete Method Summary Table

Method	Returns	Category	Primary Controls
`New( oParent )`	Control object	Construction	All controls
`Create()`	Self	Construction	All visual controls
`Release()`	nil	Destruction	All controls
`Close()`	nil	Lifecycle	Form
`Show()`	nil	Visibility	All visual controls
`Hide()`	nil	Visibility	All visual controls
`SetText( cText )`	nil	Value	Label, Edit, Button, Memo, StatusBar
`GetText()`	String	Value	Label, Edit, Button, Memo
`GetValue()`	Any	Value	Edit, Memo, CheckBox, ListBox, ComboBox
`SetValue( xVal )`	nil	Value	Edit, Memo, CheckBox, ListBox, ComboBox
`SetBounds()`	nil	Position	All visual controls
`SetPosition()`	nil	Position	All visual controls
`SetSize()`	nil	Position	All visual controls
`GetSize()`	Array	Position	All visual controls
`GetPosition()`	Array	Position	All visual controls
`SetFont()`	nil	Font	All controls with text
`GetFont()`	Font object	Font	All controls with text
`Refresh()`	nil	Display	All visual controls
`Update()`	nil	Display	All visual controls
`Invalidate()`	nil	Display	All visual controls
`SetFocus()`	nil	Focus	All focusable controls

Method chaining

Some methods return self, enabling a fluent style: oBtn:New( oForm ):SetBounds( 50, 30, 120, 32 ):SetText( "OK" ):Show(). However, the traditional approach of setting properties individually is more readable and is the style used by the HarbourBuilder code generator.

Getting Started Component Palette IDE Features Tutorials Reference Platforms Construction and Destruction Construction Examples Visibility and Focus Visibility and Focus Examples Value Methods Value Method Examples Position and Size Methods Position and Size Examples Font Methods Font Method Examples Display and Refresh Methods Refresh Examples Complete Method Summary Table

Getting Started

Component Palette

IDE Features

Tutorials

Reference

Platforms