Tools for drawing interactive GUI elements in a RetroFlat program. More...

Collaboration diagram for RetroGUI API:

Topics
	RetroGUI Overrideable Config
	Options to configure RetroGUI behavior defined at compile time.

	RetroGUI Controls

Files
file	retrogui.h

Data Structures
struct	RETROGUI

Macros
#define	RETROGUI_TRACE_LVL 0

#define	RETROGUI_FLAGS_DIRTY 0x01
	RETROGUI::flags indicating controls should be redrawn.

#define	RETROGUI_FLAGS_FONT_OWNED 0x02
	RETROGUI::flags indicating GUI font is owned by this RETROGUI and can/will be freed by retrogui_destroy().

#define	RETROGUI_FILLBAR_FLAG_SHOWNUM 0x02

#define	_retrogui_copy_str(field, src_str, dest_ctl, str_tmp, str_sz)

#define	RETROGUI_IDC_NONE 0

#define	retrogui_focus_next(gui)

#define	retrogui_focus_prev(gui)

#define	RETROGUI_CTL_TABLE_CONSTS(idx, c_name, c_fields)

Typedefs
typedef int16_t	retrogui_idc_t
	Unique identifying constant number for controls.

typedef void(*	retrogui_xy_cb) (retroflat_pxxy_t x, retroflat_pxxy_t y, void *data)

Functions
MERROR_RETVAL	retrogui_push_listbox_item (struct RETROGUI gui, retrogui_idc_t idc, const char item, size_t item_sz)

retrogui_idc_t	retrogui_poll_ctls (struct RETROGUI gui, RETROFLAT_IN_KEY p_input, struct RETROFLAT_INPUT *input_evt)
	Poll for the last clicked control and maintain listboxes and menus.

MERROR_RETVAL	retrogui_redraw_ctls (struct RETROGUI *gui)

MERROR_RETVAL	retrogui_sz_ctl (struct RETROGUI gui, retrogui_idc_t idc, retroflat_pxxy_t p_w, retroflat_pxxy_t *p_h, retroflat_pxxy_t max_w, retroflat_pxxy_t max_h)

MERROR_RETVAL	retrogui_pos_ctl (struct RETROGUI *gui, retrogui_idc_t idc, retroflat_pxxy_t x, retroflat_pxxy_t y, retroflat_pxxy_t w, retroflat_pxxy_t h)

MERROR_RETVAL	retrogui_push_ctl (struct RETROGUI gui, union RETROGUI_CTL ctl)

MERROR_RETVAL	retrogui_set_font (struct RETROGUI gui, const char font_path)
	Load the RetroFont API for the given RETROGUI to draw its controls with. Use RetroGXCache API if available.

MERROR_RETVAL	retrogui_get_ctl_text (struct RETROGUI gui, retrogui_idc_t idc, char buffer, size_t buffer_sz)

ssize_t	retrogui_get_ctl_sel_idx (struct RETROGUI *gui, retrogui_idc_t idc)

MERROR_RETVAL	retrogui_set_ctl_text (struct RETROGUI gui, retrogui_idc_t idc, size_t buffer_sz, const char fmt,...)

MERROR_RETVAL	retrogui_set_ctl_image (struct RETROGUI gui, retrogui_idc_t idc, const char path, uint8_t flags)
	Set the image displayed by an IMAGE-type RETROGUI_CTL.

MERROR_RETVAL	retrogui_set_ctl_level (struct RETROGUI *gui, retrogui_idc_t idc, uint16_t level, uint16_t max, uint8_t flags)
	Set the current progress level displayed by a FILLBAR-type RETROGUI_CTL.

MERROR_RETVAL	retrogui_init_ctl (union RETROGUI_CTL *ctl, uint8_t type, size_t idc)

retrogui_idc_t	retrogui_focus_iter (struct RETROGUI *gui, size_t start, ssize_t incr)
	Increment RETROGUI::focus, skipping elements that cannot hold focus.

MERROR_RETVAL	retrogui_init (struct RETROGUI *gui)
	Prepare a RETROGUI controller for use.

MERROR_RETVAL	retrogui_remove_ctl (struct RETROGUI *gui, retrogui_idc_t idc)
	Remove a control with the given unique identifier index from the given RETROGUI controller.

MERROR_RETVAL	retrogui_destroy (struct RETROGUI *gui)
	Free memory held by a RETROGUI controller internally and clean up any subordinate controls.

Detailed Description

Tools for drawing interactive GUI elements in a RetroFlat program.

This library works well with the RetroFlat Window API.

RetroGUI Example

