version 2.8
gwin_label.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_label.h
10  * @brief GWIN label widget header file
11  *
12  * @defgroup Label Label
13  * @ingroup Widgets
14  *
15  * @brief Simple label widget.
16  *
17  * @details Setting the dimensions of the widget to 0 will automatically
18  * set the labels dimensions to fit the entire text. Note that the
19  * dimensions of the label will change every time the text is changed
20  * through gwinSetText().
21  *
22  * @pre GFX_USE_GDISP must be set to TRUE in your gfxconf.h
23  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
24  * @pre GDISP_NEED_TEXT must be set to TRUE in your gfxconf.h
25  * @pre GWIN_NEED_LABEL must be set to TRUE in your gfxconf.h
26  * @pre The fonts you want to use must be enabled in your gfxconf.h
27  *
28  * @{
29  */
30 
31 #ifndef _GWIN_LABEL_H
32 #define _GWIN_LABEL_H
33 
34 // This file is included within "src/gwin/gwin_widget.h"
35 
36 /**
37  * @brief The internal label flags
38  * @note Used only for writing a custom draw routine.
39  * @{
40  */
41 #define GLABEL_FLG_WAUTO 0x01
42 #define GLABEL_FLG_HAUTO 0x02
43 #define GLABEL_FLG_BORDER 0x04
44 /** @} */
45 
46 // An label window
47 typedef struct GLabelObject {
48  GWidgetObject w;
49 
50  #if GWIN_LABEL_ATTRIBUTE
51  coord_t tab;
52  const char* attr;
53  #endif
54 } GLabelObject;
55 
56 #ifdef __cplusplus
57 extern "C" {
58 #endif
59 
60 /**
61  * @brief Create a label widget.
62  * @details A label widget is a simple window which has a static text.
63  *
64  * @param[in] g The GDisplay to display this window on
65  * @param[in] widget The label structure to initialise. If this is NULL, the structure is dynamically allocated.
66  * @param[in] pInit The initialisation parameters to use.
67  *
68  * @return NULL if there is no resultat drawing area, otherwise the widget handle.
69  *
70  * @api
71  */
72 GHandle gwinGLabelCreate(GDisplay *g, GLabelObject *widget, GWidgetInit *pInit);
73 #define gwinLabelCreate(w, pInit) gwinGLabelCreate(GDISP, w, pInit)
74 
75 /**
76  * @brief Border settings for the default rendering routine
77  *
78  * @param[in] gh The widget handle (must be a label handle)
79  * @param[in] border Shall a border be rendered?
80  *
81  * @api
82  */
83 void gwinLabelSetBorder(GHandle gh, bool_t border);
84 
85 #if GWIN_LABEL_ATTRIBUTE || defined(__DOXYGEN__)
86  /**
87  * @brief Add an text attribute in front of the normal label text
88  * @details Often you want to display a text like this:
89  * Current IP: 192.168.1.42
90  * In that case, the actual IP will be variable, the text in front of it
91  * always remains the same. The static text is called the attribute and can be
92  * set using this function.
93  * Furthermore, the tab can be set in order to vertically align multiple labels.
94  * Please check out the website for further explanation, illustraions and usage
95  * examples.
96  *
97  * @note The attribute text is not copied into private memory and so it
98  * must be a constant string, not one allocated in a stack buffer.
99  * @note Use of this construct is discouraged. The appropriate way is to
100  * create two labels - one for the static text and one for the
101  * dynamic text.
102  *
103  * @param[in] gh The widget handle (must be a label handle)
104  * @param[in] tab The distance of the label text from the left widget edge
105  * @param[in] attr The attribute to be displayed
106  *
107  * @api
108  */
109  void gwinLabelSetAttribute(GHandle gh, coord_t tab, const char* attr);
110 #endif
111 
112 /**
113  * @defgroup Renderings_Label Renderings
114  *
115  * @brief Built-in rendering functions for the label widget.
116  *
117  * @details These function may be passed to @p gwinSetCustomDraw() to get different label drawing styles.
118  *
119  * @note In your custom label drawing function you may optionally call these
120  * standard functions and then draw your extra details on top.
121  * @note The built-in functions below ignore the param parameter.
122  * @note These custom drawing routines don't have to worry about setting clipping as the framework
123  * sets clipping to the object window prior to calling these routines.
124  *
125  * @{
126  */
127 
128 /**
129  * @brief Renders a label with the text left jestified.
130  *
131  * @note This is the default rendering function.
132  *
133  * @param[in] gw The widget object (must be a label object)
134  * @param[in] param A parameter passed in from the user. Ignored by this function.
135  *
136  * @api
137  */
138 void gwinLabelDrawJustifiedLeft(GWidgetObject *gw, void *param);
139 
140 /**
141  * @brief Renders a label with the text right jestified.
142  *
143  * @param[in] gw The widget object (must be a label object)
144  * @param[in] param A parameter passed in from the user. Ignored by this function.
145  *
146  * @api
147  */
148 void gwinLabelDrawJustifiedRight(GWidgetObject *gw, void *param);
149 
150 /**
151  * @brief Renders a label with the text center jestified.
152  *
153  * @param[in] gw The widget object (must be a label object)
154  * @param[in] param A parameter passed in from the user. Ignored by this function.
155  *
156  * @api
157  */
158 void gwinLabelDrawJustifiedCenter(GWidgetObject *gw, void *param);
159 
160 /** @} */
161 
162 #ifdef __cplusplus
163 }
164 #endif
165 
166 #endif // _GWIN_LABEL_H
167 /** @} */
void gwinLabelDrawJustifiedLeft(GWidgetObject *gw, void *param)
Renders a label with the text left jestified.
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
void gwinLabelDrawJustifiedRight(GWidgetObject *gw, void *param)
Renders a label with the text right jestified.
The structure to initialise a widget.
Definition: gwin_widget.h:97
GHandle gwinGLabelCreate(GDisplay *g, GLabelObject *widget, GWidgetInit *pInit)
Create a label widget.
void gwinLabelSetBorder(GHandle gh, bool_t border)
Border settings for the default rendering routine.
void gwinLabelSetAttribute(GHandle gh, coord_t tab, const char *attr)
Add an text attribute in front of the normal label text.
The GWIN Widget structure.
Definition: gwin_widget.h:118
A window object structure.
Definition: gwin.h:40
void gwinLabelDrawJustifiedCenter(GWidgetObject *gw, void *param)
Renders a label with the text center jestified.