/*
* This file is subject to the terms of the GFX License. If a copy of
* the license was not distributed with this file, you can obtain one at:
*
* http://ugfx.org/license.html
*/
/*
* @file src/gwin/gwin_class.h
* @brief GWIN Graphic window subsystem header file.
*
* @defgroup Internal Internal
* @ingroup GWIN
*
* @note These definitions are normally not used by an application program. They are useful
* only if you want to create your own custom GWIN window or widget.
* @note To access these definitions you must include "src/gwin/gwin_class.h" in your source file.
*
* @{
*/
#ifndef _CLASS_GWIN_H
#define _CLASS_GWIN_H
#if GFX_USE_GWIN || defined(__DOXYGEN__)
/**
* @brief The predefined flags for a Window
* @{
*/
#define GWIN_FIRST_CONTROL_FLAG 0x00000001 /**< 8 bits free for the control to use. Don't change this value as it is relied upon definitions in widget header files. */
#define GWIN_LAST_CONTROL_FLAG 0x00000080 /**< 8 bits free for the control to use */
#define GWIN_FLG_VISIBLE 0x00000100 /**< The window is "visible" */
#define GWIN_FLG_SYSVISIBLE 0x00000200 /**< The window is visible after parents are tested */
#define GWIN_FLG_ENABLED 0x00000400 /**< The window is "enabled" */
#define GWIN_FLG_SYSENABLED 0x00000800 /**< The window is enabled after parents are tested */
#define GWIN_FLG_DYNAMIC 0x00001000 /**< The GWIN structure is allocated */
#define GWIN_FLG_ALLOCTXT 0x00002000 /**< The text/label is allocated */
#define GWIN_FLG_NEEDREDRAW 0x00004000 /**< Redraw is needed but has been delayed */
#define GWIN_FLG_BGREDRAW 0x00008000 /**< On redraw, if not visible redraw the revealed under-side */
#define GWIN_FLG_SUPERMASK 0x000F0000 /**< The bit mask to leave just the window superclass type */
#define GWIN_FLG_WIDGET 0x00010000 /**< This is a widget */
#define GWIN_FLG_CONTAINER 0x00020000 /**< This is a container */
#define GWIN_FLG_MINIMIZED 0x00100000 /**< The window is minimized */
#define GWIN_FLG_MAXIMIZED 0x00200000 /**< The window is maximized */
#define GWIN_FLG_MOUSECAPTURE 0x00400000 /**< The window has captured the mouse */
#define GWIN_FLG_FLASHING 0x00800000 /**< The window is flashing - see the _gwinFlashState boolean */
#define GWIN_FIRST_WM_FLAG 0x01000000 /**< 8 bits free for the window manager to use */
#define GWIN_LAST_WM_FLAG 0x80000000 /**< 8 bits free for the window manager to use */
/** @} */
/**
* @brief The Virtual Method Table for a GWIN window
* @{
*/
typedef struct gwinVMT {
const char * classname; /**< The GWIN classname (mandatory) */
size_t size; /**< The size of the class object */
void (*Destroy) (GWindowObject *gh); /**< The GWIN destroy function (optional) */
void (*Redraw) (GWindowObject *gh); /**< The GWIN redraw routine (optional) */
void (*AfterClear) (GWindowObject *gh); /**< The GWIN after-clear function (optional) */
} gwinVMT;
/** @} */
#if GWIN_NEED_WIDGET || defined(__DOXYGEN__)
/**
* @brief An toggle/dial instance is not being used
*/
#define GWIDGET_NO_INSTANCE ((uint16_t)-1)
/**
* @brief The source handle that widgets use when sending events
*/
#define GWIDGET_SOURCE ((GSourceHandle)(void *)_gwidgetCreate)
/**
* @brief The Virtual Method Table for a widget
* @note A widget must have a destroy function. Either use @p _gwidgetDestroy() or use your own function
* which internally calls @p _gwidgetDestroy().
* @note A widget must have a redraw function. Use @p _gwidgetRedraw().
* @note If toggleroles != 0, ToggleAssign(), ToggleGet() and one or both of ToggleOff() and ToggleOn() must be specified.
* @note If dialroles != 0, DialAssign(), DialGet() and DialMove() must be specified.
* @{
*/
typedef struct gwidgetVMT {
struct gwinVMT g; /**< This is still a GWIN */
void (*DefaultDraw) (GWidgetObject *gw, void *param); /**< The default drawing routine (mandatory) */
#if GINPUT_NEED_MOUSE
struct {
void (*MouseDown) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse down events (optional) */
void (*MouseUp) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse up events (optional) */
void (*MouseMove) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse move events (optional) */
};
#endif
#if GINPUT_NEED_KEYBOARD || GWIN_NEED_KEYBOARD
struct {
void (*KeyboardEvent) (GWidgetObject *gw, GEventKeyboard *pke); /**< Process keyboard events (optional) */
};
#endif
#if GINPUT_NEED_TOGGLE
struct {
uint16_t toggleroles; /**< The roles supported for toggles (0->toggleroles-1) */
void (*ToggleAssign) (GWidgetObject *gw, uint16_t role, uint16_t instance); /**< Assign a toggle to a role (optional) */
uint16_t (*ToggleGet) (GWidgetObject *gw, uint16_t role); /**< Return the instance for a particular role (optional) */
void (*ToggleOff) (GWidgetObject *gw, uint16_t role); /**< Process toggle off events (optional) */
void (*ToggleOn) (GWidgetObject *gw, uint16_t role); /**< Process toggle on events (optional) */
};
#endif
#if GINPUT_NEED_DIAL
struct {
uint16_t dialroles; /**< The roles supported for dials (0->dialroles-1) */
void (*DialAssign) (GWidgetObject *gw, uint16_t role, uint16_t instance); /**< Test the role and save the dial instance handle (optional) */
uint16_t (*DialGet) (GWidgetObject *gw, uint16_t role); /**< Return the instance for a particular role (optional) */
void (*DialMove) (GWidgetObject *gw, uint16_t role, uint16_t value, uint16_t max); /**< Process dial move events (optional) */
};
#endif
} gwidgetVMT;
/** @} */
#endif
#if GWIN_NEED_CONTAINERS || defined(__DOXYGEN__)
/**
* @brief The Virtual Method Table for a container
* @note A container must have a destroy function. Either use @p _gcontainerDestroy() or use your own function
* which internally calls @p _gcontainerDestroy().
* @note A container must have a gwin redraw function. Use @p _containerRedraw().
* @note If toggleroles != 0, ToggleAssign(), ToggleGet() and one or both of ToggleOff() and ToggleOn() must be specified.
* @note If dialroles != 0, DialAssign(), DialGet() and DialMove() must be specified.
* @{
*/
typedef struct gcontainerVMT {
gwidgetVMT gw;
coord_t (*LeftBorder) (GHandle gh); /**< The size of the left border (mandatory) */
coord_t (*TopBorder) (GHandle gh); /**< The size of the top border (mandatory) */
coord_t (*RightBorder) (GHandle gh); /**< The size of the right border (mandatory) */
coord_t (*BottomBorder) (GHandle gh); /**< The size of the bottom border (mandatory) */
void (*NotifyAdd) (GHandle gh, GHandle ghChild); /**< Notification that a child has been added (optional) */
void (*NotifyDelete) (GHandle gh, GHandle ghChild); /**< Notification that a child has been deleted (optional) */
} gcontainerVMT;
/** @} */
#endif
#if GWIN_NEED_WINDOWMANAGER || defined(__DOXYGEN__)
// @note There is only ever one instance of each GWindowManager type
typedef struct GWindowManager {
const struct gwmVMT *vmt;
} GWindowManager;
/**
* @brief The Virtual Method Table for a window manager
* @{
*/
typedef struct gwmVMT {
void (*Init) (void); /**< The window manager has just been set as the current window manager */
void (*DeInit) (void); /**< The window manager has just been removed as the current window manager */
bool_t (*Add) (GHandle gh, const GWindowInit *pInit); /**< A window has been added */
void (*Delete) (GHandle gh); /**< A window has been deleted */
void (*Redraw) (GHandle gh); /**< A window needs to be redraw (or undrawn) */
void (*Size) (GHandle gh, coord_t w, coord_t h); /**< A window wants to be resized */
void (*Move) (GHandle gh, coord_t x, coord_t y); /**< A window wants to be moved */
void (*Raise) (GHandle gh); /**< A window wants to be on top */
void (*MinMax) (GHandle gh, GWindowMinMax minmax); /**< A window wants to be minimized/maximised */
} gwmVMT;
/** @} */
/**
* @brief The current window manager
*/
extern GWindowManager *_GWINwm;
extern bool_t _gwinFlashState;
#endif
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Initialise (and allocate if necessary) the base GWIN object
*
* @param[in] g The GDisplay to use for this window
* @param[in] pgw The GWindowObject structure. If NULL one is allocated from the heap
* @param[in] pInit The user initialization parameters
* @param[in] vmt The virtual method table for the GWIN object
* @param[in] flags The default flags to use
*
* @return The GHandle of the created window
*
* @notapi
*/
GHandle _gwindowCreate(GDisplay *g, GWindowObject *pgw, const GWindowInit *pInit, const gwinVMT *vmt, uint32_t flags);
/**
* @brief Redraw the window after a status change.
*
* @param[in] gh The widget to redraw
*
* @note Mark a window for redraw.
* @note The window will get redrawn at some later time.
* @note This call is designed to be fast and non-blocking
*
* @notapi
*/
void _gwinUpdate(GHandle gh);
/**
* @brief How to flush the redraws
* @notes REDRAW_WAIT - Wait for a drawing session to be available
* @notes REDRAW_NOWAIT - Do nothing if the drawing session is not available
* @note REDRAW_INSESSION - We are already in a drawing session
*/
typedef enum GRedrawMethod { REDRAW_WAIT, REDRAW_NOWAIT, REDRAW_INSESSION } GRedrawMethod;
/**
* @brief Flush any pending redraws in the system.
*
* @param[in] how Do we wait for the lock?
*
* @note This call will attempt to flush any pending redraws
* in the system. The doWait parameter tells this call
* how to handle someone already holding the drawing lock.
* If doWait is TRUE it waits to obtain the lock. If FALSE
* and the drawing lock is free then the redraw is done
* immediately. If the drawing lock was taken it will postpone the flush
* on the basis that someone else will do it for us later.
*
* @notapi
*/
void _gwinFlushRedraws(GRedrawMethod how);
/**
* @brief Obtain a drawing session
* @return TRUE if the drawing session was obtained, FALSE if the window is not visible
*
* @param[in] gh The window
*
* @note This function blocks until a drawing session is available if the window is visible
*/
bool_t _gwinDrawStart(GHandle gh);
/**
* @brief Release a drawing session
*
* @param[in] gh The window
*/
void _gwinDrawEnd(GHandle gh);
/**
* @brief Destroy a window.
*
* @param[in] gh The window
* @param[in] how Do we wait for the lock?
*
* @note If called without the drawing lock 'how' must be REDRAW_WAIT.
* If called with the drawing lock 'how' must be REDRAW_INSESSION.
*
* @notapi
*/
void _gwinDestroy(GHandle gh, GRedrawMethod how);
/**
* @brief Add a window to the window manager and set its position and size
* @return TRUE if successful
*
* @param[in] gh The window
* @param[in] pInit The window init structure
*/
bool_t _gwinWMAdd(GHandle gh, const GWindowInit *pInit);
#if GWIN_NEED_WIDGET || defined(__DOXYGEN__)
/**
* @brief Initialise (and allocate if necessary) the base Widget object
*
* @param[in] g The GDisplay to display this window on
* @param[in] pgw The GWidgetObject structure. If NULL one is allocated from the heap
* @param[in] pInit The user initialization parameters
* @param[in] vmt The virtual method table for the Widget object
*
* @return The GHandle of the created widget
*
* @notapi
*/
GHandle _gwidgetCreate(GDisplay *g, GWidgetObject *pgw, const GWidgetInit *pInit, const gwidgetVMT *vmt);
/**
* @brief Destroy the Widget object
*
* @param[in] gh The widget to destroy
*
* @notapi
*/
void _gwidgetDestroy(GHandle gh);
/**
* @brief Redraw the Widget object (VMT method only)
*
* @param[in] gh The widget to redraw
*
* @note Do not use this routine to update a widget after a status change.
* Use @p _gwinUpdate() instead. This routine should only be used in the
* VMT.
*
* @notapi
*/
void _gwidgetRedraw(GHandle gh);
/**
* @brief Send a standard GWIN event.
*
* @param[in] gh The window
* @param[in] type The event type
*
* @note No consideration is given to recording EVENT LOST statuses.
*
* @notapi
*/
void _gwinSendEvent(GHandle gh, GEventType type);
#if (GFX_USE_GINPUT && GINPUT_NEED_KEYBOARD) || GWIN_NEED_KEYBOARD || defined(__DOXYGEN__)
/**
* @brief Move the focus off the current focus window.
*
* @note The focus can stay on the same window if there is no other focusable window
*
* @notapi
*/
void _gwinMoveFocus(void);
/**
* @brief Do focus fixup's after a change of state for a window.
* @details If a focus window has become invisible or disabled then
* the focus must be taken away from it. If there is no focus
* window and this window is eligible then this window becomes
* the focus.
*
* @param[in] gh The window
*
* @note This routine does not actually do a redraw. It assumes that surrounding code
* will because of the change of state that lead to this being called.
*
* @notapi
*/
void _gwinFixFocus(GHandle gh);
/**
* @brief Draw a simple focus rectangle in the default style.
*
* @param[in] gw The widget
* @param[in] x, y The start x, y position (relative to the window)
* @param[in] cx, cy The width & height of the rectangle
*
* @note Assumes the widget is in a state where it can draw.
* @note Nothing is drawn if the window doesn't have focus.
* @note The focus rectangle may be more than one pixel thick and may
* not be a continuous line.
*
* @notapi
*/
void _gwidgetDrawFocusRect(GWidgetObject *gw, coord_t x, coord_t y, coord_t cx, coord_t cy);
#else
#define _gwinFixFocus(gh)
#define _gwidgetDrawFocusRect(gh,x,y,cx,cy)
#endif
#if GWIN_NEED_FLASHING || defined(__DOXYGEN__)
/**
* @brief Convert a chosen style color set pressed/enabled etc if flashing
* @return The colorset - after flashing is taken into account
*
* @param[in] gw The widget
* @param[in] pcol The style color set that has been chosen to reflect the state of the widget
* @param[in] flashOffState Whether the off-state should be flashed as well. If false, only the
* pressed color set is flashed.
*/
const GColorSet *_gwinGetFlashedColor(GWidgetObject *gw, const GColorSet *pcol, bool_t flashOffState);
#endif
#else
#define _gwinFixFocus(gh)
#endif
#if GWIN_NEED_CONTAINERS || defined(__DOXYGEN__)
/**
* @brief Initialise (and allocate if necessary) the base Container object
*
* @param[in] g The GDisplay to display this window on
* @param[in] pgw The GContainerObject structure. If NULL one is allocated from the heap
* @param[in] pInit The user initialization parameters
* @param[in] vmt The virtual method table for the Container object
*
* @return The GHandle of the created widget
*
* @notapi
*/
GHandle _gcontainerCreate(GDisplay *g, GContainerObject *pgw, const GWidgetInit *pInit, const gcontainerVMT *vmt);
/**
* @brief Destroy the Container object
*
* @param[in] gh The container to destroy
*
* @notapi
*/
void _gcontainerDestroy(GHandle gh);
/**
* @brief Redraw the Container object (VMT method only)
*
* @param[in] gh The container to redraw
*
* @note Do not use this routine to update a container after a status change.
* Use @p _gwinUpdate() instead. This routine should only be used in the
* VMT.
*
* @notapi
*/
#define _gcontainerRedraw _gwidgetRedraw
/**
* @brief The visibility of something has changed. Ripple the changes.
*
* @note Does not actually trigger the redraw. It just marks as ready for redraw any
* visibility changes.
*
* @notapi
*/
void _gwinRippleVisibility(void);
#endif
#ifdef __cplusplus
}
#endif
#endif /* GFX_USE_GWIN */
#endif /* _CLASS_GWIN_H */
/** @} */