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