AddEventHandler - ProGUI Reference Manual

Syntax

Success = AddEventHandler(Object, EventType, *Callback, *UserData=#Null)

Description

Registers a user-defined callback procedure (event handler) to be executed when a specific event occurs for a given ProGUI Window or Widget object. This is the primary mechanism for making your application interactive and responsive.

Parameters

Object
The handle of the ProGUI Window or Widget object to which the event handler should be attached.

EventType
The type of event to listen for. Use one of the #PG_Event_... constants (e.g., #PG_Event_MouseLeftButtonDown, #PG_Event_Draw, #PG_Event_WindowClose).

*Callback
A pointer to the user-defined procedure that will handle the event. This procedure must match the following signature:

Procedure MyEventHandler(Object, EventType, *eventData, *userData)
; Object: The Window or Widget handle that triggered the event.
; EventType: The #PG_Event_... constant for the event.
; *eventData: Pointer to a structure with event-specific data (e.g., PG_EventMouse for mouse events). Can be #Null for some events.
; *userData: The user data pointer passed during AddEventHandler().

; ... event handling code ...

EndProcedure

*UserData (optional)
A pointer to any custom data (e.g., a structure address) that you want to be passed to your callback procedure when the event occurs. Default is #Null.

Return Value

Returns #True if the event handler was successfully added, or #False if the Object handle, EventType, or Callback pointer was invalid.

Remarks

You can add multiple handlers for the same event type on the same object; they will be called in the order they were added. The specific structure pointed to by `*eventData` depends on the `EventType`. Refer to the Event Handling overview for details on event data structures.

Example

IncludeFile "ProGUI_PB.pbi"
StartProGUI()

; Event handler procedure
Procedure MyClickHandler(Window, EventType, *eventData.PG_EventMouse, *userData)
  Message.s = "Window clicked!"
  If *userData
    Message + " UserDataValue:" + PeekS(*userData)
    Debug Message
    ; You could access *eventData\x, *eventData\y here if needed
  EndIf
EndProcedure

Procedure MyCloseHandler(Window, EventType, *eventData, *userData)
  Debug "Window close requested."
  ; Set a flag or perform cleanup before potentially closing
  End ; Example: End the program
EndProcedure

MyWindow = CreateWindow(0, 0, 300, 200, "Event Handler Example")

Global MyUserData$ = "Some Info"

If MyWindow
  ; Add a handler for left mouse button down, passing custom string data
  AddEventHandler(MyWindow, #PG_Event_MouseLeftButtonDown, @MyClickHandler(), @MyUserData$)

  ; Add a handler for the window close event
  AddEventHandler(MyWindow, #PG_Event_WindowClose, @MyCloseHandler())

  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)

  Repeat
    Event = WaitWindowEvent()
  Until Event = #PB_Event_CloseWindow ; Standard PB loop needed for OS messages
EndIf

StopProGUI()

Supported OS

Windows, Linux