The official µGFX library repository.

gwin_container.h 5.7KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199
  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_container.h
  9. *
  10. * @defgroup Container Container
  11. * @ingroup Containers
  12. *
  13. * @brief Basic container.
  14. *
  15. * @details A Container is a GWindow that supports child windows. It is also
  16. * a widget in its own right and therefore can accept user input directly.
  17. *
  18. * @pre GFX_USE_GWIN and GWIN_NEED_CONTAINERS must be set to TRUE in your gfxconf.h
  19. * @{
  20. */
  21. #ifndef _GCONTAINER_H
  22. #define _GCONTAINER_H
  23. /* This file is included within "src/gwin/gwin.h" */
  24. /**
  25. * @brief The GWIN Container structure
  26. * @note A container is a GWIN widget that can have children.
  27. * @note Do not access the members directly. Treat it as a black-box and use the method functions.
  28. *
  29. * @{
  30. */
  31. typedef GWidgetObject GContainerObject;
  32. /** @} */
  33. /**
  34. * A comment/rant on the above structure:
  35. * We would really like the GWidgetObject member to be anonymous. While this is
  36. * allowed under the C11, C99, GNU and various other standards which have been
  37. * around forever - compiler support often requires special flags e.g
  38. * gcc requires the -fms-extensions flag (no wonder the language and compilers have
  39. * not really progressed in 30 years). As portability is a key requirement
  40. * we unfortunately won't use this useful feature in case we get a compiler that
  41. * won't support it even with special flags.
  42. */
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46. /**
  47. * @brief Get the first child window
  48. *
  49. * @return The first child or NULL if are no children windows
  50. *
  51. * @param[in] gh The parent container or NULL to get the first top level window
  52. *
  53. * @api
  54. */
  55. GHandle gwinGetFirstChild(GHandle gh);
  56. /**
  57. * @brief Get the next child window in the z-order
  58. *
  59. * @return The next window or NULL if no more children
  60. *
  61. * @param[in] gh The window to obtain the next sibling of.
  62. *
  63. * @note This returns the next window under the current parent window.
  64. * Unlike @p gwinGetNextWindow() it will only return windows that
  65. * have the same parent as the supplied window.
  66. *
  67. * @api
  68. */
  69. GHandle gwinGetSibling(GHandle gh);
  70. /**
  71. * @brief Get the inner width of a container window
  72. *
  73. * @return The inner width of a container window or zero if this is not a container
  74. *
  75. * @param[in] gh The window
  76. *
  77. * @api
  78. */
  79. coord_t gwinGetInnerWidth(GHandle gh);
  80. /**
  81. * @brief Get the inner height of a container window
  82. *
  83. * @return The inner height of a container window or zero if this is not a container
  84. *
  85. * @param[in] gh The window
  86. *
  87. * @api
  88. */
  89. coord_t gwinGetInnerHeight(GHandle gh);
  90. /**
  91. * @brief Flags for gwinContainerCreate()
  92. * @{
  93. */
  94. #define GWIN_CONTAINER_BORDER 0x00000001
  95. /** @} */
  96. /**
  97. * @brief Create a simple container.
  98. * @return NULL if there is no resultant drawing area, otherwise a window handle.
  99. *
  100. * @param[in] g The GDisplay to display this window on
  101. * @param[in] gw The GContainerObject structure to initialise. If this is NULL the structure is dynamically allocated.
  102. * @param[in] pInit The initialisation parameters
  103. * @param[in] flags Some flags, see notes
  104. *
  105. * @api
  106. */
  107. GHandle gwinGContainerCreate(GDisplay *g, GContainerObject *gw, const GWidgetInit *pInit, uint32_t flags);
  108. #define gwinContainerCreate(gc, pInit, flags) gwinGContainerCreate(GDISP, gc, pInit, flags)
  109. /**
  110. * @defgroup Renderings_Container Renderings
  111. *
  112. * @brief Built-in rendering functions for the container widget.
  113. *
  114. * @details These function may be passed to @p gwinSetCustomDraw() to get different container drawing styles.
  115. *
  116. * @note In your custom container drawing function you may optionally call these
  117. * standard functions and then draw your extra details on top.
  118. * @note These custom drawing routines don't have to worry about setting clipping as the framework
  119. * sets clipping to the object window prior to calling these routines.
  120. *
  121. * @{
  122. */
  123. /**
  124. * @brief The default rendering function for the container widget.
  125. *
  126. * @details Fills the client area with the background color.
  127. *
  128. * @param[in] gw The widget object (must be a container object).
  129. * @param[in] param A parameter passed in from the user. Ignored by this function.
  130. *
  131. * @api
  132. */
  133. void gwinContainerDraw_Std(GWidgetObject *gw, void *param);
  134. /**
  135. * @brief Renders the container but leaves the client area transparent.
  136. *
  137. * @details Will not fill the client area at all.
  138. *
  139. * @param[in] gw The widget object (must be a container object).
  140. * @param[in] param A parameter passed in from the user. Ignored by this function.
  141. *
  142. * @api
  143. */
  144. void gwinContainerDraw_Transparent(GWidgetObject *gw, void *param);
  145. #if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
  146. /**
  147. * @brief Renders the container and uses the specified image for the client area.
  148. *
  149. * @details The image will be tiled throghout the client area. Therefore, to archive the best looking result the
  150. * supplied image needs to be of the same size as the client area size of the container widget (inner size).
  151. *
  152. * @param[in] gw The widget object (must be a container object).
  153. * @param[in] param A parameter passed in from the user. Must be an image handle. See note below.
  154. *
  155. * @note The image must be already opened before calling @p gwinSetCustomDraw(). The handle is passed as the parameter
  156. * to this function.
  157. *
  158. * @pre GDISP_NEED_IMAGE must be set to TRUE
  159. *
  160. * @api
  161. */
  162. void gwinContainerDraw_Image(GWidgetObject *gw, void *param);
  163. #endif /* GDISP_NEED_IMAGE */
  164. /** @} */
  165. #ifdef __cplusplus
  166. }
  167. #endif
  168. /* Include extra container types */
  169. #if GWIN_NEED_FRAME || defined(__DOXYGEN__)
  170. #include "gwin_frame.h"
  171. #endif
  172. #if GWIN_NEED_TABSET || defined(__DOXYGEN__)
  173. #include "gwin_tabset.h"
  174. #endif
  175. #endif /* _GCONTAINER_H */
  176. /** @} */