event.h File Reference

This file contains structures and functions specific to the event system. Events are a mechenism that allows the developer to send and recieve data at critical points in the execution of the application in a non- coupled way. For now, this follows a simple pub-sub model of event transmission. More...

#include "defines.h"

Go to the source code of this file.

Data Structures
struct	event_context
	Represents event contextual data to be sent along with an event code when an event is fired. It is a union that is 128 bytes in size, meaning data can be mixed and matched as required by the developer. More...

Typedefs
typedef struct event_context	event_context
	Represents event contextual data to be sent along with an event code when an event is fired. It is a union that is 128 bytes in size, meaning data can be mixed and matched as required by the developer. More...
typedef b8(*	PFN_on_event) (u16 code, void *sender, void *listener_inst, event_context data)
	A function pointer typedef which is used for event subscriptions by the subscriber. More...
typedef enum system_event_code	system_event_code
	System internal event codes. Application should use codes beyond 255. More...

Enumerations
enum	system_event_code {   EVENT_CODE_APPLICATION_QUIT = 0x01 , EVENT_CODE_KEY_PRESSED = 0x02 , EVENT_CODE_KEY_RELEASED = 0x03 , EVENT_CODE_BUTTON_PRESSED = 0x04 ,   EVENT_CODE_BUTTON_RELEASED = 0x05 , EVENT_CODE_BUTTON_CLICKED = 0x06 , EVENT_CODE_MOUSE_MOVED = 0x07 , EVENT_CODE_MOUSE_WHEEL = 0x08 ,   EVENT_CODE_WINDOW_RESIZED = 0x09 , EVENT_CODE_SET_RENDER_MODE = 0x0A , EVENT_CODE_CLIPBOARD_PASTE = 0x0B , EVENT_CODE_DEBUG0 = 0x10 ,   EVENT_CODE_DEBUG1 = 0x11 , EVENT_CODE_DEBUG2 = 0x12 , EVENT_CODE_DEBUG3 = 0x13 , EVENT_CODE_DEBUG4 = 0x14 ,   EVENT_CODE_DEBUG5 = 0x15 , EVENT_CODE_DEBUG6 = 0x16 , EVENT_CODE_DEBUG7 = 0x17 , EVENT_CODE_DEBUG8 = 0x18 ,   EVENT_CODE_DEBUG9 = 0x19 , EVENT_CODE_DEBUG10 = 0x1A , EVENT_CODE_DEBUG11 = 0x1B , EVENT_CODE_DEBUG12 = 0x1C ,   EVENT_CODE_DEBUG13 = 0x1D , EVENT_CODE_DEBUG14 = 0x1E , EVENT_CODE_DEBUG15 = 0x1F , EVENT_CODE_OBJECT_HOVER_ID_CHANGED = 0x20 ,   EVENT_CODE_DEFAULT_RENDERTARGET_REFRESH_REQUIRED = 0x21 , EVENT_CODE_KVAR_CHANGED = 0x22 , EVENT_CODE_MOUSE_DRAGGED = 0x30 , EVENT_CODE_MOUSE_DRAG_BEGIN = 0x31 ,   EVENT_CODE_MOUSE_DRAG_END = 0x32 , EVENT_CODE_ANIMATION_STARTED = 0x33 , EVENT_CODE_ANIMATION_COMPLETE = 0x34 , EVENT_CODE_AUDIO_STARTED = 0x35 ,   EVENT_CODE_AUDIO_COMPLETE = 0x36 , MAX_EVENT_CODE = 0xFF }
	System internal event codes. Application should use codes beyond 255. More...

Functions
b8	event_system_initialize (u64 *memory_requirement, void *state, void *config)
	Initializes the event system. More...
void	event_system_shutdown (void *state)
	Shuts the event system down. More...
KAPI b8	event_register (u16 code, void *listener, PFN_on_event on_event)
	Register to listen for when events are sent with the provided code. Events with duplicate listener/callback combos will not be registered again and will cause this to return false. More...
KAPI b8	event_register_single (u16 code, void *listener, PFN_on_event on_event)
	Register to listen for when a single event is sent with the provided code. Events with duplicate listener/callback combos will not be registered again and will cause this to return false. More...
KAPI b8	event_unregister (u16 code, void *listener, PFN_on_event on_event)
	Unregister from listening for when events are sent with the provided code. If no matching registration is found, this function returns false. More...
