- Generated on for Banjo API by
1.14.0
|
Banjo API 1.0.0-rc.2
Low-level C99 game development API
|
Data Structures | |
| struct | bj_enter_event |
| struct | bj_cursor_event |
| struct | bj_button_event |
| struct | bj_key_event |
| struct | bj_event |
| union | bj_event.as |
Typedefs | |
| typedef enum bj_key | bj_key |
| typedef enum bj_event_action | bj_event_action |
| typedef enum bj_event_type | bj_event_type |
| typedef void(* | bj_enter_callback_fn) (struct bj_window *window, const struct bj_enter_event *event, void *user_data) |
| typedef void(* | bj_cursor_callback_fn) (struct bj_window *window, const struct bj_cursor_event *event, void *user_data) |
| typedef void(* | bj_button_callback_fn) (struct bj_window *window, const struct bj_button_event *event, void *user_data) |
| typedef void(* | bj_key_callback_fn) (struct bj_window *window, const struct bj_key_event *event, void *user_data) |
Pick up keyboard, mouse, and window-focus events from the user.
As the user presses keys, moves the mouse, clicks buttons, or hovers in and out of your window, the operating system collects these moments and hands them to your program. Banjo gathers them into a single queue of events that you process once per frame. There are four event types:
BJ_EVENT_KEY**: a keyboard key was pressed, released, or is being held down repeatedly. Carries the key identifier (e.g. BJ_KEY_W) and the action.BJ_EVENT_BUTTON**: a mouse button was pressed or released. Carries the button identifier and cursor position.BJ_EVENT_CURSOR**: the mouse cursor moved. Carries the new position.BJ_EVENT_ENTER**: the cursor entered or left the window's area.Banjo offers two styles for consuming events. Both work; pick whichever fits the shape of your program.
happens)
You register a function of yours that Banjo will call whenever the matching event arrives. One register-function per event type: bj_set_cursor_callback, bj_set_button_callback, bj_set_key_callback, bj_set_enter_callback. Then, each frame, you call bj_dispatch_events once and Banjo runs your registered functions for every event that's waiting.
The register functions return the previously installed callback, so you can save it and call it from your new callback to chain handlers if you need to. The built-in bj_close_on_escape can be handed straight to bj_set_key_callback for one-line ESC-to-quit support. That's the shortcut start.c uses.
Instead of registering callbacks, you call bj_poll_events in a loop and Banjo hands you one event at a time until the queue is empty. You decide what to do with each one. This style fits programs whose response to an event depends on per-frame state (so you don't want a callback firing whenever, you want to process events at a specific moment in your update loop) or that need to filter or batch.
You can mix the two styles: a polled event you don't care about can be forwarded to the global callbacks via bj_dispatch_event.
bj_key values follow Microsoft's Virtual-Key codes (so BJ_KEY_A == 0x41, matching ASCII for letters/digits). The aliases at the bottom of this header (BJ_KEY_BACKSPACE, BJ_KEY_ENTER, BJ_KEY_LEFT_ALT, …) wrap the OEM/Windows-style names with their common labels.
Key-repeat events (BJ_REPEAT) only fire on windows that were created with the BJ_WINDOW_FLAG_KEY_REPEAT flag.
event_callbacks.c (callback flow) and event_polling.c (polling flow) for runnable demos. The window subsystem itself is documented under Windows. | struct bj_enter_event |
Represent a mouse enter or leave event.
| Data Fields | ||
|---|---|---|
| bj_bool | enter | BJ_TRUE if entering window, BJ_FALSE if leaving. |
| int | x | Cursor x position. |
| int | y | Cursor y position. |
| struct bj_cursor_event |
Represent a mouse cursor movement event.
| Data Fields | ||
|---|---|---|
| int | x | Cursor x position. |
| int | y | Cursor y position. |
| struct bj_button_event |
| Data Fields | ||
|---|---|---|
| enum bj_event_action | action | Action (press/release) |
| int | button | Button identifier (e.g., BJ_BUTTON_LEFT) |
| int | x | Cursor x position. |
| int | y | Cursor y position. |
| struct bj_key_event |
Represent a keyboard key event.
| Data Fields | ||
|---|---|---|
| enum bj_event_action | action | Action (press/release/repeat) |
| enum bj_key | key | Key identifier. |
| int | scancode | Scancode (layout-independent) |
| struct bj_event |
Represent a generic window-related event.
This union-based structure wraps all types of input events.
| Data Fields | ||
|---|---|---|
| union bj_event.as | as | |
| enum bj_event_type | type | Type of event. |
| struct bj_window * | window | Target window. |
| union bj_event.as |
| Data Fields | ||
|---|---|---|
| struct bj_button_event | button | Button event data. |
| struct bj_cursor_event | cursor | Cursor event data. |
| struct bj_enter_event | enter | Enter/leave event data. |
| struct bj_key_event | key | Key event data. |
| #define BJ_BUTTON_DOWN BJ_BUTTON_5 |
| #define BJ_BUTTON_LEFT BJ_BUTTON_1 |
| #define BJ_BUTTON_MIDDLE BJ_BUTTON_2 |
| #define BJ_BUTTON_RIGHT BJ_BUTTON_3 |
| #define BJ_BUTTON_UP BJ_BUTTON_4 |
| #define BJ_KEY_APOSTROPHE BJ_KEY_OEM_7 |
Alias for BJ_KEY_OEM_7.
| #define BJ_KEY_BACKSLASH BJ_KEY_OEM_5 |
Alias for BJ_KEY_OEM_5.
| #define BJ_KEY_BACKSPACE BJ_KEY_BACK |
Alias for BJ_KEY_BACK.
| #define BJ_KEY_CAPSLOCK BJ_KEY_CAPITAL |
Alias for BJ_KEY_CAPITAL.
| #define BJ_KEY_COMMA BJ_KEY_OEM_COMMA |
Alias for BJ_KEY_OEM_COMMA.
| #define BJ_KEY_ENTER BJ_KEY_RETURN |
Alias for BJ_KEY_RETURN.
| #define BJ_KEY_GRAVE_ACCENT BJ_KEY_OEM_3 |
Alias for BJ_KEY_OEM_3.
| #define BJ_KEY_HANGUL BJ_KEY_KANA |
Alias for BJ_KEY_KANA.
| #define BJ_KEY_HANJA BJ_KEY_KANJI |
Alias for BJ_KEY_KANJI.
| #define BJ_KEY_LEFT_ALT BJ_KEY_LMENU |
Alias for BJ_KEY_LMENU.
| #define BJ_KEY_LEFT_BRACKET BJ_KEY_OEM_4 |
Alias for BJ_KEY_OEM_4.
| #define BJ_KEY_LEFT_CONTROL BJ_KEY_LCONTROL |
Alias for BJ_KEY_LCONTROL.
| #define BJ_KEY_LEFT_OS BJ_KEY_LWIN |
Alias for BJ_KEY_LWIN.
| #define BJ_KEY_LEFT_SHIT BJ_KEY_LSHIFT |
Alias for BJ_KEY_LSHIFT.
| #define BJ_KEY_MINUS BJ_KEY_OEM_MINUS |
Alias for BJ_KEY_OEM_MINUS.
| #define BJ_KEY_PAGE_DOWN BJ_KEY_NEXT |
Alias for BJ_KEY_NEXT.
| #define BJ_KEY_PAGE_UP BJ_KEY_PRIOR |
Alias for BJ_KEY_PRIOR.
| #define BJ_KEY_PERIOD BJ_KEY_OEM_PERIOD |
Alias for BJ_KEY_OEM_PERIOD.
| #define BJ_KEY_PLUS BJ_KEY_OEM_PLUS |
Alias for BJ_KEY_OEM_PLUS.
| #define BJ_KEY_PRINT_SCREEN BJ_KEY_SNAPSHOT |
Alias for BJ_KEY_SNAPSHOT.
| #define BJ_KEY_RIGHT_ALT BJ_KEY_RMENU |
Alias for BJ_KEY_RMENU.
| #define BJ_KEY_RIGHT_BRACKET BJ_KEY_OEM_6 |
Alias for BJ_KEY_OEM_6.
| #define BJ_KEY_RIGHT_CONTROL BJ_KEY_RCONTROL |
Alias for BJ_KEY_RCONTROL.
| #define BJ_KEY_RIGHT_OS BJ_KEY_RWIN |
Alias for BJ_KEY_RWIN.
| #define BJ_KEY_RIGHT_SHIFT BJ_KEY_RSHIFT |
Alias for BJ_KEY_RSHIFT.
| #define BJ_KEY_SEMICOLON BJ_KEY_OEM_1 |
Alias for BJ_KEY_OEM_1.
| #define BJ_KEY_SLASH BJ_KEY_OEM_2 |
Alias for BJ_KEY_OEM_2.
| typedef void(* bj_button_callback_fn) (struct bj_window *window, const struct bj_button_event *event, void *user_data) |
Define the callback type for mouse button events.
Called when a mouse button is pressed or released.
| typedef void(* bj_cursor_callback_fn) (struct bj_window *window, const struct bj_cursor_event *event, void *user_data) |
Define the callback type for cursor movement events.
Called when the cursor moves inside a window.
| typedef void(* bj_enter_callback_fn) (struct bj_window *window, const struct bj_enter_event *event, void *user_data) |
Define the callback type for enter events.
Called when the cursor enters or exits a window.
| typedef enum bj_event_action bj_event_action |
| typedef enum bj_event_type bj_event_type |
| typedef void(* bj_key_callback_fn) (struct bj_window *window, const struct bj_key_event *event, void *user_data) |
Define the callback type for keyboard key events.
Called when a key is pressed, released, or repeated.
| enum bj_event_action |
| enum bj_event_type |
| enum bj_key |
List of possible keys on a keyboard.
The values are directly taken from the [VK codes in Microsoft API] (https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) This also includes the annotated documentation of each key.
Even if all values from the abovementioned page are present in this enum, not all are used by Banjo and some are never returned by key events.
Values for 0-9 and A-Z keys directly directly correspond to their ASCII equivalent.
| void bj_close_on_escape | ( | struct bj_window * | window, |
| const struct bj_key_event * | event, | ||
| void * | user_data ) |
Handle the ESC key to close a window.
This utility callback closes the window when BJ_KEY_ESCAPE is pressed. Can be passed directly to bj_set_key_callback or called manually by your event system.
| window | Target window pointer (must not be NULL). |
| event | Key event data (must not be NULL). |
| user_data | Opaque user pointer provided at callback registration. Not used by this function. |
Referenced by setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), and setup().
| void bj_dispatch_event | ( | const struct bj_event * | event | ) |
Dispatch a single event to registered callbacks.
Invokes the appropriate callback(s) associated with the event type. Does not take ownership of event; the caller manages its lifetime.
| event | Pointer to the event to dispatch (must not be NULL). |
| void bj_dispatch_events | ( | void | ) |
Poll and dispatch all pending events.
This function checks for new input events and invokes the appropriate registered callbacks.
Referenced by step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), and step().
| const char * bj_key_name | ( | int | key | ) |
Get the string name of a key.
Return a string representing the key code. The returned string omits the BJ_KEY_ prefix.
| key | The bj_key value. |
Referenced by key_callback(), and step().
Poll the next pending event from the system queue.
Retrieves and removes the next event, if any.
If no events are available, returns BJ_FALSE and does not modify event.
| event | Pointer to a struct bj_event structure to be filled (must not be NULL). |
| BJ_TRUE | An event was retrieved and written to event. |
| BJ_FALSE | No event available. |
Referenced by step().
| void bj_push_button_event | ( | struct bj_window * | window, |
| int | button, | ||
| enum bj_event_action | action, | ||
| int | x, | ||
| int | y ) |
Push a mouse button event.
Represents a mouse button press or release within a window.
| window | Pointer to the window receiving the event. |
| button | The mouse button identifier. |
| action | The action performed (press or release). |
| x | The x-coordinate of the cursor at the event. |
| y | The y-coordinate of the cursor at the event. |
| void bj_push_cursor_event | ( | struct bj_window * | window, |
| int | x, | ||
| int | y ) |
Push a cursor movement event.
Indicates the cursor has moved within the specified window.
| window | Pointer to the window receiving the event. |
| x | The new x-coordinate of the cursor. |
| y | The new y-coordinate of the cursor. |
Push an enter or leave window event.
Indicates whether the cursor entered or left the specified window.
| window | Pointer to the window receiving the event. |
| enter | BJ_TRUE if cursor entered the window, BJ_FALSE if left. |
| x | The x-coordinate of the cursor at the event. |
| y | The y-coordinate of the cursor at the event. |
| void bj_push_event | ( | const struct bj_event * | e | ) |
Push a custom event to the internal event queue.
Typically used by the platform backend to post low-level events into the event processing system.
| e | Pointer to the event to push. |
| void bj_push_key_event | ( | struct bj_window * | window, |
| enum bj_event_action | action, | ||
| enum bj_key | key, | ||
| int | scancode ) |
Push a keyboard event into the event system.
This function creates and queues a keyboard event reflecting a key press, release, or repeat.
| window | Pointer to the window receiving the event. |
| action | The key event action (press, release, repeat). |
| key | The key code that triggered the event. |
| scancode | The platform-specific scancode of the key. |
| bj_button_callback_fn bj_set_button_callback | ( | bj_button_callback_fn | callback, |
| void * | user_data ) |
Set the global callback for mouse button events.
| callback | The new callback function |
| user_data | Location to user-provided data. |
Referenced by setup().
| bj_cursor_callback_fn bj_set_cursor_callback | ( | bj_cursor_callback_fn | callback, |
| void * | user_data ) |
Set the global callback for cursor events.
| callback | The new callback function |
| user_data | Location to user-provided data. |
Referenced by setup().
| bj_enter_callback_fn bj_set_enter_callback | ( | bj_enter_callback_fn | callback, |
| void * | user_data ) |
Set the global callback for mouse enter/leave events.
| callback | The new callback function |
| user_data | Location to user-provided data. |
Referenced by setup().
| bj_key_callback_fn bj_set_key_callback | ( | bj_key_callback_fn | callback, |
| void * | user_data ) |
Set the global callback for keyboard key events.
| callback | The new callback function |
| user_data | Location to user-provided data. |
Referenced by setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), and setup().
1.14.0