The official µGFX library repository.

gwin_widget.h 13KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452
  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. * @file src/gwin/gwin_widget.h
  9. * @brief GWIN Widgets header file.
  10. *
  11. * @defgroup Widget Widget
  12. * @ingroup Widgets
  13. *
  14. * @brief The basic widget implementation (base class).
  15. *
  16. * @details A widget is a Window that supports interacting with the user
  17. * via an input device such as a mouse or toggle buttons. It is the
  18. * base class for widgets such as buttons and sliders.
  19. *
  20. * @pre GFX_USE_GWIN and GWIN_NEED_WIDGET must be set to TRUE in your gfxconf.h
  21. * @{
  22. */
  23. #ifndef _GWIDGET_H
  24. #define _GWIDGET_H
  25. /* This file is included within "src/gwin/gwin.h" */
  26. // Forward definition
  27. struct GWidgetObject;
  28. /**
  29. * @brief The GColorSet structure
  30. * @{
  31. */
  32. typedef struct GColorSet {
  33. color_t text; /**< The text color */
  34. color_t edge; /**< The edge color */
  35. color_t fill; /**< The fill color */
  36. color_t progress; /**< The color of progress bars */
  37. } GColorSet;
  38. /** @} */
  39. /**
  40. * @brief The GWidgetStyle structure
  41. * @details A GWidgetStyle is a set of colors that together form a "style".
  42. * These colors should not be confused with the GWindow foreground
  43. * and background colors which are used for drawing operations.
  44. * @{
  45. */
  46. typedef struct GWidgetStyle {
  47. color_t background; /**< The window background color */
  48. color_t focus; /**< The color when a widget is focused */
  49. GColorSet enabled; /**< The colors when enabled */
  50. GColorSet disabled; /**< The colors when disabled */
  51. GColorSet pressed; /**< The colors when pressed */
  52. } GWidgetStyle;
  53. /** @} */
  54. /**
  55. * @brief We define a couple of GWidgetStyle's that you can use in your
  56. * application. The Black style is the default style if you don't
  57. * specify one.
  58. * @note BlackWidgetStyle means that it is designed for a Black background.
  59. * Similarly WhiteWidgetStyle is designed for a White background.
  60. * @{
  61. */
  62. extern const GWidgetStyle BlackWidgetStyle;
  63. extern const GWidgetStyle WhiteWidgetStyle;
  64. /** @} */
  65. /**
  66. * @brief Defines a custom drawing function for a widget
  67. */
  68. typedef void (*CustomWidgetDrawFunction)(struct GWidgetObject *gw, void *param);
  69. /**
  70. * @brief Defines a the type of a tag on a widget
  71. */
  72. typedef uint16_t WidgetTag;
  73. /**
  74. * @brief The structure to initialise a widget.
  75. *
  76. * @note Some widgets may have extra parameters.
  77. * @note If you create this structure on the stack, you should always memset
  78. * it to all zero's first in case a future version of the software
  79. * add's extra fields. Alternatively you can use @p gwinWidgetClearInit()
  80. * to clear it.
  81. * @note The text element must be static string (not stack allocated). If you want to use
  82. * a dynamic string (eg a stack allocated string) use NULL for this member and then call
  83. * @p gwinSetText() with useAlloc set to TRUE.
  84. *
  85. * @{
  86. */
  87. typedef struct GWidgetInit {
  88. GWindowInit g; /**< The GWIN initializer */
  89. const char * text; /**< The initial text */
  90. CustomWidgetDrawFunction customDraw; /**< A custom draw function - use NULL for the standard */
  91. void * customParam; /**< A parameter for the custom draw function (default = NULL) */
  92. const GWidgetStyle * customStyle; /**< A custom style to use - use NULL for the default style */
  93. #if GWIN_WIDGET_TAGS || defined(__DOXYGEN__)
  94. WidgetTag tag; /**< The tag to associate with the widget */
  95. #endif
  96. } GWidgetInit;
  97. /** @} */
  98. /**
  99. * @brief The GWIN Widget structure
  100. * @note A widget is a GWIN window that accepts user input.
  101. * It also has a number of other properties such as its ability
  102. * to redraw itself (a widget maintains drawing state).
  103. * @note Do not access the members directly. Treat it as a black-box and use the method functions.
  104. *
  105. * @{
  106. */
  107. typedef struct GWidgetObject {
  108. GWindowObject g; /**< This is still a GWIN */
  109. const char * text; /**< The widget text */
  110. CustomWidgetDrawFunction fnDraw; /**< The current draw function */
  111. void * fnParam; /**< A parameter for the current draw function */
  112. const GWidgetStyle * pstyle; /**< The current widget style colors */
  113. #if GWIN_WIDGET_TAGS || defined(__DOXYGEN__)
  114. WidgetTag tag; /**< The widget tag */
  115. #endif
  116. } GWidgetObject;
  117. /** @} */
  118. /**
  119. * A comment/rant on the above structure:
  120. * We would really like the GWindowObject member to be anonymous. While this is
  121. * allowed under the C11, C99, GNU and various other standards which have been
  122. * around forever - compiler support often requires special flags e.g
  123. * gcc requires the -fms-extensions flag (no wonder the language and compilers have
  124. * not really progressed in 30 years). As portability is a key requirement
  125. * we unfortunately won't use this useful feature in case we get a compiler that
  126. * won't support it even with special flags.
  127. */
  128. /**
  129. * @brief A Generic GWIN Event
  130. * @note All gwin windows when sending events will either use this structure or a
  131. * structure that is 100% compatible except that it may also have extra fields.
  132. * @note There are currently no GEventGWin listening flags - use 0 as the flags to @p gwinAttachListener()
  133. *
  134. * @{
  135. */
  136. typedef struct GEventGWin {
  137. GEventType type; /**< The type of this event */
  138. GHandle gwin; /**< The gwin window handle */
  139. #if GWIN_NEED_WIDGET && GWIN_WIDGET_TAGS
  140. WidgetTag tag; /**< The tag (if applicable) */
  141. #endif
  142. } GEventGWin;
  143. /** @} */
  144. /**
  145. * @brief The list of predefined GWIN events.
  146. * @note The definition of an event type does not mean it is always sent. For example,
  147. * close events are sent by Frame windows but by little else. They are normally
  148. * only sent if there is a specific reason that the event should be sent.
  149. * @{
  150. */
  151. #define GEVENT_GWIN_OPEN (GEVENT_GWIN_FIRST+0x00)
  152. #define GEVENT_GWIN_CLOSE (GEVENT_GWIN_FIRST+0x01)
  153. #define GEVENT_GWIN_RESIZE (GEVENT_GWIN_FIRST+0x02)
  154. #define GEVENT_GWIN_CTRL_FIRST (GEVENT_GWIN_FIRST+0x40)
  155. /** @} */
  156. #ifdef __cplusplus
  157. extern "C" {
  158. #endif
  159. /**
  160. * @brief Clear a GWidgetInit structure to all zero's
  161. * @note This function is provided just to prevent problems
  162. * on operating systems where using memset() causes issues
  163. * in the users application.
  164. *
  165. * @param[in] pwi The GWidgetInit structure to clear
  166. *
  167. * @api
  168. */
  169. void gwinWidgetClearInit(GWidgetInit *pwi);
  170. /**
  171. * @brief Set the default style for widgets created hereafter.
  172. *
  173. * @param[in] pstyle The default style. Passing NULL uses the system compiled style.
  174. * @param[in] updateAll If TRUE then all existing widgets that are using the current default style
  175. * will be updated to use this new style. Widgets that have custom styles different
  176. * from the default style will not be updated.
  177. *
  178. * @note The style must be allocated statically (not on the stack) as only the pointer is stored.
  179. *
  180. * @api
  181. */
  182. void gwinSetDefaultStyle(const GWidgetStyle *pstyle, bool_t updateAll);
  183. /**
  184. * @brief Get the current default style.
  185. *
  186. * @return The current default style.
  187. *
  188. * @api
  189. */
  190. const GWidgetStyle *gwinGetDefaultStyle(void);
  191. /**
  192. * @brief Set the text of a widget.
  193. *
  194. * @param[in] gh The widget handle
  195. * @param[in] text The text to set. This must be a constant string unless useAlloc is set.
  196. * @param[in] useAlloc If TRUE the string specified will be copied into dynamically allocated memory.
  197. *
  198. * @note The widget is automatically redrawn
  199. * @note Non-widgets will ignore this call.
  200. *
  201. * @api
  202. */
  203. void gwinSetText(GHandle gh, const char *text, bool_t useAlloc);
  204. /**
  205. * @brief Get the text of a widget.
  206. * @return The widget text or NULL if it isn't a widget
  207. *
  208. * @param[in] gh The widget handle
  209. *
  210. * @api
  211. */
  212. const char *gwinGetText(GHandle gh);
  213. #if (GFX_USE_GFILE && GFILE_NEED_PRINTG && GFILE_NEED_STRINGS) || defined(__DOXYGEN__)
  214. /**
  215. * @brief Set the text of a widget using a printf style format.
  216. * @pre GFX_USE_GFILE, GFILE_NEED_PRINTG and GFILE_NEED_STRINGS must all be TRUE
  217. *
  218. * @param[in] gh The widget handle
  219. * @param[in] fmt The format string using a printf/g syntax. See @p vsnprintg()
  220. * @param[in] ... The printg paramters.
  221. *
  222. * @note The widget is automatically redrawn
  223. * @note Non-widgets will ignore this call.
  224. * @note The memory for the text is always allocated by this function.
  225. *
  226. * @api
  227. */
  228. void gwinPrintg(GHandle gh, const char * fmt,...);
  229. #endif
  230. /**
  231. * @brief Check whether a handles is a widget handle or not
  232. *
  233. * @param[in] gh The handle to check.
  234. *
  235. * @return TRUE if the passed handle is a widget handle. FALSE otherwise.
  236. *
  237. * @api
  238. */
  239. bool_t gwinIsWidget(GHandle gh);
  240. #if GWIN_WIDGET_TAGS || defined(__DOXYGEN__)
  241. /**
  242. * @brief Set the tag of a widget.
  243. *
  244. * @param[in] gh The widget handle
  245. * @param[in] tag The tag to set.
  246. *
  247. * @note Non-widgets will ignore this call.
  248. *
  249. * @pre Requires GWIN_WIDGET_TAGS to be TRUE
  250. *
  251. * @api
  252. */
  253. void gwinSetTag(GHandle gh, WidgetTag tag);
  254. /**
  255. * @brief Get the tag of a widget.
  256. * @return The widget tag value (or 0 if it is not a widget)
  257. *
  258. * @param[in] gh The widget handle
  259. *
  260. * @pre Requires GWIN_WIDGET_TAGS to be TRUE
  261. *
  262. * @api
  263. */
  264. WidgetTag gwinGetTag(GHandle gh);
  265. #endif
  266. /**
  267. * @brief Set the style of a widget.
  268. *
  269. * @param[in] gh The widget handle
  270. * @param[in] pstyle The style to set. This must be a static structure (not allocated on a transient stack).
  271. * Use NULL to reset to the default style.
  272. *
  273. * @note The widget is automatically redrawn
  274. * @note Non-widgets will ignore this call.
  275. *
  276. * @api
  277. */
  278. void gwinSetStyle(GHandle gh, const GWidgetStyle *pstyle);
  279. /**
  280. * @brief Get the style of a widget.
  281. * @return The widget style or NULL if it isn't a widget
  282. *
  283. * @param[in] gh The widget handle
  284. *
  285. * @api
  286. */
  287. const GWidgetStyle *gwinGetStyle(GHandle gh);
  288. /**
  289. * @brief Set the routine to perform a custom widget drawing.
  290. *
  291. * @param[in] gh The widget handle
  292. * @param[in] fn The function to use to draw the widget
  293. * @param[in] param A parameter to pass to the widget drawing function
  294. *
  295. * @note The widget is not automatically redrawn. Call @p gwinDraw() to redraw the widget.
  296. * @note Non-widgets will ignore this call.
  297. *
  298. * @api
  299. */
  300. void gwinSetCustomDraw(GHandle gh, CustomWidgetDrawFunction fn, void *param);
  301. /**
  302. * @brief Attach a Listener to listen for widget events
  303. * @return TRUE on success
  304. *
  305. * @param[in] pl The listener
  306. *
  307. * @api
  308. */
  309. bool_t gwinAttachListener(GListener *pl);
  310. #if (GFX_USE_GINPUT && GINPUT_NEED_MOUSE) || defined(__DOXYGEN__)
  311. bool_t DEPRECATED("This call can now be removed. Attaching the mouse to GWIN is now automatic.") gwinAttachMouse(uint16_t instance);
  312. #endif
  313. #if (GFX_USE_GINPUT && GINPUT_NEED_TOGGLE) || defined(__DOXYGEN__)
  314. /**
  315. * @brief Attach a toggle to a widget
  316. * @return TRUE on success
  317. *
  318. * @param[in] gh The widget handle
  319. * @param[in] role The function the toggle will perform for the widget
  320. * @param[in] instance The toggle instance
  321. *
  322. * @note See the documentation on the specific widget to see the possible
  323. * values for the role parameter. If it is out of range, this function
  324. * will return FALSE
  325. *
  326. * @api
  327. */
  328. bool_t gwinAttachToggle(GHandle gh, uint16_t role, uint16_t instance);
  329. #endif
  330. #if (GFX_USE_GINPUT && GINPUT_NEED_DIAL) || defined(__DOXYGEN__)
  331. /**
  332. * @brief Attach a toggle to a widget
  333. * @return TRUE on success
  334. *
  335. * @param[in] gh The widget handle
  336. * @param[in] role The function the dial will perform for the widget
  337. * @param[in] instance The dial instance
  338. *
  339. * @note See the documentation on the specific widget to see the possible
  340. * values for the role parameter. If it is out of range, this function
  341. * will return FALSE
  342. *
  343. * @api
  344. */
  345. bool_t gwinAttachDial(GHandle gh, uint16_t role, uint16_t instance);
  346. #endif
  347. #if (GFX_USE_GINPUT && GINPUT_NEED_KEYBOARD) || GWIN_NEED_KEYBOARD || defined(__DOXYGEN__)
  348. /**
  349. * @brief Set the keyboard focus to a specific window
  350. * @return Returns TRUE if the focus could be set to that window
  351. *
  352. * @param[in] gh The window
  353. *
  354. * @note Passing NULL will remove the focus from any window.
  355. * @note Only visible enabled widgets are capable of getting the focus.
  356. *
  357. * @api
  358. */
  359. bool_t gwinSetFocus(GHandle gh);
  360. /**
  361. * @brief Get the widget that is currently in focus
  362. *
  363. * @details The widget that is currently in focus is the widget that
  364. * receives mouse and keyboard events.
  365. *
  366. * @return The handle of the widget that is currently in focus. May be NULL.
  367. *
  368. * @api
  369. */
  370. GHandle gwinGetFocus(void);
  371. #else
  372. #define gwinGetFocus() (0)
  373. #define gwinSetFocus(gh) (FALSE)
  374. #endif
  375. #ifdef __cplusplus
  376. }
  377. #endif
  378. /* Include extra widget types */
  379. #if GWIN_NEED_BUTTON || defined(__DOXYGEN__)
  380. #include "gwin_button.h"
  381. #endif
  382. #if GWIN_NEED_SLIDER || defined(__DOXYGEN__)
  383. #include "gwin_slider.h"
  384. #endif
  385. #if GWIN_NEED_CHECKBOX || defined(__DOXYGEN__)
  386. #include "gwin_checkbox.h"
  387. #endif
  388. #if GWIN_NEED_RADIO || defined(__DOXYGEN__)
  389. #include "gwin_radio.h"
  390. #endif
  391. #if GWIN_NEED_LABEL || defined(__DOXYGEN__)
  392. #include "gwin_label.h"
  393. #endif
  394. #if GWIN_NEED_LIST || defined(__DOXYGEN__)
  395. #include "gwin_list.h"
  396. #endif
  397. #if GWIN_NEED_PROGRESSBAR || defined(__DOXYGEN__)
  398. #include "gwin_progressbar.h"
  399. #endif
  400. #if GWIN_NEED_KEYBOARD || defined(__DOXYGEN__)
  401. #include "gwin_keyboard.h"
  402. #endif
  403. #if GWIN_NEED_TEXTEDIT || defined(__DOXYGEN__)
  404. #include "gwin_textedit.h"
  405. #endif
  406. #endif /* _GWIDGET_H */
  407. /** @} */