button.h File Reference

Button declarations for the CmdFX UI Library. More...

#include "cmdfx/core/sprites.h"
#include "cmdfx/core/events.h"

Go to the source code of this file.

Classes
struct	CmdFX_Button
	Represents a CmdFX button. More...

Typedefs
typedef void(*	CmdFX_ButtonCallback) (void *button, CmdFX_MouseEvent *event, unsigned long long time)
	The callback function to be called when the button is clicked.
typedef struct CmdFX_Button	CmdFX_Button
	Represents a CmdFX button.

Functions
CmdFX_Button **	Canvas_getRegisteredButtons ()
	Gets an array of registered buttons.
int	Canvas_getRegisteredButtonsCount ()
	Gets the number of registered buttons.
CmdFX_Button *	Button_create (CmdFX_Sprite *sprite, CmdFX_ButtonCallback callback)
	Creates a new button.
CmdFX_Button *	Button_createFilled (int width, int height, char c, char *ansi, int z, CmdFX_ButtonCallback callback)
	Creates a new filled button.
void	Button_free (CmdFX_Button *button)
	Frees the memory associated with a button.
int	Button_draw (int x, int y, CmdFX_Button *button)
	Draws the button on the screen.
int	Button_remove (CmdFX_Button *button)
	Removes a button from the UI manager.
int	Button_isHidden (CmdFX_Button *button)
	Checks if a button is hidden.
int	Button_hide (CmdFX_Button *button)
	Hides a button from the UI manager.
int	Button_show (CmdFX_Button *button)
	Shows a button in the UI manager if it is already hidden.
CmdFX_Button **	Canvas_getAllButtonsAt (int x, int y)
	Gets all buttons at the given position.
CmdFX_Button *	Canvas_getButtonAt (int x, int y)
	Gets the button at the given position.
int	Button_setData (CmdFX_Button *button, char **data, char ***ansi)
	Sets the data for a button.

Detailed Description

Button declarations for the CmdFX UI Library.

Author

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

Version

0.2.0

Date

2025-04-14

Copyright

Copyright (c) 2025

Typedef Documentation

CmdFX_Button

typedef struct CmdFX_Button CmdFX_Button

Represents a CmdFX button.

Buttons are objects that can be clicked on by the user and perform an action when clicked. Buttons have a sprite for visual implementation while also including a callback function to be called when the button is clicked.

CmdFX_ButtonCallback

typedef void(* CmdFX_ButtonCallback) (void *button, CmdFX_MouseEvent *event, unsigned long long time)

The callback function to be called when the button is clicked.

This function is called when the button is clicked. The function should take a pointer to the button and a pointer to the mouse event as parameters. The function should return nothing.

Parameters

button	The button that was clicked.
event	The mouse event that triggered the callback.
time	The time at which the event occurred.

Function Documentation

Button_create()

CmdFX_Button * Button_create	(	CmdFX_Sprite *	sprite,
		CmdFX_ButtonCallback	callback )

Creates a new button.

This function creates a new button with the given sprite and callback function. The button is not added to the UI manager, so it must be added manually.

Parameters

sprite	The sprite to use for the button.
callback	The callback function to call when the button is clicked.

Returns

CmdFX_Button* A pointer to the newly created button.

Button_createFilled()

CmdFX_Button * Button_createFilled	(	int	width,
		int	height,
		char	c,
		char *	ansi,
		int	z,
		CmdFX_ButtonCallback	callback )

Creates a new filled button.

This function creates a new filled button with the given width, height, character, and callback function. The button is not added to the UI manager, so it must be added manually.

Parameters

width	The width of the button.
height	The height of the button.
c	The character to use for the button.
ansi	The ANSI color codes to use for the button.
z	The Z-index of the button.
callback	The callback function to call when the button is clicked.

Returns

CmdFX_Button* A pointer to the newly created filled button.

Button_draw()

