version 2.8
gwin_tabset.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_tabset.h
10  * @brief GWIN Graphic window subsystem header file.
11  *
12  * @defgroup Tabset Tabset
13  * @ingroup Containers
14  *
15  * @brief Tabwidget to implement different "Tabs" or "Pages". Used to structure menus.
16  *
17  * @details A tabset is a set of tabs that control visibility of a number of pages of widgets.
18  * Note: Although the tabset is implemented as a container - you don't put your controls
19  * directly on the tabset. Instead you create a page and put your widgets on the page.
20  *
21  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
22  * @pre GWIN_NEED_TABSET must be set to TRUE in your gfxconf.h
23  * @{
24  */
25 
26 #ifndef _GWIN_TABSET_H
27 #define _GWIN_TABSET_H
28 
29 /* This file is included from src/gwin/gwin_container.h */
30 
31 /**
32  * @brief The Event Type for a Tabset Event
33  */
34 #define GEVENT_GWIN_TABSET (GEVENT_GWIN_CTRL_FIRST+5)
35 
36 /**
37  * @brief A Tabset Event
38  * @note There are currently no GEventGWinTabset listening flags - use 0 as the flags to @p gwinAttachListener()
39  */
40 typedef struct GEventGWinTabset {
41  GEventType type; // The type of this event (GEVENT_GWIN_TABSET)
42  GHandle gwin; // The tabset window handle
43  #if GWIN_NEED_WIDGET && GWIN_WIDGET_TAGS
44  WidgetTag tag; // The tag of the tabset
45  #endif
46  // Above are the generic widget event elements, below the tabset specific elements
47  GHandle ghPage; // The tabpage window handle that has been selected
48  int nPage; // The page number (0 to n-1) that has been selected
50 
51 /**
52  * @brief Flags for gwinTabsetCreate()
53  * @{
54  */
55 #define GWIN_TABSET_BORDER 0x00000001 // Should the tab pages have a border?
56 /** @} */
57 
58 typedef struct GTabsetObject {
60  coord_t border_top;
61  } GTabsetObject;
62 
63 #ifdef __cplusplus
64 extern "C" {
65 #endif
66 
67 /**
68  * @brief Create a tabset widget
69  *
70  * @details This widget provides a set of tabs.
71  *
72  * @param[in] g The GDisplay to display this window on
73  * @param[in] fo The GTabsetObject structure to initialize. If this is NULL the structure is dynamically allocated.
74  * @param[in] pInit The initialization parameters
75  * @param[in] flags Some flags, see notes.
76  *
77  * @note Possible flags are: GWIN_TABSET_BORDER
78  *
79  * @return NULL if there is no resulting widget. A valid GHandle otherwise.
80  *
81  * @api
82  */
83 GHandle gwinGTabsetCreate(GDisplay *g, GTabsetObject *fo, GWidgetInit *pInit, uint32_t flags);
84 #define gwinTabsetCreate(fo, pInit, flags) gwinGTabsetCreate(GDISP, fo, pInit, flags);
85 
86 /**
87  * @brief Add a tab-page to the tabset
88  * @returns The GHandle of the tab-page container.
89  *
90  * @param[in] gh The tabset handle
91  * @param[in] title The text to set. This must be a constant string unless useAlloc is set.
92  * @param[in] useAlloc If TRUE the string specified will be copied into dynamically allocated memory.
93  *
94  * @api
95  */
96 GHandle gwinTabsetAddTab(GHandle gh, const char *title, bool_t useAlloc);
97 
98 /**
99  * @brief Delete a tab-page.
100  * @details Any widgets on the page will also be destroyed
101  *
102  * @param[in] gh The tab-page handle
103  *
104  * @note The index position of all tabs after this tab in the tabset are automatically renumbered.
105  *
106  * @api
107  */
108 #define gwinTabsetDeleteTab(gh) gwinDestroy(gh)
109 
110 /**
111  * @brief Count the number of tabs in the tabset
112  * @returns The number of tabs or zero if none exist.
113  *
114  * @param[in] gh The tabset handle
115  *
116  * @api
117  */
119 
120 /**
121  * @brief Get the GHandle of a tab based on its position
122  * @returns The GHandle of the tab-page container or NULL if that tab-page doesn't exist.
123  *
124  * @param[in] gh The tabset handle
125  * @param[in] index The tab-page handle to return (0 to number of pages - 1)
126  *
127  * @api
128  */
130 
131 /**
132  * @brief Get the GHandle of a tab based on its title
133  * @returns The GHandle of the tab-page container or NULL if that tab-page doesn't exist.
134  *
135  * @param[in] gh The tabset handle
136  * @param[in] title The title to search for
137  *
138  * @api
139  */
140 GHandle gwinTabsetGetTabByTitle(GHandle gh, const char *title);
141 
142 /**
143  * @brief Set the title of a tab-page.
144  *
145  * @param[in] gh The tab-page handle (NB: Use the page handle NOT the tabset handle)
146  * @param[in] title The text to set. This must be a constant string unless useAlloc is set.
147  * @param[in] useAlloc If TRUE the string specified will be copied into dynamically allocated memory.
148  *
149  * @note This function should be used to change the text associated with a tab-page
150  * rather than @p gwinSetText().
151  *
152  * @api
153  */
154 void gwinTabsetSetTitle(GHandle gh, const char *title, bool_t useAlloc);
155 
156 /**
157  * @brief Get the title of a tab-page.
158  * @return The title of the tab.
159  *
160  * @param[in] gh The tab-page handle (NB: Use the page handle NOT the tabset handle)
161  *
162  * @api
163  */
164 #define gwinTabsetGetTitle(gh) gwinGetText(gh)
165 
166 /**
167  * @brief Set the active tab in a tabset.
168  *
169  * @param[in] gh The tab-page handle (NB: Use the page handle NOT the tabset handle)
170  *
171  * @api
172  */
173 void gwinTabsetSetTab(GHandle gh);
174 
175 /**
176  * @defgroup Renderings_Tabset Renderings
177  *
178  * @brief Built-in rendering functions for the tabset widget.
179  *
180  * @details These function may be passed to @p gwinSetCustomDraw() to get different tabset drawing styles.
181  *
182  * @note In your custom tabset drawing function you may optionally call these
183  * standard functions and then draw your extra details on top.
184  * @note These custom drawing routines don't have to worry about setting clipping as the framework
185  * sets clipping to the object window prior to calling these routines.
186  *
187  * @{
188  */
189 
190 /**
191  * @brief The default rendering function for the tabset widget.
192  *
193  * @details Fills the client area with the background color.
194  *
195  * @param[in] gw The widget object (must be a container object).
196  * @param[in] param A parameter passed in from the user. Ignored by this function.
197  *
198  * @api
199  */
200 void gwinTabsetDraw_Std(GWidgetObject *gw, void *param);
201 
202 /**
203  * @brief Renders the tabset but leaves the client area transparent.
204  *
205  * @details Will not fill the client area at all.
206  *
207  * @param[in] gw The widget object (must be a container object).
208  * @param[in] param A parameter passed in from the user. Ignored by this function.
209  *
210  * @api
211  */
212 void gwinTabsetDraw_Transparent(GWidgetObject *gw, void *param);
213 
214 #if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
215  /**
216  * @brief Renders the tabset and uses the specified image for the client area.
217  *
218  * @details The image will be tiled throghout the client area. Therefore, to archive the best looking result the
219  * supplied image needs to be of the same size as the client area size of the tabset widget (inner size).
220  *
221  * @param[in] gw The widget object (must be a tabset object).
222  * @param[in] param A parameter passed in from the user. Must be an image handle. See note below.
223  *
224  * @note The image must be already opened before calling @p gwinSetCustomDraw(). The handle is passed as the parameter
225  * to this function.
226  *
227  * @pre GDISP_NEED_IMAGE must be set to TRUE
228  *
229  * @api
230  */
231  void gwinTabsetDraw_Image(GWidgetObject *gw, void *param);
232 #endif /* GDISP_NEED_IMAGE */
233 /** @} */
234 
235 #ifdef __cplusplus
236 }
237 #endif
238 
239 #endif /* _GWIN_TABSET_H */
240 /** @} */
241 
struct GEventGWinTabset GEventGWinTabset
A Tabset Event.
void gwinTabsetDraw_Image(GWidgetObject *gw, void *param)
Renders the tabset and uses the specified image for the client area.
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
GHandle gwinTabsetAddTab(GHandle gh, const char *title, bool_t useAlloc)
Add a tab-page to the tabset.
A Tabset Event.
Definition: gwin_tabset.h:40
The GWIN Widget structure.
Definition: gwin_widget.h:118
void gwinTabsetDraw_Transparent(GWidgetObject *gw, void *param)
Renders the tabset but leaves the client area transparent.
GHandle gwinTabsetGetTabByTitle(GHandle gh, const char *title)
Get the GHandle of a tab based on its title.
GHandle gwinGTabsetCreate(GDisplay *g, GTabsetObject *fo, GWidgetInit *pInit, uint32_t flags)
Create a tabset widget.
int gwinTabsetCountTabs(GHandle gh)
Count the number of tabs in the tabset.
GHandle gwinTabsetGetTabByIndex(GHandle gh, int index)
Get the GHandle of a tab based on its position.
uint16_t WidgetTag
Defines a the type of a tag on a widget.
Definition: gwin_widget.h:81
void gwinTabsetSetTab(GHandle gh)
Set the active tab in a tabset.
A window object structure.
Definition: gwin.h:40
void gwinTabsetDraw_Std(GWidgetObject *gw, void *param)
The default rendering function for the tabset widget.
void gwinTabsetSetTitle(GHandle gh, const char *title, bool_t useAlloc)
Set the title of a tab-page.