events.h File Reference

Events API for CmdFX. More...

#include <stdbool.h>

Go to the source code of this file.

Classes
struct	CmdFX_ResizeEvent
	The payload for the CMDFX_EVENT_RESIZE event. More...
struct	CmdFX_KeyEvent
	The payload for the CMDFX_EVENT_KEY event. More...
struct	CmdFX_MouseEvent
	The payload for the CMDFX_EVENT_MOUSE event. More...
struct	CmdFX_ButtonEvent
	Called when a button is clicked. More...
struct	CmdFX_Event
	The main event structure for CmdFX. More...

Macros
#define	EVENT_TICK   10
	The time between event loop iterations, in milliseconds.
#define	CMDFX_EVENT_RESIZE   0
	Called when the terminal is resized.
#define	CMDFX_EVENT_KEY   1
	Called when a key is pressed or released.
#define	CMDFX_EVENT_MOUSE   2
	Called when the mouse is moved or clicked.
#define	CMDFX_EVENT_BUTTON_CLICK   3

Typedefs
typedef struct CmdFX_ResizeEvent	CmdFX_ResizeEvent
	The payload for the CMDFX_EVENT_RESIZE event.
typedef struct CmdFX_KeyEvent	CmdFX_KeyEvent
	The payload for the CMDFX_EVENT_KEY event.
typedef struct CmdFX_MouseEvent	CmdFX_MouseEvent
	The payload for the CMDFX_EVENT_MOUSE event.
typedef struct CmdFX_ButtonEvent	CmdFX_ButtonEvent
	Called when a button is clicked.
typedef int(*	CmdFX_EventCallback) (struct CmdFX_Event *event)
	Represents an event callback.
typedef struct CmdFX_Event	CmdFX_Event
	The main event structure for CmdFX.

Functions
int	addCmdFXEventListener (unsigned int id, CmdFX_EventCallback callback)
	Adds an event listener.
CmdFX_EventCallback *	getCmdFXEventListener (unsigned int eventId, unsigned int listenerId)
	Gets an event listener.
int	removeCmdFXEventListener (unsigned int eventId, unsigned int listenerId)
	Removes an event listener.
const CmdFX_EventCallback **	dispatchCmdFXEvent (CmdFX_Event *event)
	Dispatches an event.
int	beginCmdFXEventLoop ()
	Starts the event loop for CmdFX.
int	endCmdFXEventLoop ()
	Ends the event loop for CmdFX.
void	shutdownCmdFXEvents ()
	Removes all event listeners.

Detailed Description

Events API for CmdFX.

Author

Gregory Mitchell (me@gm.nosp@m.itch.nosp@m.215.x.nosp@m.yz)

Version

0.1.0

Date

2025-01-20

Copyright

Copyright (c) 2025

Macro Definition Documentation

CMDFX_EVENT_KEY

#define CMDFX_EVENT_KEY   1

Called when a key is pressed or released.

The data is a pointer to a struct CmdFX_KeyEvent.

CMDFX_EVENT_MOUSE

#define CMDFX_EVENT_MOUSE   2

Called when the mouse is moved or clicked.

The data is a pointer to a struct CmdFX_MouseEvent.

CMDFX_EVENT_RESIZE

#define CMDFX_EVENT_RESIZE   0

Called when the terminal is resized.

The data is a pointer to a struct CmdFX_ResizeEvent.

EVENT_TICK

#define EVENT_TICK   10

The time between event loop iterations, in milliseconds.

This value is used to determine how often the event loop should check for events. A lower value will result in more frequent event checks, but may consume more CPU resources. A higher value will result in less frequent event checks, but may cause events to be missed. This is usually set to avoid a "busy loop" that consumes too many resources.

The value used for CmdFX events is 10 milliseconds.

Typedef Documentation

CmdFX_ButtonEvent

typedef struct CmdFX_ButtonEvent CmdFX_ButtonEvent

Called when a button is clicked.

The data is a pointer to a struct CmdFX_ButtonEvent.

CmdFX_Event

typedef struct CmdFX_Event CmdFX_Event

The main event structure for CmdFX.

Parameters

id	The event ID.
time	The time the event was created, in milliseconds.
data	A pointer to the data associated with the event.

CmdFX_EventCallback

typedef int(* CmdFX_EventCallback) (struct CmdFX_Event *event)

Represents an event callback.

Parameters

event

The event that was dispatched.

Returns

0 if the event handler was called successfully. Any other integer value if an error occurred.

Function Documentation

addCmdFXEventListener()

int addCmdFXEventListener	(	unsigned int	id,
		CmdFX_EventCallback	callback )

Adds an event listener.

The listener will be called when the event with the specified ID is dispatched. The library has an internal limit of 1,024 listeners across all events.

Parameters

id	The event ID.
callback	The event callback.

Returns

A unique ID for the event listener, or -1 if an error occurred.

beginCmdFXEventLoop()

int beginCmdFXEventLoop

(

)

Starts the event loop for CmdFX.

This method is called automatically if a listener is added.

Returns

1 if the event loop was started successfully, 0 if an error occurred or the event loop is already running.

dispatchCmdFXEvent()

const CmdFX_EventCallback ** dispatchCmdFXEvent

(

CmdFX_Event *

event

)

Dispatches an event.

Parameters

event

The event to dispatch.

Returns

Addresses of the event listeners that were called.

endCmdFXEventLoop()

int endCmdFXEventLoop

(

)

Ends the event loop for CmdFX.

Returns

1 if the event loop was ended successfully, 0 if an error occurred or the event loop is not running.

getCmdFXEventListener()

CmdFX_EventCallback * getCmdFXEventListener	(	unsigned int	eventId,
		unsigned int	listenerId )

Gets an event listener.

Parameters

eventId	The ID of the event to remove the listener from.
listenerId	The ID of the event listener to retrieve.

Returns

The event listener, or NULL if the listener does not exist.

removeCmdFXEventListener()

int removeCmdFXEventListener	(	unsigned int	eventId,
		unsigned int	listenerId )

Removes an event listener.

Parameters

eventId	The ID of the event to remove the listener from.
listenerId	The ID of the event listener to remove.

Returns

1 if the listener was removed successfully, or 0 if an error occurred.