int Button_draw	(	int	x,
		int	y,
		CmdFX_Button *	button )

Draws the button on the screen.

This function draws the button on the screen at the given position. The button is drawn using the sprite associated with the button. The Z-index of the button is set to the current Z-index of its sprite.

Parameters

x	The x position to draw the button at.
y	The y position to draw the button at.
button	The button to draw.

Returns

0 if successful, else -1

Button_free()

void Button_free

(

CmdFX_Button *

button

)

Frees the memory associated with a button.

This function frees the memory associated with the given button. The button will no longer be valid after this function is called. The sprite associated with the button is also freed.

Parameters

button

The button to free.

Button_hide()

int Button_hide

(

CmdFX_Button *

button

)

Hides a button from the UI manager.

This function hides the given button from the UI manager. The button will still be present and will respond to mouse events, but it will not be rendered on the screen. This is useful for temporarily hiding a button without removing it from the UI manager.

Parameters

button

The button to hide.

Returns

0 if successful, else -1

Button_isHidden()

int Button_isHidden

(

CmdFX_Button *

button

)

Checks if a button is hidden.

This function checks if the given button is hidden from the UI manager. A button is considered hidden if it is not rendered on the screen and does not respond to mouse events.

Parameters

button

The button to check.

Returns

1 if the button is hidden, 0 otherwise.

Button_remove()

int Button_remove

(

CmdFX_Button *

button

)

Removes a button from the UI manager.

This function removes the given button from the UI manager. The button will no longer be rendered on the screen and will not respond to mouse events.

Parameters

button

The button to remove.

Returns

0 if successful, else -1

Button_setData()

int Button_setData	(	CmdFX_Button *	button,
		char **	data,
		char ***	ansi )

Sets the data for a button.

This function sets the data for the given button. The data is specified by the data and ansi parameters. The data is a string that is displayed on the button, and the ansi parameter is an array of ANSI escape codes that are applied to the data.

This will also redraw the button if it is currently shown.

Parameters

button	The button to set the data for.
data	The data to set for the button.
ansi	The ANSI escape codes to apply to the data.

Returns

0 if successful, else -1

Button_show()

int Button_show

(

CmdFX_Button *

button

)

Shows a button in the UI manager if it is already hidden.

This function shows the given button in the UI manager. The button will be rendered on the screen and will respond to mouse events.

Parameters

button

The button to show.

Returns

0 if successful, else -1

Canvas_getAllButtonsAt()

CmdFX_Button ** Canvas_getAllButtonsAt	(	int	x,
		int	y )

Gets all buttons at the given position.

This function returns an array of all buttons at the given position. The position is specified by the x and y coordinates. If there are no buttons at the given position, this function returns NULL.

The array must freed after use. The array is terminated with a NULL pointer.

Parameters

x	The x position to check.
y	The y position to check.

Returns

An array of pointers to the buttons at the given position, or NULL if no buttons are found.

Canvas_getButtonAt()

CmdFX_Button * Canvas_getButtonAt	(	int	x,
		int	y )

Gets the button at the given position.

This function returns the button at the given position with the highest z-index. The position is specified by the x and y coordinates. If there is no button at the given position, this function returns NULL.

Parameters

x	The x position to check.
y	The y position to check.

Returns

A pointer to the button at the given position, or NULL if no button is found.

Canvas_getRegisteredButtons()

CmdFX_Button ** Canvas_getRegisteredButtons

(

)

Gets an array of registered buttons.

This function returns the number of buttons that are currently registered with the UI manager. This includes all buttons that have been created and added to the UI manager.

Returns

An array of pointers to the registered buttons on the terminal screen.

Canvas_getRegisteredButtonsCount()

int Canvas_getRegisteredButtonsCount

(

)

Gets the number of registered buttons.

This function returns the number of buttons that are currently registered with the UI manager. This includes all buttons that have been created and added to the UI manager.

Returns

int The number of registered buttons.