Here is a brief example of how to create a RETROGUI with a button, a LABEL, and a FILLBAR.This example presumes that gui_p EITHER points to a separate RETROGUI that has been created on the stack and had retrogui_init() called on it, OR it is set to win->gui_p from the RetroWin Example.

  / * These are arbitrary; they only must be unique! * /
  # define EXAMPLE_IDC_LABEL    10
  # define EXAMPLE_IDC_BUTTON   20
  # define EXAMPLE_IDC_FILLBAR  30

  / * Insert the label control. * /

  retrogui_init_ctl( &ctl, RETROGUI_CTL_TYPE_LABEL, EXAMPLE_IDC_LABEL );

  ctl.base.x = 10;
  ctl.base.y = 10;
  ctl.base.w = 100;
  ctl.base.h = 20;
  ctl.base.fg_color = RETROFLAT_COLOR_WHITE;
  ctl.BUTTON.label = "Example\nLabel";
  ctl.BUTTON.label_sz = maug_strlen( ctl.BUTTON.label );

  retval = retrogui_push_ctl( gui_p, &ctl );
  maug_cleanup_if_not_ok();

  / * Insert the button control. * /

  retrogui_init_ctl(
     &ctl, RETROGUI_CTL_TYPE_BUTTON, EXAMPLE_IDC_BUTTON );

  ctl.base.x = 10;
  ctl.base.y = 40;
  ctl.base.w = 60;
  ctl.base.h = 20;
  ctl.BUTTON.label = "Test";
  ctl.BUTTON.label_sz = maug_strlen( ctl.BUTTON.label );

  retval = retrogui_push_ctl( gui_p, &ctl );
  maug_cleanup_if_not_ok();

  / * Insert the fillbar control. * /

  retrogui_init_ctl(
     &ctl, RETROGUI_CTL_TYPE_FILLBAR, EXAMPLE_IDC_FILLBAR );

  ctl.base.x = 10;
  ctl.base.y = 70;
  ctl.base.w = 100;
  ctl.base.h = 10;
  ctl.base.bg_color = RETROFLAT_COLOR_BLACK;
  ctl.base.fg_color = RETROFLAT_COLOR_RED;

  retval = retrogui_push_ctl( gui_p, &ctl );
  maug_cleanup_if_not_ok();

  / * Set the level of the inserted fillbar to 50%. * /
  retval = retrogui_set_ctl_level(
     gui_p, EXAMPLE_IDC_FILLBAR, 50, 100, 0 );

Macro Definition Documentation

◆ _retrogui_copy_str

#define _retrogui_copy_str	(	field,
		src_str,
		dest_ctl,
		str_tmp,
		str_sz )