KAPI b8	event_fire (u16 code, void *sender, event_context context)
	Fires an event to listeners of the given code. If an event handler returns true, the event is considered handled and is not passed on to any more listeners. More...

Detailed Description

This file contains structures and functions specific to the event system. Events are a mechenism that allows the developer to send and recieve data at critical points in the execution of the application in a non- coupled way. For now, this follows a simple pub-sub model of event transmission.

Author

Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Version

1.0

Date

2022-01-10

Copyright

Kohi Game Engine is Copyright (c) Travis Vroman 2021-2022

Typedef Documentation

event_context

typedef struct event_context event_context

Represents event contextual data to be sent along with an event code when an event is fired. It is a union that is 128 bytes in size, meaning data can be mixed and matched as required by the developer.

PFN_on_event

typedef b8(* PFN_on_event) (u16 code, void *sender, void *listener_inst, event_context data)

A function pointer typedef which is used for event subscriptions by the subscriber.

Parameters

code	The event code to be sent.
sender	A pointer to the sender of the event. Can be 0.
listener_inst	A pointer to the listener of the event. Can be 0.
data	The event context to be passed with the fired event.

Returns

True if the message should be considered handled, which means that it will not be sent to any other consumers; otherwise false.

system_event_code

typedef enum system_event_code system_event_code

System internal event codes. Application should use codes beyond 255.

Enumeration Type Documentation

system_event_code

enum system_event_code

System internal event codes. Application should use codes beyond 255.

Enumerator
EVENT_CODE_APPLICATION_QUIT	Shuts the application down on the next frame.
EVENT_CODE_KEY_PRESSED	Keyboard key pressed. Context usage: u16 key_code = data.data.u16[0]; u16 repeat_count = data.data.u16[1];.
EVENT_CODE_KEY_RELEASED	Keyboard key released. Context usage: u16 key_code = data.data.u16[0]; u16 repeat_count = data.data.u16[1];.
EVENT_CODE_BUTTON_PRESSED	Mouse button pressed. Context usage: u16 x = data.data.i16[0]; u16 y = data.data.i16[1]; u16 delta_x = data.data.i16[2]; u16 delta_y = data.data.i16[3]; u16 button = data.data.u16[4];.
EVENT_CODE_BUTTON_RELEASED	Mouse button released. Context usage: u16 x = data.data.i16[0]; u16 y = data.data.i16[1]; u16 delta_x = data.data.i16[2]; u16 delta_y = data.data.i16[3]; u16 button = data.data.u16[4];.
EVENT_CODE_BUTTON_CLICKED	Mouse button pressed then released. Context usage: u16 x = data.data.i16[0]; u16 y = data.data.i16[1]; u16 delta_x = data.data.i16[2]; u16 delta_y = data.data.i16[3]; u16 button = data.data.u16[4];.
EVENT_CODE_MOUSE_MOVED	Mouse moved. Context usage: u16 x = data.data.i16[0]; u16 y = data.data.i16[1]; u16 delta_x = data.data.i16[2]; u16 delta_y = data.data.i16[3];.
EVENT_CODE_MOUSE_WHEEL	Mouse moved. Context usage: u16 x = data.data.i16[0]; u16 y = data.data.i16[1]; u16 delta_x = data.data.i16[2]; u16 delta_y = data.data.i16[3]; ui z_delta = data.data.i8[8];.
EVENT_CODE_WINDOW_RESIZED	Resized/resolution of a window changed from the OS. Context usage: u16 width = data.data.u16[0]; u16 height = data.data.u16[1]; Sender is the window itself.
EVENT_CODE_SET_RENDER_MODE
EVENT_CODE_CLIPBOARD_PASTE	Clipboard content is ready to be retrieved. NOTE: data is freed by the platform immediately after this event is fired. Context usage: struct clipboard_context* = context.data.custom_data.data, (sizeof clipboard_context)
EVENT_CODE_DEBUG0	Special-purpose debugging event. Context will vary over time.
EVENT_CODE_DEBUG1	Special-purpose debugging event. Context will vary over time.
EVENT_CODE_DEBUG2	Special-purpose debugging event. Context will vary over time.
EVENT_CODE_DEBUG3	Special-purpose debugging event. Context will vary over time.
EVENT_CODE_DEBUG4	Special-purpose debugging event. Context will vary over time.
EVENT_CODE_DEBUG5
EVENT_CODE_DEBUG6
EVENT_CODE_DEBUG7
EVENT_CODE_DEBUG8
EVENT_CODE_DEBUG9
EVENT_CODE_DEBUG10
EVENT_CODE_DEBUG11
EVENT_CODE_DEBUG12
EVENT_CODE_DEBUG13
EVENT_CODE_DEBUG14
EVENT_CODE_DEBUG15
EVENT_CODE_OBJECT_HOVER_ID_CHANGED	The hovered-over object id, if there is one. Context usage: i32 id = context.data.u32[0]; - will be INVALID ID if nothing is hovered over.
EVENT_CODE_DEFAULT_RENDERTARGET_REFRESH_REQUIRED	An event fired by the renderer backend to indicate when any render targets associated with the default window resources need to be refreshed (i.e. a window resize)
EVENT_CODE_KVAR_CHANGED	An event fired by the kvar system when a kvar has been updated. Context usage: kvar_change* change = context.data.custom_data.data;.
EVENT_CODE_MOUSE_DRAGGED	An event fired while a button is being held down and the mouse is moved. Context usage: i16 x = context.data.i16[0] i16 y = context.data.i16[1] i16 delta_x = context.data.i16[2] i16 delta_y = context.data.i16[3] u16 button = context.data.u16[4]
EVENT_CODE_MOUSE_DRAG_BEGIN	An event fired when a button is pressed and a mouse movement is done while it is pressed. Context usage: i16 x = context.data.i16[0] i16 y = context.data.i16[1] i16 delta_x = context.data.i16[2] i16 delta_y = context.data.i16[3] u16 button = context.data.u16[4]
EVENT_CODE_MOUSE_DRAG_END	An event fired when a button is released was previously dragging. Context usage: i16 x = context.data.i16[0] i16 y = context.data.i16[1] i16 delta_x = context.data.i16[2] i16 delta_y = context.data.i16[3] u16 button = context.data.u16[4]
EVENT_CODE_ANIMATION_STARTED	An event fired when an animation starts. Context usage: kname animation_name = context.data.u64[0]
EVENT_CODE_ANIMATION_COMPLETE	An event fired when an animation completes. Context usage: kname animation_name = context.data.u64[0]
EVENT_CODE_AUDIO_STARTED	An event fired when an audio starts playing. Context usage: kname animation_name = context.data.u64[0]
EVENT_CODE_AUDIO_COMPLETE	An event fired when an audio completes. Context usage: kaudio base = context.data.u16[0] instance_id = context.data.u16[1]
MAX_EVENT_CODE	The maximum event code that can be used internally.

