events.h File Reference

Events API for CmdFX. More...

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_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.
#define	CMDFX_EVENT_MOUSE   2
	Called when the mouse is moved or clicked.

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 int(*	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, EventCallback callback)
	Adds an event listener.
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 EventCallback **	dispatchCmdFXEvent (CmdFX_Event *event)
	Dispatches an event.
int	beginCmdFXEventLoop ()
	Starts the event loop for CmdFX.
int	endCmdFXEventLoop ()
	Ends the event loop for CmdFX.

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.

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_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.

Function Documentation

addCmdFXEventListener()

int addCmdFXEventListener	(	unsigned int	id,
		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 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()

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.