2 * @defgroup Label Label
4 * @image html img/widget/label/preview-00.png
5 * @image latex img/widget/label/preview-00.eps
7 * @brief Widget to display text, with simple html-like markup.
9 * The Label widget @b doesn't allow text to overflow its boundaries, if the
10 * text doesn't fit the geometry of the label it will be ellipsized or be
11 * cut. Elementary provides several styles for this widget:
12 * @li default - No animation
13 * @li marker - Centers the text in the label and make it bold by default
14 * @li slide_long - The entire text appears from the right of the screen and
15 * slides until it disappears in the left of the screen(reappering on the
17 * @li slide_short - The text appears in the left of the label and slides to
18 * the right to show the overflow. When all of the text has been shown the
20 * @li slide_bounce - The text appears in the left of the label and slides to
21 * the right to show the overflow. When all of the text has been shown the
22 * animation reverses, moving the text to the left.
24 * Custom themes can of course invent new markup tags and style them any way
27 * The following signals may be emitted by the label widget:
28 * @li "language,changed": The program's language changed.
30 * See @ref tutorial_label for a demonstration of how to use a label widget.
35 * @brief Add a new label to the parent
37 * @param parent The parent object
38 * @return The new object or NULL if it cannot be created
40 EAPI Evas_Object *elm_label_add(Evas_Object *parent);
43 * @brief Set the wrapping behavior of the label
45 * @param obj The label object
46 * @param wrap To wrap text or not
48 * By default no wrapping is done. Possible values for @p wrap are:
49 * @li ELM_WRAP_NONE - No wrapping
50 * @li ELM_WRAP_CHAR - wrap between characters
51 * @li ELM_WRAP_WORD - wrap between words
52 * @li ELM_WRAP_MIXED - Word wrap, and if that fails, char wrap
54 EAPI void elm_label_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap);
57 * @brief Get the wrapping behavior of the label
59 * @param obj The label object
62 * @see elm_label_line_wrap_set()
64 EAPI Elm_Wrap_Type elm_label_line_wrap_get(const Evas_Object *obj);
67 * @brief Set wrap width of the label
69 * @param obj The label object
70 * @param w The wrap width in pixels at a minimum where words need to wrap
72 * This function sets the maximum width size hint of the label.
74 * @warning This is only relevant if the label is inside a container.
76 EAPI void elm_label_wrap_width_set(Evas_Object *obj, Evas_Coord w);
79 * @brief Get wrap width of the label
81 * @param obj The label object
82 * @return The wrap width in pixels at a minimum where words need to wrap
84 * @see elm_label_wrap_width_set()
86 EAPI Evas_Coord elm_label_wrap_width_get(const Evas_Object *obj);
89 * @brief Set wrap height of the label
91 * @param obj The label object
92 * @param h The wrap height in pixels at a minimum where words need to wrap
94 * This function sets the maximum height size hint of the label.
96 * @warning This is only relevant if the label is inside a container.
98 EAPI void elm_label_wrap_height_set(Evas_Object *obj, Evas_Coord h);
101 * @brief get wrap width of the label
103 * @param obj The label object
104 * @return The wrap height in pixels at a minimum where words need to wrap
106 EAPI Evas_Coord elm_label_wrap_height_get(const Evas_Object *obj);
109 * @brief Set the font size on the label object.
111 * @param obj The label object
112 * @param size font size
114 * @warning NEVER use this. It is for hyper-special cases only. use styles
115 * instead. e.g. "default", "marker", "slide_long" etc.
117 EAPI void elm_label_fontsize_set(Evas_Object *obj, int fontsize);
120 * @brief Set the text color on the label object
122 * @param obj The label object
123 * @param r Red property background color of The label object
124 * @param g Green property background color of The label object
125 * @param b Blue property background color of The label object
126 * @param a Alpha property background color of The label object
128 * @warning NEVER use this. It is for hyper-special cases only. use styles
129 * instead. e.g. "default", "marker", "slide_long" etc.
131 EAPI void elm_label_text_color_set(Evas_Object *obj, unsigned int r, unsigned int g, unsigned int b, unsigned int a);
134 * @brief Set the text align on the label object
136 * @param obj The label object
137 * @param align align mode ("left", "center", "right")
139 * @warning NEVER use this. It is for hyper-special cases only. use styles
140 * instead. e.g. "default", "marker", "slide_long" etc.
142 EAPI void elm_label_text_align_set(Evas_Object *obj, const char *alignmode);
145 * @brief Set background color of the label
147 * @param obj The label object
148 * @param r Red property background color of The label object
149 * @param g Green property background color of The label object
150 * @param b Blue property background color of The label object
151 * @param a Alpha property background alpha of The label object
153 * @warning NEVER use this. It is for hyper-special cases only. use styles
154 * instead. e.g. "default", "marker", "slide_long" etc.
156 EAPI void elm_label_background_color_set(Evas_Object *obj, unsigned int r, unsigned int g, unsigned int b, unsigned int a);
159 * @brief Set the ellipsis behavior of the label
161 * @param obj The label object
162 * @param ellipsis To ellipsis text or not
164 * If set to true and the text doesn't fit in the label an ellipsis("...")
165 * will be shown at the end of the widget.
167 * @warning This doesn't work with slide(elm_label_slide_set()) or if the
168 * choosen wrap method was ELM_WRAP_WORD.
170 EAPI void elm_label_ellipsis_set(Evas_Object *obj, Eina_Bool ellipsis);
173 * @brief Set the text slide of the label
175 * @param obj The label object
176 * @param slide To start slide or stop
178 * If set to true, the text of the label will slide/scroll through the length of
181 * @warning This only works with the themes "slide_short", "slide_long" and
184 EAPI void elm_label_slide_set(Evas_Object *obj, Eina_Bool slide);
187 * @brief Get the text slide mode of the label
189 * @param obj The label object
190 * @return slide slide mode value
192 * @see elm_label_slide_set()
194 EAPI Eina_Bool elm_label_slide_get(Evas_Object *obj);
197 * @brief Set the slide duration(speed) of the label
199 * @param obj The label object
200 * @return The duration in seconds in moving text from slide begin position
201 * to slide end position
203 EAPI void elm_label_slide_duration_set(Evas_Object *obj, double duration);
206 * @brief Get the slide duration(speed) of the label
208 * @param obj The label object
209 * @return The duration time in moving text from slide begin position to slide end position
211 * @see elm_label_slide_duration_set()
213 EAPI double elm_label_slide_duration_get(Evas_Object *obj);