Value:

   /* Sanity checking. */ \
   assert( NULL != src_str ); \
   debug_printf( RETROGUI_TRACE_LVL, \
      "copying string \"%s\" to " #dest_ctl, src_str ); \
   if( 0 == str_sz ) { \
      str_sz = maug_strlen( src_str ); \
      debug_printf( RETROGUI_TRACE_LVL, \
         "determined str sz of \"%s\": " SIZE_T_FMT, src_str, str_sz ); \
   } \
   if( (MAUG_MHANDLE)NULL != dest_ctl. field ## _h ) { \
      /* Free the existing string. */ \
      maug_mfree( dest_ctl. field ## _h ); \
   } \
   \
   /* Allocate new string space. */ \
   dest_ctl. field ## _h = maug_malloc( str_sz + 1, 1 ); \
   debug_printf( RETROGUI_TRACE_LVL, \
      "allocated str sz for \"%s\": " SIZE_T_FMT, src_str, str_sz + 1 ); \
   maug_cleanup_if_null_alloc( MAUG_MHANDLE, dest_ctl. field ## _h ); \
   maug_mlock( dest_ctl. field ## _h, str_tmp ); \
   maug_cleanup_if_null_lock( char*, str_tmp ); \
   \
   /* Copy the string over. */ \
   assert( NULL != str_tmp ); \
   maug_mzero( str_tmp, str_sz + 1 ); \
   debug_printf( RETROGUI_TRACE_LVL, \
      "zeroed str sz for \"%s\": " SIZE_T_FMT, src_str, str_sz + 1 ); \
   maug_strncpy( str_tmp, src_str, str_sz ); \
   debug_printf( RETROGUI_TRACE_LVL, "copied str as: \"%s\"", str_tmp ); \
   maug_munlock( dest_ctl. field ## _h, str_tmp );

◆ RETROGUI_CTL_TABLE_CONSTS

#define RETROGUI_CTL_TABLE_CONSTS	(	idx,
		c_name,
		c_fields )

Value:

extern MAUG_CONST uint8_t SEG_MCONST RETROGUI_CTL_TYPE_ ## c_name;

◆ retrogui_focus_next

#define retrogui_focus_next ( gui )

Value:

retrogui_focus_iter( gui, 0, 1 )

◆ retrogui_focus_prev

#define retrogui_focus_prev ( gui )

Value:

retrogui_focus_iter( gui, mdata_vector_ct( &((gui)->ctls) ) - 1, -1 )

Function Documentation

◆ retrogui_destroy()

MERROR_RETVAL retrogui_destroy ( struct RETROGUI * gui )

Free memory held by a RETROGUI controller internally and clean up any subordinate controls.

Warning: This function does not free memory used for the RETROGUI struct directly! A RETROGUI may exist on the stack or be managed by a RETROWIN, after all!

Returns: One of the Return Values indicating operation result.

◆ retrogui_focus_iter()

retrogui_idc_t retrogui_focus_iter	(	struct RETROGUI *	gui,
		size_t	start,
		ssize_t	incr )

Increment RETROGUI::focus, skipping elements that cannot hold focus.

Warning: This function is designed to be used via the retrogui_focus_next() and retrogui_focus_prev() convenience functions!

Parameters

start	Value to start from, either 0 for the first element or ctl_count - 1 for the last.
incr	1 or -1, depending on whether to increment forwards or backwards.

Returns: The new value of RETROGUI::focus, or a negative value to be converted to an error code with merror_sz_to_retval() on failure.

◆ retrogui_init()

MERROR_RETVAL retrogui_init ( struct RETROGUI * gui )

Prepare a RETROGUI controller for use.

Note: It is possible to have multiple GUI controllers in a program. For example, a web browser might have a controller for its address bar and a controller for form elements on pages.

Warning: This must be run before any other methods are used on the given GUI!

Parameters

gui	Pointer to a RETROGUI struct to initialize.

Returns: One of the Return Values indicating operation result.

◆ retrogui_poll_ctls()

retrogui_idc_t retrogui_poll_ctls	(	struct RETROGUI *	gui,
		RETROFLAT_IN_KEY *	p_input,
		struct RETROFLAT_INPUT *	input_evt )

Poll for the last clicked control and maintain listboxes and menus.

Parameters

input	Input integer returned from retroflat_poll_input().
input_evt	RETROFLAT_INPUT initialized by retroflat_poll_input().

Returns: IDC of clicked control or RETROGUI_IDC_NONE if none clicked since last poll.

◆ retrogui_remove_ctl()

MERROR_RETVAL retrogui_remove_ctl	(	struct RETROGUI *	gui,
		retrogui_idc_t	idc )

Remove a control with the given unique identifier index from the given RETROGUI controller.

Parameters

gui	Pointer to a RETROGUI struct to remove a control from.
idc	Unique identifier index of the control to remove.

Returns: One of the Return Values indicating operation result.

◆ retrogui_set_ctl_image()

MERROR_RETVAL retrogui_set_ctl_image	(	struct RETROGUI *	gui,
		retrogui_idc_t	idc,
		const char *	path,
		uint8_t	flags )

Set the image displayed by an IMAGE-type RETROGUI_CTL.

Parameters

idc	Unique identifier index of the control to adjust.
path	Filesystem path to pass to retroflat_load_bitmap().
flags	Flags from the RetroFlat Drawing API to pass to retroflat_load_bitmap().

Returns: One of the Return Values indicating operation result.

◆ retrogui_set_ctl_level()

MERROR_RETVAL retrogui_set_ctl_level	(	struct RETROGUI *	gui,
		retrogui_idc_t	idc,
		uint16_t	level,
		uint16_t	max,
		uint8_t	flags )

Set the current progress level displayed by a FILLBAR-type RETROGUI_CTL.

Parameters

idc	Unique identifier index of the control to adjust.
level	Numeric value out of the max param (e.g. 50 for half if max is 100).
max	The maximum possible value.

Returns: One of the Return Values indicating operation result.

◆ retrogui_set_font()

MERROR_RETVAL retrogui_set_font	(	struct RETROGUI *	gui,
		const char *	font_path )

Load the RetroFont API for the given RETROGUI to draw its controls with. Use RetroGXCache API if available.

Fonts loaded with this function will be automatically freed by calling retrogui_destroy() on this RETROGUI.

Topics

Files

Data Structures

Macros

Typedefs

Functions

Detailed Description

RetroGUI Example

Macro Definition Documentation

◆ _retrogui_copy_str

◆ RETROGUI_CTL_TABLE_CONSTS

◆ retrogui_focus_next

◆ retrogui_focus_prev

Function Documentation

◆ retrogui_destroy()

◆ retrogui_focus_iter()

◆ retrogui_init()

◆ retrogui_poll_ctls()

◆ retrogui_remove_ctl()

◆ retrogui_set_ctl_image()

◆ retrogui_set_ctl_level()

◆ retrogui_set_font()