Event Handling Overview
ProGUI operates on an event-driven model. User interactions (like mouse clicks, keyboard input), system events (like window resizing or DPI changes), and internal operations (like drawing or animation updates) trigger events. Your application reacts to these events by providing specific functions, called event handlers or callbacks.
The primary function for reacting to events is AddEventHandler(). You use this to associate one of your procedures with a specific event type on a specific object (either a Window or a Widget). When that event occurs for that object, ProGUI will call your procedure.
When an event handler is called, it typically receives information
about the event through an *eventData parameter. This
parameter points to a structure containing details relevant to the event
(e.g., mouse coordinates for a mouse event, new DPI values for a DPI
change event). The specific structure type depends on the
EventType.
ProGUI also provides a DispatchEvent() function, which is
primarily used internally by the library to trigger the registered
handlers, but is also used by custom widgets to trigger events such as
#PG_Event_Action (and can potentially be used by developers
to simulate events if needed).
Core Event Functions
- AddEventHandler() - Registers a user-defined callback procedure to be executed when a specific event occurs for a given ProGUI Window or Widget.
- DispatchEvent() - Manually triggers or dispatches a specific event for a given ProGUI Window or Widget, calling all registered handlers.
Event Types
These are the constants used to identify different events:
#PG_Event_Draw- Sent when an object needs to redraw its main content. (Uses PG_EventDraw)#PG_Event_DrawForeground- Sent after the main content and child layouts are drawn, allowing for drawing on top. (Uses PG_EventDraw)#PG_Event_AnimateSkin- Sent during skin state transitions for custom animation logic. (Uses PG_EventAnimate)#PG_Event_Action- A general-purpose event, often triggered by user actions like clicking a button or changing a scrollbar position. (Data varies or is #Null)#PG_Event_Animate- Sent during animations managed by StartAnimation(). (Uses PG_EventAnimate)#PG_Event_MouseLeftButtonDown- Sent when the left mouse button is pressed over the object. (Uses PG_EventMouse)#PG_Event_MouseLeftButtonUp- Sent when the left mouse button is released over the object. (Uses PG_EventMouse)#PG_Event_MouseLeftDoubleClick- Sent on a left mouse button double-click. (Uses PG_EventMouse)#PG_Event_MouseEnter- Sent when the mouse cursor enters the object’s bounds. (Data is #Null)#PG_Event_MouseLeave- Sent when the mouse cursor leaves the object’s bounds. (Data is #Null)#PG_Event_MouseEnterContainer- Sent when the mouse cursor enters the widget’s bounds ignoring any nested child widgets. (Data is #Null)#PG_Event_MouseLeaveContainer- Sent when the mouse cursor leaves the widget’s bounds ignoring any nested child widgets. (Data is #Null)#PG_Event_MouseMove- Sent when the mouse cursor moves while over the object. (Uses PG_EventMouse)#PG_Event_MouseRightButtonDown- Sent when the right mouse button is pressed over the object. (Uses PG_EventMouse)#PG_Event_MouseRightButtonUp- Sent when the right mouse button is released over the object. (Uses PG_EventMouse)#PG_Event_MouseRightDoubleClick- Sent on a right mouse button double-click. (Uses PG_EventMouse)#PG_Event_MouseWheel- Sent when the mouse wheel is scrolled while the cursor is over the object. (Uses PG_EventMouse)#PG_Event_Destroy- Sent just before a widget or window object is freed. (Data is #Null)#PG_Event_WindowClose- Sent when the user attempts to close a window (e.g., by clicking the close button). (Data is #Null)#PG_Event_WindowActivate- Sent when a window becomes the active/focused window. (Data is #Null)#PG_Event_WindowDeactivate- Sent when a window loses active focus. (Data is #Null)#PG_Event_WindowMinimize- Sent when a window is minimized to the taskbar. (Data is #Null)#PG_Event_WindowMaximize- Sent when a window is maximized. (Data is #Null)#PG_Event_WindowRestore- Sent when a window is restored from a minimized or maximized state. (Data is #Null)#PG_Event_WindowTitle- Sent when a window’s title has been changed. (Data is the Window object pointer)#PG_Event_DPI- Sent when the window’s DPI (Dots Per Inch) changes, usually because it was moved to a monitor with different scaling settings. (Uses PG_EventDPI)
Note on Global Window Events: Events such as
#PG_Event_WindowClose,
#PG_Event_WindowActivate,
#PG_Event_WindowDeactivate,
#PG_Event_WindowMinimize,
#PG_Event_WindowMaximize,
#PG_Event_WindowRestore, and
#PG_Event_WindowTitle are classified internally as global
window events. If you bind these event types directly to a child Widget,
ProGUI will automatically route the parent window’s event down to that
Widget.
Animation Event States
The #PG_Event_Animate event uses the state
field in its PG_EventAnimate data
structure to indicate the phase of the animation:
#PG_Event_Animate_Start- Sent once at the beginning of the animation.#PG_Event_Animate_Update- Sent repeatedly during the animation’s duration.#PG_Event_Animate_End- Sent once when the animation completes or is stopped.
Event Data Structures
The *eventData pointer passed to event handlers points
to one of the following structures, depending on the
EventType:
- PG_EventDraw: Used
for
#PG_Event_Drawand#PG_Event_DrawForeground. Contains dimensions (DIPs and pixels) and DPI scaling factors. - PG_EventAnimate:
Used for
#PG_Event_Animateand#PG_Event_AnimateSkin. Contains animation state, timing information (duration, current time, delta time), object dimensions, and user data. - PG_EventDPI: Used
for
#PG_Event_DPI. Contains the new DPI values, scaling factors, and resulting window dimensions. - PG_EventMouse:
Used for all mouse events (
#PG_Event_Mouse...). Contains mouse coordinates (DIPs and pixels relative to the object), object dimensions, and wheel delta (for#PG_Event_MouseWheel). - (Implicit/Generic): For simple events like
#PG_Event_Action,#PG_Event_Destroy, or#PG_Event_WindowClose, the*eventDatamight be#Nullor point to a basic integer value representing relevant data (e.g., the new position for a scrollbar action). Check the specific widget’s documentation.