src/lib/elm_label.h

   1 /**
   2  * @defgroup Label Label
   3  * @ingroup Elementary
   4  *
   5  * @image html label_inheritance_tree.png
   6  * @image latex label_inheritance_tree.eps
   7  *
   8  * @image html img/widget/label/preview-00.png
   9  * @image latex img/widget/label/preview-00.eps
  10  *
  11  * @brief Widget to display text, with simple html-like markup.
  12  *
  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
  20  * right again).
  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
  23  * position is reset.
  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.
  27  *
  28  * Custom themes can of course invent new markup tags and style them any way
  29  * they like.
  30  *
  31  * This widget inherits from the @ref Layout one, so that all the
  32  * functions acting on it also work for label objects.
  33  *
  34  * This widget emits the following signals, besides the ones sent from
  35  * @ref Layout:
  36  * @li @c "language,changed": The program's language changed.
  37  * @li @c "slide,end": The slide is end.
  38  *
  39  * See @ref tutorial_label for a demonstration of how to use a label widget.
  40  * @{
  41  */
  42
  43 typedef enum
  44 {
  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;
  49
  50
  51 /**
  52  * @brief Add a new label to the parent
  53  *
  54  * @param parent The parent object
  55  * @return The new object or NULL if it cannot be created
  56  *
  57  * @ingroup Label
  58  */
  59 EAPI Evas_Object                *elm_label_add(Evas_Object *parent);
  60
  61 /**
  62  * @brief Set the wrapping behavior of the label
  63  *
  64  * @param obj The label object
  65  * @param wrap To wrap text or not
  66  *
  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
  72  *
  73  * @ingroup Label
  74  */
  75 EAPI void                        elm_label_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap);
  76
  77 /**
  78  * @brief Get the wrapping behavior of the label
  79  *
  80  * @param obj The label object
  81  * @return Wrap type
  82  *
  83  * @see elm_label_line_wrap_set()
  84  *
  85  * @ingroup Label
  86  */
  87 EAPI Elm_Wrap_Type               elm_label_line_wrap_get(const Evas_Object *obj);
  88
  89 /**
  90  * @brief Set wrap width of the label
  91  *
  92  * @param obj The label object
  93  * @param w The wrap width in pixels at a minimum where words need to wrap
  94  *
  95  * This function sets the maximum width size hint of the label.
  96  *
  97  * @warning This is only relevant if the label is inside a container.
  98  *
  99  * @ingroup Label
 100  */
 101 EAPI void                        elm_label_wrap_width_set(Evas_Object *obj, Evas_Coord w);
 102
 103 /**
 104  * @brief Get wrap width of the label
 105  *
 106  * @param obj The label object
 107  * @return The wrap width in pixels at a minimum where words need to wrap
 108  *
 109  * @see elm_label_wrap_width_set()
 110  *
 111  * @ingroup Label
 112  */
 113 EAPI Evas_Coord                  elm_label_wrap_width_get(const Evas_Object *obj);
 114
 115 /**
 116  * @brief Set the ellipsis behavior of the label
 117  *
 118  * @param obj The label object
 119  * @param ellipsis To ellipsis text or not
 120  *
 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.
 123  *
 124  * @warning This doesn't work with slide(elm_label_slide_set()) or if the
 125  * chosen wrap method was #ELM_WRAP_WORD.
 126  *
 127  * @ingroup Label
 128  */
 129 EAPI void                        elm_label_ellipsis_set(Evas_Object *obj, Eina_Bool ellipsis);
 130
 131 /**
 132  * @brief Get the ellipsis behavior of the label
 133  *
 134  * @param obj The label object
 135  * @return If true, an ellipsis will be shown at the end of the label area.
 136  *
 137  * @see elm_label_ellipsis_set()
 138  *
 139  * @ingroup Label
 140  */
 141 EAPI Eina_Bool                   elm_label_ellipsis_get(const Evas_Object *obj);
 142
 143 /**
 144  * @brief Set the slide duration (speed) of the label
 145  *
 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
 149  *
 150  * @ingroup Label
 151  */
 152 EAPI void                        elm_label_slide_duration_set(Evas_Object *obj, double duration);
 153
 154 /**
 155  * @brief Get the slide duration(speed) of the label
 156  *
 157  * @param obj The label object
 158  * @return The duration time in moving text from slide begin position to slide end position
 159  *
 160  * @see elm_label_slide_duration_set()
 161  *
 162  * @ingroup Label
 163  */
 164 EAPI double                      elm_label_slide_duration_get(const Evas_Object *obj);
 165
 166 /**
 167  * @brief Set the slide mode of the label widget.
 168  *
 169  * @param obj The label object
 170  * @param mode The slide mode
 171  *
 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
 178  *
 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.
 184  *
 185  * @see elm_label_slide_mode_get().
 186  *
 187  * @ingroup Label
 188  */
 189 EAPI void                        elm_label_slide_mode_set(Evas_Object *obj, Elm_Label_Slide_Mode mode);
 190
 191 /**
 192  * @brief Get the slide mode of the label widget.
 193  *
 194  * @param obj The label object
 195  * @return The slide mode
 196  *
 197  * @see elm_label_slide_mode_set()
 198  *
 199  * @ingroup Label
 200  */
 201 EAPI Elm_Label_Slide_Mode        elm_label_slide_mode_get(const Evas_Object *obj);
 202
 203 /**
 204  * @brief Start slide effect.
 205  *
 206  * @param obj The label object
 207  *
 208  * @see elm_label_slide_mode_set()
 209  *
 210  * @ingroup Label
 211  */
 212 EAPI void                        elm_label_slide_go(Evas_Object *obj);
 213
 214 /**
 215  * @}
 216  */