User Input Hook Registration

Register optional user-supplied callbacks that fire after the library has completed its own internal event processing. More...

Collaboration diagram for User Input Hook Registration:

Functions
BGI_API void BGI_CALL	wxbgi_set_char_hook (WxbgiCharHook cb)
	Registers a user hook invoked after each printable character input event.
BGI_API void BGI_CALL	wxbgi_set_cursor_pos_hook (WxbgiCursorPosHook cb)
	Registers a user hook invoked after every cursor position update.
BGI_API void BGI_CALL	wxbgi_set_key_hook (WxbgiKeyHook cb)
	Registers a user hook invoked after each key press, repeat, or release.
BGI_API void BGI_CALL	wxbgi_set_mouse_button_hook (WxbgiMouseButtonHook cb)
	Registers a user hook invoked after each mouse button press or release.
BGI_API void BGI_CALL	wxbgi_set_scroll_hook (WxbgiScrollHook cb)
	Registers a user hook invoked after each mouse scroll (wheel) event.

Action and button constants (mirror GLFW values)
Use these in hook implementations instead of including GLFW headers.
#define	WXBGI_KEY_PRESS   1
	Key or button pressed.
#define	WXBGI_KEY_RELEASE   0
	Key or button released.
#define	WXBGI_KEY_REPEAT   2
	Key held down (auto-repeat)
#define	WXBGI_MOUSE_LEFT   0
	Left mouse button.
#define	WXBGI_MOUSE_RIGHT   1
	Right mouse button.
#define	WXBGI_MOUSE_MIDDLE   2
	Middle mouse button.
#define	WXBGI_MOD_SHIFT   0x0001
	Shift modifier held.
#define	WXBGI_MOD_CTRL   0x0002
	Control modifier held.
#define	WXBGI_MOD_ALT   0x0004
	Alt modifier held.

Detailed Description

Register optional user-supplied callbacks that fire after the library has completed its own internal event processing.

The library retains ownership of all GLFW callbacks. These functions let you attach supplementary logic to keyboard and mouse events without interfering with the key queue, keyDown state, mouse position tracking, or the click-to-pick selection system.

Execution model: Each hook fires synchronously from within the corresponding GLFW callback, which executes while the library's internal mutex is held (inside glfwPollEvents()).

Warning

Hooks must not call any wxbgi_* function. Doing so will deadlock because the non-recursive internal mutex is already held. Safe operations from a hook: update your own variables, set flags, call non-wxbgi code.

Pass NULL to any registration function to remove a previously installed hook.

Macro Definition Documentation

WXBGI_KEY_PRESS

#define WXBGI_KEY_PRESS   1

Key or button pressed.

WXBGI_KEY_RELEASE

#define WXBGI_KEY_RELEASE   0

Key or button released.

WXBGI_KEY_REPEAT

#define WXBGI_KEY_REPEAT   2

Key held down (auto-repeat)

WXBGI_MOD_ALT

#define WXBGI_MOD_ALT   0x0004

Alt modifier held.

WXBGI_MOD_CTRL

#define WXBGI_MOD_CTRL   0x0002

Control modifier held.

WXBGI_MOD_SHIFT

#define WXBGI_MOD_SHIFT   0x0001

Shift modifier held.

WXBGI_MOUSE_LEFT

#define WXBGI_MOUSE_LEFT   0

Left mouse button.

WXBGI_MOUSE_MIDDLE

#define WXBGI_MOUSE_MIDDLE   2

Middle mouse button.

WXBGI_MOUSE_RIGHT

#define WXBGI_MOUSE_RIGHT   1

Right mouse button.

Function Documentation

wxbgi_set_char_hook()

BGI_API void BGI_CALL wxbgi_set_char_hook

(

WxbgiCharHook

cb

)

Registers a user hook invoked after each printable character input event.

Fires only for printable characters (Unicode codepoints 1–255 accepted by this library). Control characters (Tab=9, Enter=13, Escape=27) are handled by the key hook instead.

Parameters

cb	Function pointer to install, or NULL to remove the current hook.

wxbgi_set_cursor_pos_hook()

BGI_API void BGI_CALL wxbgi_set_cursor_pos_hook

(

WxbgiCursorPosHook

cb

)

Registers a user hook invoked after every cursor position update.

x and y are the cursor's new position in window pixels, origin at the top-left corner (same coordinate system as wxbgi_get_mouse_pos()).

Parameters

cb	Function pointer to install, or NULL to remove the current hook.

wxbgi_set_key_hook()

BGI_API void BGI_CALL wxbgi_set_key_hook

(

WxbgiKeyHook

cb

)

Registers a user hook invoked after each key press, repeat, or release.

The hook receives the same parameters as the GLFW key callback: key is a GLFW key constant (e.g. GLFW_KEY_ESCAPE = 256; plain ASCII letters use their uppercase ASCII code), scancode is the raw OS scancode, action is one of WXBGI_KEY_PRESS / WXBGI_KEY_RELEASE / WXBGI_KEY_REPEAT, and mods is a bitfield of WXBGI_MOD_SHIFT, WXBGI_MOD_CTRL, WXBGI_MOD_ALT.

Parameters

cb	Function pointer to install, or NULL to remove the current hook.

wxbgi_set_mouse_button_hook()

BGI_API void BGI_CALL wxbgi_set_mouse_button_hook

(

WxbgiMouseButtonHook

cb

)

Registers a user hook invoked after each mouse button press or release.

button is WXBGI_MOUSE_LEFT, WXBGI_MOUSE_RIGHT, or WXBGI_MOUSE_MIDDLE. action is WXBGI_KEY_PRESS or WXBGI_KEY_RELEASE. mods is a bitfield of modifier keys.

Note: the library's own pick/selection logic runs before this hook is called, so gState.selectedObjectIds already reflects the result of a left-click pick.

Parameters

cb	Function pointer to install, or NULL to remove the current hook.

wxbgi_set_scroll_hook()

BGI_API void BGI_CALL wxbgi_set_scroll_hook

(

WxbgiScrollHook

cb

)

Registers a user hook invoked after each mouse scroll (wheel) event.

xoffset is the horizontal scroll delta; yoffset is the vertical scroll delta (positive = scroll up/forward).

Parameters

cb	Function pointer to install, or NULL to remove the current hook.