2 * @defgroup Label Label
5 * @image html label_inheritance_tree.png
6 * @image latex label_inheritance_tree.eps
8 * @image html img/widget/label/preview-00.png
9 * @image latex img/widget/label/preview-00.eps
11 * @brief Widget to display text, with simple html-like markup.
13 * The Label widget @b doesn't allow text to overflow its boundaries, if the
14 * text doesn't fit the geometry of the label it will be ellipsized or be
15 * cut. Elementary provides several styles for this widget:
16 * @li default - No animation
17 * @li marker - Centers the text in the label and makes it bold by default
18 * @li slide_long - The entire text appears from the right of the screen and
19 * slides until it disappears in the left of the screen(reappearing on the
21 * @li slide_short - The text appears in the left of the label and slides to
22 * the right to show the overflow. When all of the text has been shown the
24 * @li slide_bounce - The text appears in the left of the label and slides to
25 * the right to show the overflow. When all of the text has been shown the
26 * animation reverses, moving the text to the left.
28 * Custom themes can of course invent new markup tags and style them any way
31 * This widget inherits from the @ref Layout one, so that all the
32 * functions acting on it also work for label objects.
34 * This widget emits the following signals, besides the ones sent from
36 * @li @c "language,changed": The program's language changed.
37 * @li @c "slide,end": The slide is end.
39 * See @ref tutorial_label for a demonstration of how to use a label widget.
45 ELM_LABEL_SLIDE_MODE_NONE = 0, /**< no slide effect */
46 ELM_LABEL_SLIDE_MODE_AUTO, /**< slide only if the label area is bigger than the text width length */
47 ELM_LABEL_SLIDE_MODE_ALWAYS /**< slide always */
48 } Elm_Label_Slide_Mode;
52 * @brief Add a new label to the parent
54 * @param parent The parent object
55 * @return The new object or NULL if it cannot be created
59 EAPI Evas_Object *elm_label_add(Evas_Object *parent);
62 * @brief Set the wrapping behavior of the label
64 * @param obj The label object
65 * @param wrap To wrap text or not
67 * By default no wrapping is done. Possible values for @p wrap are:
68 * @li ELM_WRAP_NONE - No wrapping
69 * @li ELM_WRAP_CHAR - wrap between characters
70 * @li ELM_WRAP_WORD - wrap between words
71 * @li ELM_WRAP_MIXED - Word wrap, and if that fails, char wrap
75 EAPI void elm_label_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap);
78 * @brief Get the wrapping behavior of the label
80 * @param obj The label object
83 * @see elm_label_line_wrap_set()
87 EAPI Elm_Wrap_Type elm_label_line_wrap_get(const Evas_Object *obj);
90 * @brief Set wrap width of the label
92 * @param obj The label object
93 * @param w The wrap width in pixels at a minimum where words need to wrap
95 * This function sets the maximum width size hint of the label.
97 * @warning This is only relevant if the label is inside a container.
101 EAPI void elm_label_wrap_width_set(Evas_Object *obj, Evas_Coord w);
104 * @brief Get wrap width of the label
106 * @param obj The label object
107 * @return The wrap width in pixels at a minimum where words need to wrap
109 * @see elm_label_wrap_width_set()
113 EAPI Evas_Coord elm_label_wrap_width_get(const Evas_Object *obj);
116 * @brief Set the ellipsis behavior of the label
118 * @param obj The label object
119 * @param ellipsis To ellipsis text or not
121 * If set to true and the text doesn't fit in the label an ellipsis("...")
122 * will be shown at the end of the widget.
124 * @warning This doesn't work with slide(elm_label_slide_set()) or if the
125 * chosen wrap method was #ELM_WRAP_WORD.
129 EAPI void elm_label_ellipsis_set(Evas_Object *obj, Eina_Bool ellipsis);
132 * @brief Get the ellipsis behavior of the label
134 * @param obj The label object
135 * @return If true, an ellipsis will be shown at the end of the label area.
137 * @see elm_label_ellipsis_set()
141 EAPI Eina_Bool elm_label_ellipsis_get(const Evas_Object *obj);
144 * @brief Set the slide duration (speed) of the label
146 * @param obj The label object
147 * @param duration The duration in seconds in moving text from slide begin position
148 * to slide end position
152 EAPI void elm_label_slide_duration_set(Evas_Object *obj, double duration);
155 * @brief Get the slide duration(speed) of the label
157 * @param obj The label object
158 * @return The duration time in moving text from slide begin position to slide end position
160 * @see elm_label_slide_duration_set()
164 EAPI double elm_label_slide_duration_get(const Evas_Object *obj);
167 * @brief Set the slide mode of the label widget.
169 * @param obj The label object
170 * @param mode The slide mode
172 * elm_label_slide_mode_set() changes label slide mode.
173 * By default, slide mode is none. Possible values for @p mode are:
174 * @li ELM_LABEL_SLIDE_MODE_NONE - no slide effect
175 * @li ELM_LABEL_SLIDE_MODE_AUTO - slide only if the label area is bigger than
176 * the text width length
177 * @li ELM_LABEL_SLIDE_MODE_ALWAYS -slide always
179 * @warning ELM_LABEL_SLIDE_MODE_AUTO, ELM_LABEL_SLIDE_MODE_ALWAYS only work
180 * with the themes "slide_short", "slide_long" and "slide_bounce".
181 * @warning ELM_LABEL_SLIDE_MODE_AUTO, ELM_LABEL_SLIDE_MODE_ALWAYS don't work
182 * if the line wrap(elm_label_line_wrap_set()) or
183 * ellipsis(elm_label_ellipsis_set()) is set.
185 * @see elm_label_slide_mode_get().
189 EAPI void elm_label_slide_mode_set(Evas_Object *obj, Elm_Label_Slide_Mode mode);
192 * @brief Get the slide mode of the label widget.
194 * @param obj The label object
195 * @return The slide mode
197 * @see elm_label_slide_mode_set()
201 EAPI Elm_Label_Slide_Mode elm_label_slide_mode_get(const Evas_Object *obj);
204 * @brief Start slide effect.
206 * @param obj The label object
208 * @see elm_label_slide_mode_set()
212 EAPI void elm_label_slide_go(Evas_Object *obj);