aboutsummaryrefslogtreecommitdiffstats
path: root/src/gwin/gwin_label.h
blob: 4a28eda4f30f8cfa4719c071ba0eaa5f39f0a15f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
/*
 * This file is subject to the terms of the GFX License. If a copy of
 * the license was not distributed with this file, you can obtain one at:
 *
 *              http://ugfx.io/license.html
 */

/**
 * @file	src/gwin/gwin_label.h
 * @brief	GWIN label widget header file
 *
 * @defgroup Label Label
 * @ingroup Widgets
 *
 * @brief		Simple label widget.
 *
 * @details		Setting the dimensions of the widget to 0 will automatically
 *				set the labels dimensions to fit the entire text. Note that the
 *				dimensions of the label will change every time the text is changed
 *				through gwinSetText().
 *
 * @pre			GFX_USE_GDISP must be set to GFXON in your gfxconf.h
 * @pre			GFX_USE_GWIN must be set to GFXON in your gfxconf.h
 * @pre			GDISP_NEED_TEXT must be set to GFXON in your gfxconf.h
 * @pre			GWIN_NEED_LABEL must be set to GFXON in your gfxconf.h
 * @pre			The fonts you want to use must be enabled in your gfxconf.h
 *
 * @{
 */

#ifndef _GWIN_LABEL_H
#define _GWIN_LABEL_H

// This file is included within "src/gwin/gwin_widget.h"

/**
 * @brief	The internal label flags
 * @note	Used only for writing a custom draw routine.
 * @{
 */
#define GLABEL_FLG_BORDER		0x01
/** @} */

// An label window
typedef struct GLabelObject {
	GWidgetObject	w;

	#if GWIN_LABEL_ATTRIBUTE
		gCoord         tab;
		const char*		attr;
	#endif
} GLabelObject;

/**
 * @brief				Create a label widget.
 * @details				A label widget is a simple window which has a static text.
 *
 * @param[in] g			The GDisplay to display this window on
 * @param[in] widget	The label structure to initialise. If this is NULL, the structure is dynamically allocated.
 * @param[in] pInit		The initialisation parameters to use.
 *
 * @return				NULL if there is no resultat drawing area, otherwise the widget handle.
 *
 * @api
 */
GHandle gwinGLabelCreate(GDisplay *g, GLabelObject *widget, GWidgetInit *pInit);
#define gwinLabelCreate(w, pInit)			gwinGLabelCreate(GDISP, w, pInit)

/**
 * @brief				Border settings for the default rendering routine
 *
 * @param[in] gh		The widget handle (must be a label handle)
 * @param[in] border	Shall a border be rendered?
 *
 * @api
 */
void gwinLabelSetBorder(GHandle gh, gBool border);

#if GWIN_LABEL_ATTRIBUTE || defined(__DOXYGEN__)
	/**
	 * @brief               Add an text attribute in front of the normal label text
	 * @details              Often you want to display a text like this:
	 *                          Current IP: 192.168.1.42
	 *                      In that case, the actual IP will be variable, the text in front of it
	 *                      always remains the same. The static text is called the attribute and can be
	 *                      set using this function.
	 *                      Furthermore, the tab can be set in order to vertically align multiple labels.
	 *                      Please check out the website for further explanation, illustraions and usage
	 *                      examples.
	 *
	 * @note                The attribute text is not copied into private memory and so it
	 *						must be a constant string, not one allocated in a stack buffer.
	 * @note				Use of this construct is discouraged. The appropriate way is to
	 *						create two labels - one for the static text and one for the
	 *						dynamic text.
	 *
	 * @param[in] gh        The widget handle (must be a label handle)
	 * @param[in] tab       The distance of the label text from the left widget edge
	 * @param[in] attr      The attribute to be displayed
	 *
	 * @api
	 */
	void gwinLabelSetAttribute(GHandle gh, gCoord tab, const char* attr);
#endif

/**
 * @defgroup Renderings_Label Renderings
 *
 * @brief				Built-in rendering functions for the label widget.
 *
 * @details				These function may be passed to @p gwinSetCustomDraw() to get different label drawing styles.
 *
 * @note				In your custom label drawing function you may optionally call these
 * 						standard functions and then draw your extra details on top.
 * @note				These custom drawing routines don't have to worry about setting clipping as the framework
 * 						sets clipping to the object window prior to calling these routines.
 *
 * @{
 */

/**
 * @brief				Renders a label with the text justified based on the parameter.
 *
 * @param[in] gw		The widget object (must be a label object)
 * @param[in] param		A parameter passed in from the user. Must be of type gJustify.
 *
 * @api
 */
void gwinLabelDrawJustified(GWidgetObject *gw, void *param);

/**
 * @brief				Renders a label with the text left jestified.
 *
 * @note				This is the default rendering function.
 *
 * @param[in] gw		The widget object (must be a label object)
 * @param[in] param		A parameter passed in from the user. Ignored by this function.
 *
 * @api
 */
void gwinLabelDrawJustifiedLeft(GWidgetObject *gw, void *param);

/**
 * @brief				Renders a label with the text right jestified.
 *
 * @param[in] gw		The widget object (must be a label object)
 * @param[in] param		A parameter passed in from the user. Ignored by this function.
 *
 * @api
 */
void gwinLabelDrawJustifiedRight(GWidgetObject *gw, void *param);

/**
 * @brief				Renders a label with the text center jestified.
 *
 * @param[in] gw		The widget object (must be a label object)
 * @param[in] param		A parameter passed in from the user. Ignored by this function.
 *
 * @api
 */
void gwinLabelDrawJustifiedCenter(GWidgetObject *gw, void *param);

/** @} */

#endif // _GWIN_LABEL_H
/** @} */