version 2.8
gwin.h
Go to the documentation of this file.
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.h
10  *
11  * @defgroup Window Window
12  * @ingroup Windows
13  *
14  * @brief The basic window implementation (base class).
15  *
16  * @details GWIN provides a basic window manager which allows it to easily
17  * create and destroy different windows at runtime. Each window
18  * will have it's own properties such as colors as well as
19  * it's own drawing origin.
20  *
21  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
22  * @{
23  */
24 
25 #ifndef _GWIN_H
26 #define _GWIN_H
27 
28 #include "../../gfx.h"
29 
30 #if GFX_USE_GWIN || defined(__DOXYGEN__)
31 
32 /* Forward declaration */
33 typedef struct GWindowObject *GHandle;
34 
35 /**
36  * @brief A window object structure
37  * @note Do not access the members directly. Treat it as a black-box and use the method functions.
38  * @{
39  */
40 typedef struct GWindowObject {
41  #if GWIN_NEED_WINDOWMANAGER
42  // This MUST be the first member of the structure
43  gfxQueueASyncItem wmq; /**< The next window (for the window manager) */
44  #endif
45  const struct gwinVMT* vmt; /**< The VMT for this GWIN */
46  GDisplay * display; /**< The display this window is on */
47  coord_t x; /**< The position relative to the screen */
48  coord_t y; /**< The position relative to the screen */
49  coord_t width; /**< The width of this window */
50  coord_t height; /**< The height of this window */
51  color_t color; /**< The current foreground drawing color */
52  color_t bgcolor; /**< The current background drawing color */
53  uint32_t flags; /**< Window flags (the meaning is private to the GWIN class) */
54  #if GDISP_NEED_TEXT
55  font_t font; /**< The current font */
56  #endif
57  #if GWIN_NEED_CONTAINERS
58  GHandle parent; /**< The parent window */
59  #endif
60 } GWindowObject, * GHandle;
61 /** @} */
62 
63 /**
64  * @brief The structure to initialise a GWIN.
65  *
66  * @note Some gwin's will need extra parameters.
67  * @note The dimensions and position may be changed to fit on the real screen.
68  * @note If you create this structure on the stack, you should always memset
69  * it to all zero's first in case a future version of the software
70  * add's extra fields. Alternatively you can use @p gwinClearInit()
71  * to clear it.
72  *
73  * @{
74  */
75 typedef struct GWindowInit {
76  coord_t x; /**< The initial position relative to its parent */
77  coord_t y; /**< The initial position relative to its parent */
78  coord_t width; /**< The width */
79  coord_t height; /**< The height */
80  bool_t show; /**< Should the window be visible initially */
81  #if GWIN_NEED_CONTAINERS
82  GHandle parent; /**< The parent - must be a container or NULL */
83  #endif
84 } GWindowInit;
85 /** @} */
86 
87 /**
88  * @brief A window's minimized, maximized or normal size
89  */
90 typedef enum { GWIN_NORMAL, GWIN_MAXIMIZE, GWIN_MINIMIZE } GWindowMinMax;
91 
92 #ifdef __cplusplus
93 extern "C" {
94 #endif
95 
96 /*-------------------------------------------------
97  * Window Manager functions
98  *-------------------------------------------------*/
99 
100 #if GWIN_NEED_WINDOWMANAGER || defined(__DOXYGEN__)
101  // Forward definition
102  struct GWindowManager;
103 
104  /**
105  * @brief Set the window manager for the GWIN system.
106  *
107  * @param[in] gwm The window manager to use. Can be NULL to turn off the existing window manager.
108  *
109  * @note A window manager is responsible for handling when window visibility is changed or
110  * a window is resized for moved. Note that only saved window states will be redrawn. Each
111  * window type can save different information (or none at all). See the documentation on each window
112  * type to see which information it saves (and can therefore be automatically redrawn).
113  * For window types that do not save any state information, the window manager determines what to do.
114  * Generally it will just clear the window to its background color.
115  *
116  * @api
117  */
118  void gwinSetWindowManager(struct GWindowManager *gwm);
119 #endif
120 
121 /*-------------------------------------------------
122  * Functions that affect all windows
123  *-------------------------------------------------*/
124 
125  /**
126  * @brief Clear a GWindowInit structure to all zero's
127  * @note This function is provided just to prevent problems
128  * on operating systems where using memset() causes issues
129  * in the users application.
130  *
131  * @param[in] pwi The GWindowInit structure to clear
132  *
133  * @api
134  */
135  void gwinClearInit(GWindowInit *pwi);
136 
137  /**
138  * @brief Set the default foreground color for all new GWIN windows
139  *
140  * @param[in] clr The color to be set
141  *
142  * @api
143  */
144  void gwinSetDefaultColor(color_t clr);
145 
146  /**
147  * @brief Get the default foreground color for all new GWIN windows
148  *
149  * @return The current default color for all new GWIN windows
150  *
151  * @api
152  */
154 
155  /**
156  * @brief Set the default background color for all new GWIN windows
157  *
158  * @param[in] bgclr The background color
159  *
160  * @api
161  */
162  void gwinSetDefaultBgColor(color_t bgclr);
163 
164  /**
165  * @brief Get the default background color for all new GWIN windows
166  *
167  * @return The current default background color for all new GWIN windows
168  *
169  * @api
170  */
172 
173  #if GDISP_NEED_TEXT || defined(__DOXYGEN__)
174  /**
175  * @brief Set the default font for all new GWIN windows
176  *
177  * @param[in] font The new font to be set
178  *
179  * @api
180  */
181  void gwinSetDefaultFont(font_t font);
182 
183  /**
184  * @brief Get the current default font
185  *
186  * @return The current default font
187  *
188  * @api
189  */
191  #endif
192 
193 /*-------------------------------------------------
194  * Base functions
195  *-------------------------------------------------*/
196 
197  /**
198  * @brief Create a basic window.
199  * @return NULL if there is no resultant drawing area, otherwise a window handle.
200  *
201  * @param[in] g The GDisplay to display this window on
202  * @param[in] pgw The window structure to initialize. If this is NULL the structure is dynamically allocated.
203  * @param[in] pInit How to initialise the window
204  *
205  * @note The drawing color and the background color get set to the current defaults. If you haven't called
206  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively.
207  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
208  * is no default font and text drawing operations will no nothing.
209  * @note A basic window does not save the drawing state. It is not automatically redrawn if the window is moved or
210  * its visibility state is changed.
211  *
212  * @api
213  */
214  GHandle gwinGWindowCreate(GDisplay *g, GWindowObject *pgw, const GWindowInit *pInit);
215  #define gwinWindowCreate(pgw, pInit) gwinGWindowCreate(GDISP, pgw, pInit);
216 
217  /**
218  * @brief Destroy a window (of any type). Releases any dynamically allocated memory.
219  *
220  * @param[in] gh The window handle
221  *
222  * @api
223  */
224  void gwinDestroy(GHandle gh);
225 
226  /**
227  * @brief Get the real class name of the GHandle
228  * @details Returns a string describing the object class.
229  *
230  * @param[in] gh The window
231  *
232  * @return A string describing the object class.
233  *
234  * @api
235  */
236  const char* gwinGetClassName(GHandle gh);
237 
238  /**
239  * @brief Get an ID that uniquely describes the class of the GHandle
240  *
241  * @param[in] gh The window
242  *
243  * @api
244  */
245  #define gwinGetClassID(gh) ((void *)((gh)->vmt))
246 
247  /**
248  * @brief Get the X coordinate of the window
249  * @details Returns the X coordinate of the origin of the window.
250  * The coordinate is relative to the physical screen zero point.
251  *
252  * @param[in] gh The window
253  *
254  * @api
255  */
256  #define gwinGetScreenX(gh) ((gh)->x)
257 
258  /**
259  * @brief Get the Y coordinate of the window
260  * @details Returns the Y coordinate of the origin of the window.
261  * The coordinate is relative to the physical screen zero point.
262  *
263  * @param[in] gh The window
264  *
265  * @api
266  */
267  #define gwinGetScreenY(gh) ((gh)->y)
268 
269  /**
270  * @brief Get the width of the window
271  *
272  * @param[in] gh The window
273  *
274  * @api
275  */
276  #define gwinGetWidth(gh) ((gh)->width)
277 
278  /**
279  * @brief Get the height of the window
280  *
281  * @param[in] gh The window
282  *
283  * @api
284  */
285  #define gwinGetHeight(gh) ((gh)->height)
286 
287  /**
288  * @brief Set foreground color
289  * @details Set the color which will be used to draw
290  *
291  * @param[in] gh The window
292  * @param[in] clr The color to be set
293  *
294  * @api
295  */
296  #define gwinSetColor(gh, clr) (gh)->color = (clr)
297 
298  /**
299  * @brief Set background color
300  * @details Set the color which will be used as background
301  * @note gwinClear() must be called to set the background color
302  *
303  * @param[in] gh The window
304  * @param[in] bgclr The background color
305  *
306  * @api
307  */
308  #define gwinSetBgColor(gh, bgclr) (gh)->bgcolor = (bgclr)
309 
310  /**
311  * @brief Get the foreground color of a window
312  *
313  * @param[in] gh The window
314  *
315  * @api
316  */
317  #define gwinGetColor(gh) (gh)->color
318 
319  /**
320  * @brief Get the background color of a window
321  *
322  * @param[in] gh The window
323  *
324  * @api
325  */
326  #define gwinGetBgColor(gh) (gh)->bgcolor
327 
328  /**
329  * @brief Sets whether a window is visible or not
330  *
331  * @param[in] gh The window
332  * @param[in] visible Whether the window should be visible or not
333  *
334  * @note When a window is marked as not visible, drawing operations
335  * on the window do nothing.
336  * @note When a window is marked as visible, it is not automatically
337  * redrawn as many window types don't remember their drawing state.
338  * Widgets such as Buttons, Sliders etc will be redrawn.
339  * @note If there is no window manager in use, when a window is marked
340  * as not visible, nothing is done to remove the window from the screen.
341  * When there is a window manager, it is up to the window manager to
342  * handle what happens.
343  * @note Even when you mark a window as visible, it may still not be displayed
344  * if it's parent is invisible. When the parent becomes visible this child
345  * will automatically be shown because it is already marked as visible.
346  *
347  * @api
348  */
349  void gwinSetVisible(GHandle gh, bool_t visible);
350 
351  /**
352  * @brief Makes a widget become visible
353  *
354  * @param[in] gh The window handle
355  *
356  * @api
357  */
358  #define gwinShow(gh) gwinSetVisible(gh, TRUE)
359 
360  /**
361  * @brief Makes a widget become invisible
362  *
363  * @param[in] gh The window handle
364  *
365  * @api
366  */
367  #define gwinHide(gh) gwinSetVisible(gh, FALSE)
368 
369  /**
370  * @brief Gets the visibility of a window
371  * @return TRUE if visible
372  *
373  * @note It is possible for a child to be marked as visible by @p gwinSetVisible()
374  * but for this call to return FALSE if one of its parents are not visible.
375  *
376  * @param[in] gh The window
377  *
378  * @api
379  */
380  bool_t gwinGetVisible(GHandle gh);
381 
382  /**
383  * @brief Enable or disable a window
384  *
385  * @param[in] gh The window handle
386  * @param[in] enabled Enable or disable the window
387  *
388  * @note The window is automatically redrawn if it supports self-redrawing.
389  * @note Even when you mark a window as enabled, it may still remain disabled
390  * if it's parent is disabled. When the parent becomes enabled this child
391  * will automatically be enabled because it is already marked as enabled.
392  *
393  * @api
394  */
395  void gwinSetEnabled(GHandle gh, bool_t enabled);
396 
397  /**
398  * @brief Enables a widget
399  *
400  * @param[in] gh The window handle
401  *
402  * @api
403  */
404  #define gwinEnable(gh) gwinSetEnabled(gh, TRUE)
405 
406  /**
407  * @brief Disables a widget
408  *
409  * @param[in] gh The window handle
410  *
411  * @api
412  */
413  #define gwinDisable(gh) gwinSetEnabled(gh, FALSE)
414 
415  /**
416  * @brief Gets the enabled state of a window
417  * @return TRUE if enabled
418  *
419  * @note It is possible for a child to be marked as enabled by @p gwinSetEnabled()
420  * but for this call to return FALSE if one of its parents are not enabled.
421  *
422  * @param[in] gh The window
423  *
424  * @api
425  */
426  bool_t gwinGetEnabled(GHandle gh);
427 
428  /**
429  * @brief Move a window
430  *
431  * @param[in] gh The window
432  * @param[in] x, y The new position (screen relative) for this window
433  *
434  * @note The final window position may not be the requested position. Windows
435  * are clipped to the screen area and the window manager may also affect the position.
436  * @note The window is redrawn if it is visible. See the comments in @p gwinSetVisible()
437  * with regard to what can be redrawn and what can't.
438  * @note It is up to the window manager to determine what happens with the screen area
439  * uncovered by moving the window. When there is no window manager, nothing
440  * is done with the uncovered area.
441  *
442  * @api
443  */
444  void gwinMove(GHandle gh, coord_t x, coord_t y);
445 
446  /**
447  * @brief Resize a window
448  *
449  * @param[in] gh The window
450  * @param[in] width, height The new size of the window
451  *
452  * @note The final window size may not be the requested size. Windows
453  * are clipped to the screen area and the window manager may also affect the size.
454  * @note The window is redrawn if it is visible. See the comments in @p gwinSetVisible()
455  * with regard to what can be redrawn and what can't.
456  * @note It is up to the window manager to determine what happens with any screen area
457  * uncovered by resizing the window. When there is no window manager, nothing
458  * is done with the uncovered area.
459  *
460  * @api
461  */
462  void gwinResize(GHandle gh, coord_t width, coord_t height);
463 
464  /**
465  * @brief Redraw a window
466  *
467  * @param[in] gh The window
468  *
469  * @note This is normally never required as windows and widgets will redraw as required.
470  * Note that some windows are incapable of redrawing themselves as they don't save
471  * their drawing state.
472  *
473  * @api
474  */
475  void gwinRedraw(GHandle gh);
476 
477  #if GWIN_NEED_WINDOWMANAGER || defined (__DOXYGEN__)
478  /**
479  * @brief Redraw a display
480  *
481  * @param[in] g The display to redraw. Passing NULL will redraw all displays.
482  * @param[in] preserve Should the redraw try to preserve existing screen data for those
483  * windows that can't redraw themselves?
484  *
485  * @note This is normally never required as windows and widgets will redraw as required.
486  * @note Some windows are incapable of redrawing themselves as they don't save
487  * their drawing state.
488  * @note This does not clear the background - just redraws the gwin windows (where possible)
489  *
490  * @api
491  */
492  void gwinRedrawDisplay(GDisplay *g, bool_t preserve);
493 
494  /**
495  * @brief Minimize, Maximize or Restore a window
496  * @pre GWIN_NEED_WINDOWMANAGER must be TRUE
497  *
498  * @param[in] gh The window
499  * @param[in] minmax The new minimized/maximized state
500  *
501  * @note The final window state may not be the requested state. Window Managers
502  * do not need to implement changing the minmax state. If there is no
503  * window manager this call is ignored.
504  * @note The window is redrawn if it is changed. See the comments in @p gwinSetVisible()
505  * with regard to what can be redrawn and what can't.
506  * @note It is up to the window manager to determine what happens with any screen area
507  * uncovered by resizing the window.
508  * @note When a window is minimised it may be asked to draw the window or the window
509  * manager may draw the minimised window.
510  *
511  * @api
512  */
513  void gwinSetMinMax(GHandle gh, GWindowMinMax minmax);
514 
515  /**
516  * @brief Get the Minimized/Maximized state of a window
517  * @pre GWIN_NEED_WINDOWMANAGER must be TRUE
518  *
519  * @param[in] gh The window
520  *
521  * @return GWIN_NORMAL, GWIN_MAXIMIZE or GWIN_MINIMIZE
522  *
523  * @api
524  */
525  GWindowMinMax gwinGetMinMax(GHandle gh);
526 
527  /**
528  * @brief Raise a window to the top of the z-order
529  * @pre GWIN_NEED_WINDOWMANAGER must be TRUE
530  *
531  * @param[in] gh The window
532  *
533  * @note The window z-order is only supported by some window managers. See the comments
534  * in @p gwinSetVisible() with regard to what can be redrawn and what can't.
535  *
536  * @api
537  */
538  void gwinRaise(GHandle gh);
539 
540  /**
541  * @brief Get the next window in the z-order
542  * @return The next window or NULL if no more windows
543  *
544  * @param[in] gh The previous window or NULL to get the first window
545  *
546  * @note This returns the next window in the system from top to bottom.
547  * @note Where there are parent child relationships, this ignores them
548  * and will list all windows in the system. There is no defined
549  * order between children of siblings and they can in fact be mixed
550  * in order. The only relationship honored is that parents will be
551  * listed before their children.
552  *
553  * @api
554  */
555  GHandle gwinGetNextWindow(GHandle gh);
556 
557  /**
558  * @brief Set a window or widget to flash
559  *
560  * @param[in] gh The window handle
561  * @param[in] flash Enable or disable the flashing of the window
562  *
563  * @note The window is automatically redrawn if it supports self-redrawing.
564  * @note When a window is set to flash, its appearance changes in some
565  * way every flash period (GWIN_FLASHING_PERIOD). How its appearance
566  * changes depends on the draw for each window/widget.
567  *
568  * @pre Requires GWIN_NEED_FLASHING to be TRUE
569  *
570  * @api
571  */
572  void gwinSetFlashing(GHandle gh, bool_t flash);
573 
574  /**
575  * @brief Enables flashing of a window or widget
576  *
577  * @param[in] gh The window handle
578  *
579  * @api
580  */
581  #define gwinFlash(gh) gwinSetFlashing(gh, TRUE)
582 
583  /**
584  * @brief Disables a widget
585  *
586  * @param[in] gh The window handle
587  *
588  * @api
589  */
590  #define gwinNoFlash(gh) gwinSetFlashing(gh, FALSE)
591  #endif
592 
593  #if GDISP_NEED_TEXT || defined(__DOXYGEN__)
594  /**
595  * @brief Set the current font for this window.
596  *
597  * @param[in] gh The window handle
598  * @param[in] font The font to use for text functions
599  *
600  * @api
601  */
602  void gwinSetFont(GHandle gh, font_t font);
603  #endif
604 
605 /*-------------------------------------------------
606  * Drawing functions
607  *-------------------------------------------------*/
608 
609  /**
610  * @brief Clear the window
611  * @note Uses the current background color to clear the window
612  *
613  * @param[in] gh The window handle
614  *
615  * @api
616  */
617  void gwinClear(GHandle gh);
618 
619  /**
620  * @brief Set a pixel in the window
621  * @note Uses the current foreground color to set the pixel
622  * @note May leave GDISP clipping to this window's dimensions
623  *
624  * @param[in] gh The window handle
625  * @param[in] x,y The coordinates of the pixel
626  *
627  * @api
628  */
629  void gwinDrawPixel(GHandle gh, coord_t x, coord_t y);
630 
631  /**
632  * @brief Draw a line in the window
633  * @note Uses the current foreground color to draw the line
634  * @note May leave GDISP clipping to this window's dimensions
635  *
636  * @param[in] gh The window handle
637  * @param[in] x0,y0 The start position
638  * @param[in] x1,y1 The end position
639  *
640  * @api
641  */
642  void gwinDrawLine(GHandle gh, coord_t x0, coord_t y0, coord_t x1, coord_t y1);
643 
644  /**
645  * @brief Draw a box in the window
646  * @note Uses the current foreground color to draw the box
647  * @note May leave GDISP clipping to this window's dimensions
648  *
649  * @param[in] gh The window handle
650  * @param[in] x,y The start position
651  * @param[in] cx,cy The size of the box (outside dimensions)
652  *
653  * @api
654  */
655  void gwinDrawBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy);
656 
657  /**
658  * @brief Fill an rectangular area in the window
659  * @note Uses the current foreground color to fill the box
660  * @note May leave GDISP clipping to this window's dimensions
661  *
662  * @param[in] gh The window handle
663  * @param[in] x,y The start position
664  * @param[in] cx,cy The size of the box (outside dimensions)
665  *
666  * @api
667  */
668  void gwinFillArea(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy);
669 
670  /**
671  * @brief Fill an area in the window using the supplied bitmap.
672  * @details The bitmap is in the pixel format specified by the low level driver
673  * @note If GDISP_NEED_ASYNC is defined then the buffer must be static
674  * or at least retained until this call has finished the blit. You can
675  * tell when all graphics drawing is finished by @p gdispIsBusy() going FALSE.
676  * @note May leave GDISP clipping to this window's dimensions
677  *
678  * @param[in] gh The window handle
679  * @param[in] x, y The start filled area
680  * @param[in] cx, cy The width and height to be filled
681  * @param[in] srcx, srcy The bitmap position to start the fill from
682  * @param[in] srccx The width of a line in the bitmap.
683  * @param[in] buffer The pixels to use to fill the area.
684  *
685  * @api
686  */
687  void gwinBlitArea(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t srcx, coord_t srcy, coord_t srccx, const pixel_t *buffer);
688 
689 /*-------------------------------------------------
690  * Circle, ellipse, arc and arc-sectors functions
691  *-------------------------------------------------*/
692 
693  #if GDISP_NEED_CIRCLE || defined(__DOXYGEN__)
694  /**
695  * @brief Draw a circle in the window.
696  * @note Uses the current foreground color to draw the circle
697  * @note May leave GDISP clipping to this window's dimensions
698  *
699  * @param[in] gh The window handle
700  * @param[in] x, y The center of the circle
701  * @param[in] radius The radius of the circle
702  *
703  * @api
704  */
705  void gwinDrawCircle(GHandle gh, coord_t x, coord_t y, coord_t radius);
706 
707  /**
708  * @brief Draw a filled circle in the window.
709  * @note Uses the current foreground color to draw the filled circle
710  * @note May leave GDISP clipping to this window's dimensions
711  *
712  * @param[in] gh The window handle
713  * @param[in] x, y The center of the circle
714  * @param[in] radius The radius of the circle
715  *
716  * @api
717  */
718  void gwinFillCircle(GHandle gh, coord_t x, coord_t y, coord_t radius);
719  #endif
720 
721  #if GDISP_NEED_DUALCIRCLE || defined(__DOXYGEN__)
722  /**
723  * @brief Draw two filled circles with the same centre in the window.
724  * @note Uses the current foreground color to draw the inner circle
725  * @note Uses the current background color to draw the outer circle
726  * @note May leave GDISP clipping to this window's dimensions
727  * @pre GDISP_NEED_DUALCIRCLE must be TRUE in your gfxconf.h
728  *
729  * @param[in] gh The window handle
730  * @param[in] x,y The center of the circle
731  * @param[in] radius1 The radius of the larger circle
732  * @param[in] radius2 The radius of the smaller circle
733  *
734  * @api
735  */
736  void gwinFillDualCircle(GHandle gh, coord_t x, coord_t y, coord_t radius1, coord_t radius2);
737  #endif
738 
739  #if GDISP_NEED_ELLIPSE || defined(__DOXYGEN__)
740  /**
741  * @brief Draw an ellipse.
742  * @note Uses the current foreground color to draw the ellipse
743  * @note May leave GDISP clipping to this window's dimensions
744  *
745  * @param[in] gh The window handle
746  * @param[in] x,y The center of the ellipse
747  * @param[in] a,b The dimensions of the ellipse
748  *
749  * @api
750  */
751  void gwinDrawEllipse(GHandle gh, coord_t x, coord_t y, coord_t a, coord_t b);
752 
753  /**
754  * @brief Draw an filled ellipse.
755  * @note Uses the current foreground color to draw the filled ellipse
756  * @note May leave GDISP clipping to this window's dimensions
757  *
758  * @param[in] gh The window handle
759  * @param[in] x,y The center of the ellipse
760  * @param[in] a,b The dimensions of the ellipse
761  *
762  * @api
763  */
764  void gwinFillEllipse(GHandle gh, coord_t x, coord_t y, coord_t a, coord_t b);
765  #endif
766 
767  #if GDISP_NEED_ARC || defined(__DOXYGEN__)
768  /*
769  * @brief Draw an arc in the window.
770  * @note Uses the current foreground color to draw the arc
771  * @note May leave GDISP clipping to this window's dimensions
772  *
773  * @param[in] gh The window handle
774  * @param[in] x,y The center point
775  * @param[in] radius The radius of the arc
776  * @param[in] start The start angle (0 to 360)
777  * @param[in] end The end angle (0 to 360)
778  *
779  * @api
780  */
781  void gwinDrawArc(GHandle gh, coord_t x, coord_t y, coord_t radius, coord_t startangle, coord_t endangle);
782 
783  /*
784  * @brief Draw a filled arc in the window.
785  * @note Uses the current foreground color to draw the filled arc
786  * @note May leave GDISP clipping to this window's dimensions
787  *
788  * @param[in] gh The window handle
789  * @param[in] x,y The center point
790  * @param[in] radius The radius of the arc
791  * @param[in] start The start angle (0 to 360)
792  * @param[in] end The end angle (0 to 360)
793  *
794  * @api
795  */
796  void gwinFillArc(GHandle gh, coord_t x, coord_t y, coord_t radius, coord_t startangle, coord_t endangle);
797 
798  /*
799  * @brief Draw a thick arc in the window.
800  * @note Uses the current foreground color to draw the thick arc
801  * @note May leave GDISP clipping to this window's dimensions
802  *
803  * @param[in] gh The window handle
804  * @param[in] x,y The center point
805  * @param[in] startradius The inner radius of the thick arc
806  * @param[in] endradius The outer radius of the thick arc
807  * @param[in] startangle The start angle (0 to 360)
808  * @param[in] endangle The end angle (0 to 360)
809  *
810  * @api
811  */
812  void gwinDrawThickArc(GHandle gh, coord_t x, coord_t y, coord_t startradius, coord_t endradius, coord_t startangle, coord_t endangle);
813  #endif
814 
815  #if GDISP_NEED_ARCSECTORS || defined(__DOXYGEN__)
816  /*
817  * @brief Draw a selection of 45 degree arcs of a circle in the window.
818  * @note Uses the current foreground color to draw the arc sector
819  * @note May leave GDISP clipping to this window's dimensions
820  *
821  * @param[in] gh The window handle
822  * @param[in] x,y The center of the circle
823  * @param[in] radius The radius of the circle
824  * @param[in] sectors Bits determine which sectors are drawn.
825  * Bits go anti-clockwise from the 0 degree mark (y = 0, x is positive), as follows:
826  * bit 0 - upper right right -----
827  * bit 1 - upper upper right /2 1\
828  * bit 2 - upper upper left /3 0\
829  * bit 3 - upper left left \4 7/
830  * bit 4 - lower left left \5 6/
831  * bit 5 - lower lower left -----
832  * bit 6 - lower lower right
833  * bit 7 - lower left left
834  *
835  * @api
836  */
837  void gwinDrawArcSectors(GHandle gh, coord_t x, coord_t y, coord_t radius, uint8_t sectors);
838 
839  /*
840  * @brief Draw a filled selection of 45 degree arcs of a circle in the window.
841  * @note Uses the current foreground color to draw the arc sector
842  * @note May leave GDISP clipping to this window's dimensions
843  *
844  * @param[in] gh The window handle
845  * @param[in] x,y The center of the circle
846  * @param[in] radius The radius of the circle
847  * @param[in] sectors Bits determine which sectors are drawn.
848  * Bits go anti-clockwise from the 0 degree mark (y = 0, x is positive), as follows:
849  * bit 0 - upper right right -----
850  * bit 1 - upper upper right /2 1\
851  * bit 2 - upper upper left /3 0\
852  * bit 3 - upper left left \4 7/
853  * bit 4 - lower left left \5 6/
854  * bit 5 - lower lower left -----
855  * bit 6 - lower lower right
856  * bit 7 - lower left left
857  *
858  * @api
859  */
860  void gwinFillArcSectors(GHandle gh, coord_t x, coord_t y, coord_t radius, uint8_t sectors);
861  #endif
862 
863 /*-------------------------------------------------
864  * Pixel read-back functions
865  *-------------------------------------------------*/
866 
867  #if GDISP_NEED_PIXELREAD || defined(__DOXYGEN__)
868  /**
869  * @brief Get the color of a pixel in the window.
870  * @return The color of the pixel.
871  * @note May leave GDISP clipping to this window's dimensions
872  *
873  * @param[in] gh The window handle
874  * @param[in] x,y The position in the window
875  *
876  * @api
877  */
878  color_t gwinGetPixelColor(GHandle gh, coord_t x, coord_t y);
879  #endif
880 
881 /*-------------------------------------------------
882  * Text functions
883  *-------------------------------------------------*/
884 
885  #if GDISP_NEED_TEXT || defined(__DOXYGEN__)
886  /**
887  * @brief Draw a text character at the specified position in the window.
888  * @pre The font must have been set.
889  * @note Uses the current foreground color to draw the character
890  * @note May leave GDISP clipping to this window's dimensions
891  *
892  * @param[in] gh The window handle
893  * @param[in] x,y The position for the text
894  * @param[in] c The character to draw
895  *
896  * @api
897  */
898  void gwinDrawChar(GHandle gh, coord_t x, coord_t y, char c);
899 
900  /**
901  * @brief Draw a text character with a filled background at the specified position in the window.
902  * @pre The font must have been set.
903  * @note Uses the current foreground color to draw the character and fills the background using the background drawing color
904  * @note May leave GDISP clipping to this window's dimensions
905  *
906  * @param[in] gh The window handle
907  * @param[in] x,y The position for the text
908  * @param[in] c The character to draw
909  *
910  * @api
911  */
912  void gwinFillChar(GHandle gh, coord_t x, coord_t y, char c);
913 
914  /**
915  * @brief Draw a text string in the window
916  * @pre The font must have been set.
917  * @note Uses the current foreground color to draw the character
918  * @note May leave GDISP clipping to this window's dimensions
919  *
920  * @param[in] gh The window handle
921  * @param[in] x,y The position for the text
922  * @param[in] str The string to draw
923  *
924  * @api
925  */
926  void gwinDrawString(GHandle gh, coord_t x, coord_t y, const char *str);
927 
928  /**
929  * @brief Draw a text string with a filled background in the window
930  * @pre The font must have been set.
931  * @note Uses the current foreground color to draw the character and fills the background using the background drawing color
932  * @note May leave GDISP clipping to this window's dimensions
933  *
934  * @param[in] gh The window handle
935  * @param[in] x,y The position for the text
936  * @param[in] str The string to draw
937  *
938  * @api
939  */
940  void gwinFillString(GHandle gh, coord_t x, coord_t y, const char *str);
941 
942  /**
943  * @brief Draw a text string verticly centered within the specified box.
944  * @pre The font must have been set.
945  * @note Uses the current foreground color to draw the character.
946  * @note The specified box does not need to align with the window box
947  * @note May leave GDISP clipping to this window's dimensions
948  *
949  * @param[in] gh The window handle
950  * @param[in] x,y The position for the text (need to define top-right or base-line - check code)
951  * @param[in] cx,cy The width and height of the box
952  * @param[in] str The string to draw
953  * @param[in] justify Justify the text left, center or right within the box
954  *
955  * @api
956  */
957  void gwinDrawStringBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, const char* str, justify_t justify);
958 
959  /**
960  * @brief Draw a text string verticly centered within the specified filled box.
961  * @pre The font must have been set.
962  * @note Uses the current foreground color to draw the character and fills the background using the background drawing color
963  * @note The entire box is filled. Note this box does not need to align with the window box
964  * @note May leave GDISP clipping to this window's dimensions
965  *
966  * @param[in] gh The window handle
967  * @param[in] x,y The position for the text (need to define top-right or base-line - check code)
968  * @param[in] cx,cy The width and height of the box
969  * @param[in] str The string to draw
970  * @param[in] justify Justify the text left, center or right within the box
971  *
972  * @api
973  */
974  void gwinFillStringBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, const char* str, justify_t justify);
975  #endif
976 
977 /*-------------------------------------------------
978  * Polygon functions
979  *-------------------------------------------------*/
980 
981  #if GDISP_NEED_CONVEX_POLYGON || defined(__DOXYGEN__)
982  /**
983  * @brief Draw an enclosed polygon (convex, non-convex or complex).
984  *
985  * @note Uses the current foreground color.
986  *
987  * @param[in] gh The window handle
988  * @param[in] tx, ty Transform all points in pntarray by tx, ty
989  * @param[in] pntarray An array of points
990  * @param[in] cnt The number of points in the array
991  *
992  * @api
993  */
994  void gwinDrawPoly(GHandle gh, coord_t tx, coord_t ty, const point *pntarray, unsigned cnt);
995 
996  /**
997  * @brief Fill a convex polygon
998  * @details Doesn't handle non-convex or complex polygons.
999  *
1000  * @note Uses the current foreground color.
1001  *
1002  * @param[in] gh The window handle
1003  * @param[in] tx, ty Transform all points in pntarray by tx, ty
1004  * @param[in] pntarray An array of points
1005  * @param[in] cnt The number of points in the array
1006  *
1007  * @note Convex polygons are those that have no internal angles. That is;
1008  * you can draw a line from any point on the polygon to any other point
1009  * on the polygon without it going outside the polygon. In our case we generalise
1010  * this a little by saying that an infinite horizontal line (at any y value) will cross
1011  * no more than two edges on the polygon. Some non-convex polygons do fit this criteria
1012  * and can therefore be drawn.
1013  * @note This routine is designed to be very efficient with even simple display hardware.
1014  *
1015  * @api
1016  */
1017  void gwinFillConvexPoly(GHandle gh, coord_t tx, coord_t ty, const point *pntarray, unsigned cnt);
1018 
1019  /**
1020  * @brief Draw a thick line in the window
1021  * @details The line thickness is specified in pixels. The line ends can
1022  * be selected to be either flat or round.
1023  * @note Uses gdispGFillConvexPoly() internally to perform the drawing.
1024  * @note Uses the current foreground color to draw the line
1025  *
1026  * @param[in] gh The window handle
1027  * @param[in] x0,y0 The start position
1028  * @param[in] x1,y1 The end position
1029  * @param[in] width The width of the line
1030  * @param[in] round Use round ends for the line
1031  *
1032  * @api
1033  */
1034  void gwinDrawThickLine(GHandle gh, coord_t x0, coord_t y0, coord_t x1, coord_t y1, coord_t width, bool_t round);
1035  #endif
1036 
1037 /*-------------------------------------------------
1038  * Image functions
1039  *-------------------------------------------------*/
1040 
1041  #if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
1042  /**
1043  * @brief Draw the image
1044  * @return GDISP_IMAGE_ERR_OK (0) on success or an error code.
1045  *
1046  * @param[in] gh The window handle
1047  * @param[in] img The image structure
1048  * @param[in] x,y The window location to draw the image
1049  * @param[in] cx,cy The area on the screen to draw
1050  * @param[in] sx,sy The image position to start drawing at
1051  *
1052  * @pre gdispImageOpen() must have returned successfully.
1053  *
1054  * @note If sx,sy + cx,cy is outside the image boundaries the area outside the image
1055  * is simply not drawn.
1056  * @note If @p gdispImageCache() has been called first for this frame, this routine will draw using a
1057  * fast blit from the cached frame. If not, it reads the input and decodes it as it
1058  * is drawing. This may be significantly slower than if the image has been cached (but
1059  * uses a lot less RAM)
1060  *
1061  * @api
1062  */
1063  gdispImageError gwinDrawImage(GHandle gh, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy);
1064  #endif
1065 
1066 #ifdef __cplusplus
1067 }
1068 #endif
1069 
1070 /*-------------------------------------------------
1071  * Additional functionality
1072  *-------------------------------------------------*/
1073 
1074  /* Include widgets */
1075  #if GWIN_NEED_WIDGET || defined(__DOXYGEN__)
1076  #include "gwin_widget.h"
1077  #endif
1078 
1079  /* Include containers */
1080  #if GWIN_NEED_CONTAINERS || defined(__DOXYGEN__)
1081  #include "gwin_container.h"
1082  #endif
1083 
1084  /* Include vanilla window objects */
1085  #if GWIN_NEED_CONSOLE || defined(__DOXYGEN__)
1086  #include "gwin_console.h"
1087  #endif
1088  #if GWIN_NEED_GRAPH || defined(__DOXYGEN__)
1089  #include "gwin_graph.h"
1090  #endif
1091  #if GWIN_NEED_IMAGE || defined(__DOXYGEN__)
1092  #include "gwin_image.h"
1093  #endif
1094  #if GWIN_NEED_GL3D || defined(__DOXYGEN__)
1095  #include "gwin_gl3d.h"
1096  #endif
1097 
1098 #endif /* GFX_USE_GWIN */
1099 
1100 #endif /* _GWIN_H */
1101 /** @} */
void gwinDrawPoly(GHandle gh, coord_t tx, coord_t ty, const point *pntarray, unsigned cnt)
Draw an enclosed polygon (convex, non-convex or complex).
void gwinSetFlashing(GHandle gh, bool_t flash)
Set a window or widget to flash.
const struct mf_font_s * font_t
The type of a font.
Definition: gdisp.h:93
const struct gwinVMT * vmt
Definition: gwin.h:45
void gwinRedraw(GHandle gh)
Redraw a window.
void gwinSetMinMax(GHandle gh, GWindowMinMax minmax)
Minimize, Maximize or Restore a window.
void gwinClear(GHandle gh)
Clear the window.
The structure to initialise a GWIN.
Definition: gwin.h:75
GHandle gwinGetNextWindow(GHandle gh)
Get the next window in the z-order.
struct GWindowInit GWindowInit
The structure to initialise a GWIN.
void gwinBlitArea(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t srcx, coord_t srcy, coord_t srccx, const pixel_t *buffer)
Fill an area in the window using the supplied bitmap.
uint32_t flags
Definition: gwin.h:53
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
coord_t y
Definition: gwin.h:77
gdispImageError gwinDrawImage(GHandle gh, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy)
Draw the image.
void gwinFillEllipse(GHandle gh, coord_t x, coord_t y, coord_t a, coord_t b)
Draw an filled ellipse.
bool_t gwinGetEnabled(GHandle gh)
Gets the enabled state of a window.
void gwinSetDefaultColor(color_t clr)
Set the default foreground color for all new GWIN windows.
color_t gwinGetDefaultColor(void)
Get the default foreground color for all new GWIN windows.
A queue item.
Definition: gqueue.h:40
coord_t y
Definition: gwin.h:48
coord_t x
Definition: gwin.h:47
struct GWindowObject GWindowObject
A window object structure.
void gwinResize(GHandle gh, coord_t width, coord_t height)
Resize a window.
void gwinSetFont(GHandle gh, font_t font)
Set the current font for this window.
void gwinRedrawDisplay(GDisplay *g, bool_t preserve)
Redraw a display.
font_t gwinGetDefaultFont(void)
Get the current default font.
void gwinDrawChar(GHandle gh, coord_t x, coord_t y, char c)
Draw a text character at the specified position in the window.
void gwinClearInit(GWindowInit *pwi)
Clear a GWindowInit structure to all zero&#39;s.
void gwinFillString(GHandle gh, coord_t x, coord_t y, const char *str)
Draw a text string with a filled background in the window.
void gwinRaise(GHandle gh)
Raise a window to the top of the z-order.
void gwinDrawLine(GHandle gh, coord_t x0, coord_t y0, coord_t x1, coord_t y1)
Draw a line in the window.
void gwinDrawStringBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, const char *str, justify_t justify)
Draw a text string verticly centered within the specified box.
GWIN Graphic window subsystem header file.
justify
Type for the text justification.
Definition: gdisp.h:60
GWindowMinMax
A window&#39;s minimized, maximized or normal size.
Definition: gwin.h:90
void gwinFillArea(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy)
Fill an rectangular area in the window.
void gwinFillChar(GHandle gh, coord_t x, coord_t y, char c)
Draw a text character with a filled background at the specified position in the window.
void gwinDestroy(GHandle gh)
Destroy a window (of any type). Releases any dynamically allocated memory.
void gwinFillCircle(GHandle gh, coord_t x, coord_t y, coord_t radius)
Draw a filled circle in the window.
void gwinDrawPixel(GHandle gh, coord_t x, coord_t y)
Set a pixel in the window.
void gwinDrawBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy)
Draw a box in the window.
void gwinSetVisible(GHandle gh, bool_t visible)
Sets whether a window is visible or not.
color_t gwinGetDefaultBgColor(void)
Get the default background color for all new GWIN windows.
void gwinDrawCircle(GHandle gh, coord_t x, coord_t y, coord_t radius)
Draw a circle in the window.
void gwinFillStringBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, const char *str, justify_t justify)
Draw a text string verticly centered within the specified filled box.
void gwinSetDefaultFont(font_t font)
Set the default font for all new GWIN windows.
void gwinDrawThickLine(GHandle gh, coord_t x0, coord_t y0, coord_t x1, coord_t y1, coord_t width, bool_t round)
Draw a thick line in the window.
bool_t show
Definition: gwin.h:80
GWIN Widgets header file.
color_t bgcolor
Definition: gwin.h:52
GDisplay * display
Definition: gwin.h:46
coord_t height
Definition: gwin.h:79
void gwinDrawString(GHandle gh, coord_t x, coord_t y, const char *str)
Draw a text string in the window.
bool_t gwinGetVisible(GHandle gh)
Gets the visibility of a window.
coord_t x
Definition: gwin.h:76
coord_t height
Definition: gwin.h:50
void gwinSetEnabled(GHandle gh, bool_t enabled)
Enable or disable a window.
GWIN GRAPH module header file.
void gwinFillDualCircle(GHandle gh, coord_t x, coord_t y, coord_t radius1, coord_t radius2)
Draw two filled circles with the same centre in the window.
GWIN 3D module header file.
Type for a 2D point on the screen.
Definition: gdisp.h:51
coord_t width
Definition: gwin.h:49
GHandle gwinGWindowCreate(GDisplay *g, GWindowObject *pgw, const GWindowInit *pInit)
Create a basic window.
void gwinDrawEllipse(GHandle gh, coord_t x, coord_t y, coord_t a, coord_t b)
Draw an ellipse.
The structure for an image.
Definition: gdisp_image.h:59
The Virtual Method Table for a GWIN window.
Definition: gwin_class.h:55
GWIN image widget header file.
A window object structure.
Definition: gwin.h:40
COLOR_TYPE color_t
The color type definition.
Definition: gdisp_colors.h:412
coord_t width
Definition: gwin.h:78
color_t color
Definition: gwin.h:51
const char * gwinGetClassName(GHandle gh)
Get the real class name of the GHandle.
void gwinSetWindowManager(struct GWindowManager *gwm)
Set the window manager for the GWIN system.
uint16_t gdispImageError
An image error code.
Definition: gdisp_image.h:37
void gwinSetDefaultBgColor(color_t bgclr)
Set the default background color for all new GWIN windows.
color_t gwinGetPixelColor(GHandle gh, coord_t x, coord_t y)
Get the color of a pixel in the window.
color_t pixel_t
The pixel format.
Definition: gdisp.h:226
void gwinMove(GHandle gh, coord_t x, coord_t y)
Move a window.
GWindowMinMax gwinGetMinMax(GHandle gh)
Get the Minimized/Maximized state of a window.
void gwinFillConvexPoly(GHandle gh, coord_t tx, coord_t ty, const point *pntarray, unsigned cnt)
Fill a convex polygon.