RetroFlat Window API

Builds on RetroGUI API to allow for multiple windows. More...

Collaboration diagram for RetroFlat Window API:

Files
file	retrowin.h

Data Structures
struct	RETROWIN

Macros
#define	RETROWIN_TRACE_LVL   0
#define	RETROWIN_FLAG_INIT_BMP   0x20
#define	RETROWIN_FLAG_GUI_LOCKED   0x04
#define	RETROWIN_FLAG_BORDER_NONE   0x00
#define	RETROWIN_FLAG_BORDER_GRAY   0x01
#define	RETROWIN_FLAG_BORDER_BLUE   0x02
#define	retrowin_win_is_active(win)    (RETROWIN_FLAG_INIT_BMP == (RETROWIN_FLAG_INIT_BMP & (win)->flags))
#define	RETROWIN_FLAG_BORDER_MASK   0x03
#define	retrowin_lock_gui(win)
#define	retrowin_unlock_gui(win)
#define	retrowin_gui_is_locked(win)

Functions
MERROR_RETVAL	retrowin_redraw_win_stack (struct MDATA_VECTOR *win_stack)
MERROR_RETVAL	retrowin_refresh_win_stack (struct MDATA_VECTOR *win_stack)
	Force all windows on the stack to redraw.
retrogui_idc_t	retrowin_poll_win_stack (struct MDATA_VECTOR *win_stack, retrogui_idc_t idc_active, RETROFLAT_IN_KEY *p_input, struct RETROFLAT_INPUT *input_evt)
	Given the outputs of the input poller, check the controls on the active window to see if the inputs trigger any of them. More...
ssize_t	retrowin_get_win_stack_sel_idx (struct MDATA_VECTOR *win_stack, retrogui_idc_t idc_win, retrogui_idc_t idc_ctl)
	Get the selected index of the given control in the given window from the window stack.
void	retrowin_free_win (struct RETROWIN *win)
MERROR_RETVAL	retrowin_free_all_win (struct MDATA_VECTOR *win_stack)
ssize_t	retrowin_get_by_idc (retrogui_idc_t idc, struct MDATA_VECTOR *win_stack)
ssize_t	retrowin_push_win (struct RETROGUI *gui, struct MDATA_VECTOR *win_stack, retrogui_idc_t idc, const maug_path font_filename, retroflat_pxxy_t x, retroflat_pxxy_t y, retroflat_pxxy_t w, retroflat_pxxy_t h, uint8_t flags)
	Create a new window on the given win_stack. More...
MERROR_RETVAL	retrowin_destroy_win (struct MDATA_VECTOR *win_stack, retrogui_idc_t idc)
	Destroy the given window's resources and remove it from the window stack. More...

Detailed Description

Builds on RetroGUI API to allow for multiple windows.

RetroWin Example

  struct RETROWIN* win = NULL;
  struct MDATA_VECTOR win_stack;

  retrowin_push_win(
     NULL, / * This window should create and manage its own GUI. * /
     &win_stack,
     IDC_EXAMPLE_WIN, "unscii_8.hex",
     / * Center * /
     (retroflat_screen_w() >> 1) - (EXAMPLE_WIN_W >> 1),
     / * Center * /
     (retroflat_screen_h() >> 1) - (EXAMPLE_WIN_H >> 1),
     EXAMPLE_WIN_W, EXAMPLE_WIN_H, RETROWIN_FLAG_BORDER_BLUE );

  mdata_vector_lock( &win_stack );
  win = mdata_vector_get_last( &win_stack, struct RETROWIN );
  maug_cleanup_if_null_lock( struct RETROWIN*, win );

  / * Lock macros will automatically fail to cleanup: label if something
    * goes wrong, so no error handling here!
    * /
  retrowin_lock_gui( win );

  / *** Pause Example to Insert Controls *** /

For inserting controls into a RETROGUI, please see RetroGUI Example. Use win->gui_p as the GUI to lock and push controls onto, instead of the gui_p variable in that example.

  / *** Resume Example *** /

  / * Unlock window and window stack after controls have been added. * /
  retrowin_unlock_gui( win );
  mdata_vector_unlock( &win_stack );

