version 2.8
gwin_class.h
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /*
9  * @file src/gwin/gwin_class.h
10  * @brief GWIN Graphic window subsystem header file.
11  *
12  * @defgroup Internal Internal
13  * @ingroup GWIN
14  *
15  * @note These definitions are normally not used by an application program. They are useful
16  * only if you want to create your own custom GWIN window or widget.
17  * @note To access these definitions you must include "src/gwin/gwin_class.h" in your source file.
18  *
19  * @{
20  */
21 #ifndef _CLASS_GWIN_H
22 #define _CLASS_GWIN_H
23 
24 #if GFX_USE_GWIN || defined(__DOXYGEN__)
25 
26 /**
27  * @brief The predefined flags for a Window
28  * @{
29  */
30 #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. */
31 #define GWIN_LAST_CONTROL_FLAG 0x00000080 /**< 8 bits free for the control to use */
32 #define GWIN_FLG_VISIBLE 0x00000100 /**< The window is "visible" */
33 #define GWIN_FLG_SYSVISIBLE 0x00000200 /**< The window is visible after parents are tested */
34 #define GWIN_FLG_ENABLED 0x00000400 /**< The window is "enabled" */
35 #define GWIN_FLG_SYSENABLED 0x00000800 /**< The window is enabled after parents are tested */
36 #define GWIN_FLG_DYNAMIC 0x00001000 /**< The GWIN structure is allocated */
37 #define GWIN_FLG_ALLOCTXT 0x00002000 /**< The text/label is allocated */
38 #define GWIN_FLG_NEEDREDRAW 0x00004000 /**< Redraw is needed but has been delayed */
39 #define GWIN_FLG_BGREDRAW 0x00008000 /**< On redraw, if not visible redraw the revealed under-side */
40 #define GWIN_FLG_SUPERMASK 0x000F0000 /**< The bit mask to leave just the window superclass type */
41 #define GWIN_FLG_WIDGET 0x00010000 /**< This is a widget */
42 #define GWIN_FLG_CONTAINER 0x00020000 /**< This is a container */
43 #define GWIN_FLG_MINIMIZED 0x00100000 /**< The window is minimized */
44 #define GWIN_FLG_MAXIMIZED 0x00200000 /**< The window is maximized */
45 #define GWIN_FLG_MOUSECAPTURE 0x00400000 /**< The window has captured the mouse */
46 #define GWIN_FLG_FLASHING 0x00800000 /**< The window is flashing - see the _gwinFlashState boolean */
47 #define GWIN_FIRST_WM_FLAG 0x01000000 /**< 8 bits free for the window manager to use */
48 #define GWIN_LAST_WM_FLAG 0x80000000 /**< 8 bits free for the window manager to use */
49 /** @} */
50 
51 /**
52  * @brief The Virtual Method Table for a GWIN window
53  * @{
54  */
55 typedef struct gwinVMT {
56  const char * classname; /**< The GWIN classname (mandatory) */
57  size_t size; /**< The size of the class object */
58  void (*Destroy) (GWindowObject *gh); /**< The GWIN destroy function (optional) */
59  void (*Redraw) (GWindowObject *gh); /**< The GWIN redraw routine (optional) */
60  void (*AfterClear) (GWindowObject *gh); /**< The GWIN after-clear function (optional) */
61 } gwinVMT;
62 /** @} */
63 
64 #if GWIN_NEED_WIDGET || defined(__DOXYGEN__)
65 
66  /**
67  * @brief An toggle/dial instance is not being used
68  */
69  #define GWIDGET_NO_INSTANCE ((uint16_t)-1)
70 
71  /**
72  * @brief The source handle that widgets use when sending events
73  */
74  #define GWIDGET_SOURCE ((GSourceHandle)(void *)_gwidgetCreate)
75 
76  /**
77  * @brief The Virtual Method Table for a widget
78  * @note A widget must have a destroy function. Either use @p _gwidgetDestroy() or use your own function
79  * which internally calls @p _gwidgetDestroy().
80  * @note A widget must have a redraw function. Use @p _gwidgetRedraw().
81  * @note If toggleroles != 0, ToggleAssign(), ToggleGet() and one or both of ToggleOff() and ToggleOn() must be specified.
82  * @note If dialroles != 0, DialAssign(), DialGet() and DialMove() must be specified.
83  * @{
84  */
85  typedef struct gwidgetVMT {
86  struct gwinVMT g; /**< This is still a GWIN */
87  void (*DefaultDraw) (GWidgetObject *gw, void *param); /**< The default drawing routine (mandatory) */
88  #if GINPUT_NEED_MOUSE
89  struct {
90  void (*MouseDown) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse down events (optional) */
91  void (*MouseUp) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse up events (optional) */
92  void (*MouseMove) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse move events (optional) */
93  };
94  #endif
95  #if GINPUT_NEED_KEYBOARD || GWIN_NEED_KEYBOARD
96  struct {
97  void (*KeyboardEvent) (GWidgetObject *gw, GEventKeyboard *pke); /**< Process keyboard events (optional) */
98  };
99  #endif
100  #if GINPUT_NEED_TOGGLE
101  struct {
102  uint16_t toggleroles; /**< The roles supported for toggles (0->toggleroles-1) */
103  void (*ToggleAssign) (GWidgetObject *gw, uint16_t role, uint16_t instance); /**< Assign a toggle to a role (optional) */
104  uint16_t (*ToggleGet) (GWidgetObject *gw, uint16_t role); /**< Return the instance for a particular role (optional) */
105  void (*ToggleOff) (GWidgetObject *gw, uint16_t role); /**< Process toggle off events (optional) */
106  void (*ToggleOn) (GWidgetObject *gw, uint16_t role); /**< Process toggle on events (optional) */
107  };
108  #endif
109  #if GINPUT_NEED_DIAL
110  struct {
111  uint16_t dialroles; /**< The roles supported for dials (0->dialroles-1) */
112  void (*DialAssign) (GWidgetObject *gw, uint16_t role, uint16_t instance); /**< Test the role and save the dial instance handle (optional) */
113  uint16_t (*DialGet) (GWidgetObject *gw, uint16_t role); /**< Return the instance for a particular role (optional) */
114  void (*DialMove) (GWidgetObject *gw, uint16_t role, uint16_t value, uint16_t max); /**< Process dial move events (optional) */
115  };
116  #endif
117  } gwidgetVMT;
118  /** @} */
119 #endif
120 
121 #if GWIN_NEED_CONTAINERS || defined(__DOXYGEN__)
122 
123  /**
124  * @brief The Virtual Method Table for a container
125  * @note A container must have a destroy function. Either use @p _gcontainerDestroy() or use your own function
126  * which internally calls @p _gcontainerDestroy().
127  * @note A container must have a gwin redraw function. Use @p _containerRedraw().
128  * @note If toggleroles != 0, ToggleAssign(), ToggleGet() and one or both of ToggleOff() and ToggleOn() must be specified.
129  * @note If dialroles != 0, DialAssign(), DialGet() and DialMove() must be specified.
130  * @{
131  */
132  typedef struct gcontainerVMT {
133  gwidgetVMT gw;
134  coord_t (*LeftBorder) (GHandle gh); /**< The size of the left border (mandatory) */
135  coord_t (*TopBorder) (GHandle gh); /**< The size of the top border (mandatory) */
136  coord_t (*RightBorder) (GHandle gh); /**< The size of the right border (mandatory) */
137  coord_t (*BottomBorder) (GHandle gh); /**< The size of the bottom border (mandatory) */
138  void (*NotifyAdd) (GHandle gh, GHandle ghChild); /**< Notification that a child has been added (optional) */
139  void (*NotifyDelete) (GHandle gh, GHandle ghChild); /**< Notification that a child has been deleted (optional) */
140  } gcontainerVMT;
141  /** @} */
142 #endif
143 
144 #if GWIN_NEED_WINDOWMANAGER || defined(__DOXYGEN__)
145  // @note There is only ever one instance of each GWindowManager type
146  typedef struct GWindowManager {
147  const struct gwmVMT *vmt;
148  } GWindowManager;
149 
150  /**
151  * @brief The Virtual Method Table for a window manager
152  * @{
153  */
154  typedef struct gwmVMT {
155  void (*Init) (void); /**< The window manager has just been set as the current window manager */
156  void (*DeInit) (void); /**< The window manager has just been removed as the current window manager */
157  bool_t (*Add) (GHandle gh, const GWindowInit *pInit); /**< A window has been added */
158  void (*Delete) (GHandle gh); /**< A window has been deleted */
159  void (*Redraw) (GHandle gh); /**< A window needs to be redraw (or undrawn) */
160  void (*Size) (GHandle gh, coord_t w, coord_t h); /**< A window wants to be resized */
161  void (*Move) (GHandle gh, coord_t x, coord_t y); /**< A window wants to be moved */
162  void (*Raise) (GHandle gh); /**< A window wants to be on top */
163  void (*MinMax) (GHandle gh, GWindowMinMax minmax); /**< A window wants to be minimized/maximised */
164  } gwmVMT;
165  /** @} */
166 
167  /**
168  * @brief The current window manager
169  */
170  extern GWindowManager *_GWINwm;
171  extern bool_t _gwinFlashState;
172 
173 #endif
174 
175 #ifdef __cplusplus
176 extern "C" {
177 #endif
178 
179 /**
180  * @brief Initialise (and allocate if necessary) the base GWIN object
181  *
182  * @param[in] g The GDisplay to use for this window
183  * @param[in] pgw The GWindowObject structure. If NULL one is allocated from the heap
184  * @param[in] pInit The user initialization parameters
185  * @param[in] vmt The virtual method table for the GWIN object
186  * @param[in] flags The default flags to use
187  *
188  * @return The GHandle of the created window
189  *
190  * @notapi
191  */
192 GHandle _gwindowCreate(GDisplay *g, GWindowObject *pgw, const GWindowInit *pInit, const gwinVMT *vmt, uint32_t flags);
193 
194 /**
195  * @brief Redraw the window after a status change.
196  *
197  * @param[in] gh The widget to redraw
198  *
199  * @note Mark a window for redraw.
200  * @note The window will get redrawn at some later time.
201  * @note This call is designed to be fast and non-blocking
202  *
203  * @notapi
204  */
205 void _gwinUpdate(GHandle gh);
206 
207 /**
208  * @brief How to flush the redraws
209  * @notes REDRAW_WAIT - Wait for a drawing session to be available
210  * @notes REDRAW_NOWAIT - Do nothing if the drawing session is not available
211  * @note REDRAW_INSESSION - We are already in a drawing session
212  */
213 typedef enum GRedrawMethod { REDRAW_WAIT, REDRAW_NOWAIT, REDRAW_INSESSION } GRedrawMethod;
214 
215 /**
216  * @brief Flush any pending redraws in the system.
217  *
218  * @param[in] how Do we wait for the lock?
219  *
220  * @note This call will attempt to flush any pending redraws
221  * in the system. The doWait parameter tells this call
222  * how to handle someone already holding the drawing lock.
223  * If doWait is TRUE it waits to obtain the lock. If FALSE
224  * and the drawing lock is free then the redraw is done
225  * immediately. If the drawing lock was taken it will postpone the flush
226  * on the basis that someone else will do it for us later.
227  *
228  * @notapi
229  */
230 void _gwinFlushRedraws(GRedrawMethod how);
231 
232 /**
233  * @brief Obtain a drawing session
234  * @return TRUE if the drawing session was obtained, FALSE if the window is not visible
235  *
236  * @param[in] gh The window
237  *
238  * @note This function blocks until a drawing session is available if the window is visible
239  */
240 bool_t _gwinDrawStart(GHandle gh);
241 
242 /**
243  * @brief Release a drawing session
244  *
245  * @param[in] gh The window
246  */
247 void _gwinDrawEnd(GHandle gh);
248 
249 /**
250  * @brief Destroy a window.
251  *
252  * @param[in] gh The window
253  * @param[in] how Do we wait for the lock?
254  *
255  * @note If called without the drawing lock 'how' must be REDRAW_WAIT.
256  * If called with the drawing lock 'how' must be REDRAW_INSESSION.
257  *
258  * @notapi
259  */
260 void _gwinDestroy(GHandle gh, GRedrawMethod how);
261 
262 /**
263  * @brief Add a window to the window manager and set its position and size
264  * @return TRUE if successful
265  *
266  * @param[in] gh The window
267  * @param[in] pInit The window init structure
268  */
269 bool_t _gwinWMAdd(GHandle gh, const GWindowInit *pInit);
270 
271 #if GWIN_NEED_WIDGET || defined(__DOXYGEN__)
272  /**
273  * @brief Initialise (and allocate if necessary) the base Widget object
274  *
275  * @param[in] g The GDisplay to display this window on
276  * @param[in] pgw The GWidgetObject structure. If NULL one is allocated from the heap
277  * @param[in] pInit The user initialization parameters
278  * @param[in] vmt The virtual method table for the Widget object
279  *
280  * @return The GHandle of the created widget
281  *
282  * @notapi
283  */
284  GHandle _gwidgetCreate(GDisplay *g, GWidgetObject *pgw, const GWidgetInit *pInit, const gwidgetVMT *vmt);
285 
286  /**
287  * @brief Destroy the Widget object
288  *
289  * @param[in] gh The widget to destroy
290  *
291  * @notapi
292  */
293  void _gwidgetDestroy(GHandle gh);
294 
295  /**
296  * @brief Redraw the Widget object (VMT method only)
297  *
298  * @param[in] gh The widget to redraw
299  *
300  * @note Do not use this routine to update a widget after a status change.
301  * Use @p _gwinUpdate() instead. This routine should only be used in the
302  * VMT.
303  *
304  * @notapi
305  */
306  void _gwidgetRedraw(GHandle gh);
307 
308  /**
309  * @brief Send a standard GWIN event.
310  *
311  * @param[in] gh The window
312  * @param[in] type The event type
313  *
314  * @note No consideration is given to recording EVENT LOST statuses.
315  *
316  * @notapi
317  */
318  void _gwinSendEvent(GHandle gh, GEventType type);
319 
320  #if (GFX_USE_GINPUT && GINPUT_NEED_KEYBOARD) || GWIN_NEED_KEYBOARD || defined(__DOXYGEN__)
321  /**
322  * @brief Move the focus off the current focus window.
323  *
324  * @note The focus can stay on the same window if there is no other focusable window
325  *
326  * @notapi
327  */
328  void _gwinMoveFocus(void);
329 
330  /**
331  * @brief Do focus fixup's after a change of state for a window.
332  * @details If a focus window has become invisible or disabled then
333  * the focus must be taken away from it. If there is no focus
334  * window and this window is eligible then this window becomes
335  * the focus.
336  *
337  * @param[in] gh The window
338  *
339  * @note This routine does not actually do a redraw. It assumes that surrounding code
340  * will because of the change of state that lead to this being called.
341  *
342  * @notapi
343  */
344  void _gwinFixFocus(GHandle gh);
345 
346  /**
347  * @brief Draw a simple focus rectangle in the default style.
348  *
349  * @param[in] gw The widget
350  * @param[in] x, y The start x, y position (relative to the window)
351  * @param[in] cx, cy The width & height of the rectangle
352  *
353  * @note Assumes the widget is in a state where it can draw.
354  * @note Nothing is drawn if the window doesn't have focus.
355  * @note The focus rectangle may be more than one pixel thick and may
356  * not be a continuous line.
357  *
358  * @notapi
359  */
360  void _gwidgetDrawFocusRect(GWidgetObject *gw, coord_t x, coord_t y, coord_t cx, coord_t cy);
361 
362  #else
363  #define _gwinFixFocus(gh)
364  #define _gwidgetDrawFocusRect(gh,x,y,cx,cy)
365  #endif
366 
367  #if GWIN_NEED_FLASHING || defined(__DOXYGEN__)
368  /**
369  * @brief Convert a chosen style color set pressed/enabled etc if flashing
370  * @return The colorset - after flashing is taken into account
371  *
372  * @param[in] gw The widget
373  * @param[in] pcol The style color set that has been chosen to reflect the state of the widget
374  * @param[in] flashOffState Whether the off-state should be flashed as well. If false, only the
375  * pressed color set is flashed.
376  */
377  const GColorSet *_gwinGetFlashedColor(GWidgetObject *gw, const GColorSet *pcol, bool_t flashOffState);
378  #endif
379 #else
380  #define _gwinFixFocus(gh)
381 #endif
382 
383 #if GWIN_NEED_CONTAINERS || defined(__DOXYGEN__)
384  /**
385  * @brief Initialise (and allocate if necessary) the base Container object
386  *
387  * @param[in] g The GDisplay to display this window on
388  * @param[in] pgw The GContainerObject structure. If NULL one is allocated from the heap
389  * @param[in] pInit The user initialization parameters
390  * @param[in] vmt The virtual method table for the Container object
391  *
392  * @return The GHandle of the created widget
393  *
394  * @notapi
395  */
396  GHandle _gcontainerCreate(GDisplay *g, GContainerObject *pgw, const GWidgetInit *pInit, const gcontainerVMT *vmt);
397 
398  /**
399  * @brief Destroy the Container object
400  *
401  * @param[in] gh The container to destroy
402  *
403  * @notapi
404  */
405  void _gcontainerDestroy(GHandle gh);
406 
407  /**
408  * @brief Redraw the Container object (VMT method only)
409  *
410  * @param[in] gh The container to redraw
411  *
412  * @note Do not use this routine to update a container after a status change.
413  * Use @p _gwinUpdate() instead. This routine should only be used in the
414  * VMT.
415  *
416  * @notapi
417  */
418  #define _gcontainerRedraw _gwidgetRedraw
419 
420  /**
421  * @brief The visibility of something has changed. Ripple the changes.
422  *
423  * @note Does not actually trigger the redraw. It just marks as ready for redraw any
424  * visibility changes.
425  *
426  * @notapi
427  */
428  void _gwinRippleVisibility(void);
429 
430 #endif
431 
432 #ifdef __cplusplus
433 }
434 #endif
435 
436 #endif /* GFX_USE_GWIN */
437 
438 #endif /* _CLASS_GWIN_H */
439 /** @} */
size_t size
Definition: gwin_class.h:57
The Virtual Method Table for a window manager.
Definition: gwin_class.h:154
The structure to initialise a GWIN.
Definition: gwin.h:75
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
The structure to initialise a widget.
Definition: gwin_widget.h:97
The Virtual Method Table for a container.
Definition: gwin_class.h:132
const char * classname
Definition: gwin_class.h:56
The GColorSet structure.
Definition: gwin_widget.h:37
void(* Destroy)(GWindowObject *gh)
Definition: gwin_class.h:58
GWindowMinMax
A window&#39;s minimized, maximized or normal size.
Definition: gwin.h:90
void(* AfterClear)(GWindowObject *gh)
Definition: gwin_class.h:60
The GWIN Widget structure.
Definition: gwin_widget.h:118
The Virtual Method Table for a widget.
Definition: gwin_class.h:85
The Virtual Method Table for a GWIN window.
Definition: gwin_class.h:55
A window object structure.
Definition: gwin.h:40
void(* Redraw)(GWindowObject *gh)
Definition: gwin_class.h:59