DispatchEvent - ProGUI Reference Manual

Syntax

Success = DispatchEvent(Object, EventType, *EventData=#Null)

Description

Manually triggers or dispatches a specific event for a given ProGUI Window or Widget object. This causes all event handlers previously registered for that specific event type on that object using AddEventHandler() to be executed.

Note: This function is primarily intended for internal use within the ProGUI library itself to route events originating from the OS or other internal systems. While available to the developer, manual event dispatching should be used cautiously as it might bypass expected ProGUI state management.

Parameters

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

EventType
The type of event to dispatch. Use one of the #PG_Event_... constants (e.g., #PG_Event_Action).

*EventData (optional)
A pointer to a structure containing data relevant to the event being dispatched. The type of structure depends on the `EventType`. For simple events like #PG_Event_Action, this might be an integer value or #Null. For mouse events, it would typically be a pointer to a PG_EventMouse structure. Default is #Null.

Return Value

Returns #True if at least one event handler was found and called for the specified object and event type. Returns #False if the Object handle was invalid or if no handlers were registered for that specific event on that object.

Remarks

This function directly calls the registered callback procedures. The `*UserData` originally passed during AddEventHandler() will be correctly passed to the handlers when they are called via `DispatchEvent()`. Manually dispatching events like mouse movements might not update internal ProGUI states related to mouse position or hover status unless the provided `*EventData` is correctly populated and corresponds to actual state changes.

Example (Conceptual)

This example demonstrates how the function *could* be used, but direct use is generally discouraged in favor of reacting to naturally occurring events via AddEventHandler().

IncludeFile "ProGUI_PB.pbi"
StartProGUI()

; Event handler for a custom action
Procedure MyActionHandler(Widget, EventType, *eventData, *userData)
  Protected Value
  If *eventData: Value = *eventData: EndIf ; Get the value passed
  Debug "Action Event Dispatched for Widget! Value: " + Str(Value)
EndProcedure

MyWindow = CreateWindow(0, 0, 300, 200, "Dispatch Example")
MyWidget = CreateWidget(10, 10, 100, 30) ; Add a simple widget

If MyWindow And MyWidget
  ; Register a handler for the Action event on the widget
  AddEventHandler(MyWidget, #PG_Event_Action, @MyActionHandler())

  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)

  ; Manually dispatch the #PG_Event_Action to the widget, passing '123' as data
  Debug "Dispatching Action event..."
  DispatchEvent(MyWidget, #PG_Event_Action, 123)
  Debug "Dispatch complete."

  Repeat
    Event = WaitWindowEvent()
  Until Event = #PB_Event_CloseWindow
EndIf

StopProGUI()

Supported OS

Windows, Linux