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 can potentially be used by developers to simulate events if needed.
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. (Uses PG_EventMouse)#PG_Event_MouseLeave- Sent when the mouse cursor leaves the object's bounds. (Uses PG_EventMouse)#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_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)
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 `*eventData` might 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.