Macro Definition Documentation

retrowin_gui_is_locked

#define retrowin_gui_is_locked

(

win

)

Value:

   (RETROWIN_FLAG_INIT_GUI == (RETROWIN_FLAG_INIT_GUI & (win)->flags) && \
   RETROWIN_FLAG_GUI_LOCKED == (RETROWIN_FLAG_GUI_LOCKED & (win)->flags))

retrowin_lock_gui

#define retrowin_lock_gui

(

win

)

Value:

   if( \
      RETROWIN_FLAG_INIT_GUI == (RETROWIN_FLAG_INIT_GUI & (win)->flags) && \
      RETROWIN_FLAG_GUI_LOCKED != (RETROWIN_FLAG_GUI_LOCKED & (win)->flags) \
   ) { \
      /* debug_printf( RETROWIN_TRACE_LVL, "locking managed gui handle %p...", \
         (win)->gui_h ); */ \
      maug_mlock( (win)->gui_h, (win)->gui_p ); \
      maug_cleanup_if_null_lock( struct RETROGUI*, (win)->gui_p ); \
      (win)->flags |= RETROWIN_FLAG_GUI_LOCKED; \
      /* debug_printf( RETROWIN_TRACE_LVL, "locked managed gui to pointer %p!", \
         (win)->gui_p ); */ \
   }

retrowin_unlock_gui

#define retrowin_unlock_gui

(

win

)

Value:

   if( \
      RETROWIN_FLAG_INIT_GUI == (RETROWIN_FLAG_INIT_GUI & (win)->flags) && \
      RETROWIN_FLAG_GUI_LOCKED == (RETROWIN_FLAG_GUI_LOCKED & (win)->flags) \
   ) { \
      /* debug_printf( RETROWIN_TRACE_LVL, "unlocking managed gui pointer %p...", \
         (win)->gui_h ); */ \
      maug_munlock( (win)->gui_h, (win)->gui_p ); \
      (win)->flags &= ~RETROWIN_FLAG_GUI_LOCKED; \
   }

Function Documentation

retrowin_destroy_win()

MERROR_RETVAL retrowin_destroy_win	(	struct MDATA_VECTOR *	win_stack,
		retrogui_idc_t	idc
	)

Destroy the given window's resources and remove it from the window stack.

Parameters

idc	Identifier (NOT index) of the window to destroy.

retrowin_poll_win_stack()

retrogui_idc_t retrowin_poll_win_stack	(	struct MDATA_VECTOR *	win_stack,
		retrogui_idc_t	idc_active,
		RETROFLAT_IN_KEY *	p_input,
		struct RETROFLAT_INPUT *	input_evt
	)

Given the outputs of the input poller, check the controls on the active window to see if the inputs trigger any of them.

Parameters

idc_active	IDC of window to consider "active" as managed by your program.
p_input	Input key to process during polling (see note!)
input_evt	Input event to process during polling (see note!)

Returns

IDC of triggered control or ::RETROGUI_IDC_NONE if none triggered.

Note

p_input and input_evt MUST be polled by retroflat_poll_input() before passing to this function to determine what key has been pressed! The poll function will then clear them if it handles them so spillover can be handled by further processing in your program.

retrowin_push_win()

ssize_t retrowin_push_win	(	struct RETROGUI *	gui,
		struct MDATA_VECTOR *	win_stack,
		retrogui_idc_t	idc,
		const maug_path	font_filename,
		retroflat_pxxy_t	x,
		retroflat_pxxy_t	y,
		retroflat_pxxy_t	w,
		retroflat_pxxy_t	h,
		uint8_t	flags
	)

Create a new window on the given win_stack.

Parameters

gui	Pointer to a RETROGUI already initialized with retrogui_init(), or NULL if the window should create and manage its own RETROGUI.
win_stack	The vector on which windows are stored.
font_filename	Font to load into the GUI. Only used if this window will manage its own GUI.