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)

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)
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)
ssize_t	retrowin_get_by_idc (size_t idc, struct MDATA_VECTOR *win_stack)
ssize_t	retrowin_push_win (struct RETROGUI *gui, struct MDATA_VECTOR *win_stack, size_t idc, const char *font_filename, size_t x, size_t y, size_t w, size_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, size_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_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,
		size_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_push_win()

ssize_t retrowin_push_win	(	struct RETROGUI *	gui,
		struct MDATA_VECTOR *	win_stack,
		size_t	idc,
		const char *	font_filename,
		size_t	x,
		size_t	y,
		size_t	w,
		size_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.