Function Documentation

event_fire()

KAPI b8 event_fire	(	u16	code,
		void *	sender,
		event_context	context
	)

Fires an event to listeners of the given code. If an event handler returns true, the event is considered handled and is not passed on to any more listeners.

Parameters

code	The event code to fire.
sender	A pointer to the sender. Can be 0/NULL.
data	The event data.

Returns

True if handled, otherwise false.

event_register()

KAPI b8 event_register	(	u16	code,
		void *	listener,
		PFN_on_event	on_event
	)

Register to listen for when events are sent with the provided code. Events with duplicate listener/callback combos will not be registered again and will cause this to return false.

Parameters

code	The event code to listen for.
listener	A pointer to a listener instance. Can be 0/NULL.
on_event	The callback function pointer to be invoked when the event code is fired.

Returns

True if the event is successfully registered; otherwise false.

event_register_single()

KAPI b8 event_register_single	(	u16	code,
		void *	listener,
		PFN_on_event	on_event
	)

Register to listen for when a single event is sent with the provided code. Events with duplicate listener/callback combos will not be registered again and will cause this to return false.

Note

: the event is automatically unregistered once fired a single time.

Parameters

code	The event code to listen for.
listener	A pointer to a listener instance. Can be 0/NULL.
on_event	The callback function pointer to be invoked when the event code is fired.

Returns

True if the event is successfully registered; otherwise false.

event_system_initialize()

b8 event_system_initialize	(	u64 *	memory_requirement,
		void *	state,
		void *	config
	)

Initializes the event system.

event_system_shutdown()

void event_system_shutdown

(

void *

state

)

Shuts the event system down.

event_unregister()

KAPI b8 event_unregister	(	u16	code,
		void *	listener,
		PFN_on_event	on_event
	)

Unregister from listening for when events are sent with the provided code. If no matching registration is found, this function returns false.

Parameters

code	The event code to stop listening for.
listener	A pointer to a listener instance. Can be 0/NULL.
on_event	The callback function pointer to be unregistered.

Returns

True if the event is successfully unregistered; otherwise false.