Tutorial: Event Handling

Events are the backbone of interactive applications. Every time a user clicks a button, types a key, resizes a window, or closes a form, HarbourBuilder fires an event that your code can handle. This tutorial covers all the major event types and the different ways to respond to them.

Step 1: Understanding Events in HarbourBuilder

Every HarbourBuilder control exposes a set of event properties (e.g. OnClick, OnChange). You assign a code block or a method reference to these properties. When the event fires, HarbourBuilder executes your handler.

Step 2: Generating Event Handlers via the Object Inspector

1. Select a control on the form (e.g. a Button).
2. In the Object Inspector, switch to the Events tab.
3. Double-click the event name (e.g. OnClick).
4. The IDE automatically:
   • Creates a static function stub in your source file.
   • Assigns the code block to call that function.
   • Jumps the cursor to the new function body so you can start coding.

Step 3: OnClick — Button and Control Clicks

The most common event. Fires when the user clicks a button, label, image, or any clickable control.

Inline code block (simple logic):

oBtn:OnClick := { || MsgInfo( "Button was clicked!" ) }

Calling a separate function (complex logic):

oBtn:OnClick := { || OnBtnSaveClick( oForm, oGet ) }

static function OnBtnSaveClick( oForm, oGet )

   local cValue := oGet:GetValue()

   if Empty( cValue )
      MsgAlert( "Please enter a value." )
      return nil
   endif

   MsgInfo( "Saved: " + cValue )
   oForm:SetTitle( "Saved!" )

return nil

Step 4: OnChange — Value Changes

Fires whenever the value of an input control changes. Useful for TextBox (TGet), ComboBox, CheckBox, and Spinner controls.

oGetSearch:OnChange := { || OnSearchChange( oGetSearch, oListBox ) }

static function OnSearchChange( oGet, oList )

   local cFilter := oGet:GetValue()

   oList:Filter( { |cItem| Upper( cFilter ) $ Upper( cItem ) } )

return nil

Step 5: OnKeyDown — Keyboard Input

Fires when a key is pressed while the control has focus. The handler receives the key code and modifier flags as parameters.

oGet:OnKeyDown := { |nKey, nFlags| OnGetKeyDown( nKey, nFlags, oGet ) }

static function OnGetKeyDown( nKey, nFlags, oGet )

   do case
   case nKey == VK_RETURN
      MsgInfo( "Enter pressed! Value: " + oGet:GetValue() )

   case nKey == VK_ESCAPE
      oGet:SetValue( "" )

   case nKey == VK_F1
      MsgInfo( "Help: type a value and press Enter." )

   endcase

return nil

Common key constants: VK_RETURN, VK_ESCAPE, VK_TAB, VK_DELETE, VK_F1 through VK_F12, VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT.

Step 6: OnResize — Form and Control Resizing

Fires when the user resizes the form. Use this to reposition or resize controls dynamically for a responsive layout.

oForm:OnResize := { || OnFormResize( oForm, oMemo, oStatusBar ) }

static function OnFormResize( oForm, oMemo, oStatusBar )

   local nW := oForm:nWidth
   local nH := oForm:nHeight

   // Make the memo fill the form with a 10-pixel margin
   oMemo:SetSize( nW - 20, nH - 80 )

   // Keep status bar at the bottom
   oStatusBar:SetPos( nH - 30, 0 )
   oStatusBar:SetSize( nW, 30 )

return nil

Step 7: OnClose — Form Closing

Fires when the user tries to close the form (clicking the X button, pressing Alt+F4, or calling Close()). Return .F. from the handler to prevent the form from closing — useful for unsaved-changes prompts.

oForm:OnClose := { || OnFormClose( oForm ) }

static function OnFormClose( oForm )

   local nAnswer

   if lDataModified
      nAnswer := MsgYesNoCancel( "Save changes before closing?" )

      do case
      case nAnswer == 1   // Yes
         SaveData()
         return .T.

      case nAnswer == 2   // No
         return .T.

      case nAnswer == 3   // Cancel
         return .F.         // Prevent closing

      endcase
   endif

return .T.

Event Parameters Summary

Code Block vs. Method Handler

HarbourBuilder supports two styles for event handlers:

Code block — best for short, inline logic:

oBtn:OnClick := { || oLabel:SetValue( Time() ) }

Method handler — best for complex logic that needs its own function:

oBtn:OnClick := { || OnBtnClick( oForm ) }

static function OnBtnClick( oForm )
   // Complex logic here: database calls, validation, etc.
   ...
return nil