src/lib/elm_label.h

   1 /**
   2  * @defgroup Label Label
   3  *
   4  * @image html img/widget/label/preview-00.png
   5  * @image latex img/widget/label/preview-00.eps
   6  *
   7  * @brief Widget to display text, with simple html-like markup.
   8  *
   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
  16  * right again).
  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
  19  * position is reset.
  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.
  23  *
  24  * Custom themes can of course invent new markup tags and style them any way
  25  * they like.
  26  *
  27  * The following signals may be emitted by the label widget:
  28  * @li "language,changed": The program's language changed.
  29  *
  30  * See @ref tutorial_label for a demonstration of how to use a label widget.
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Add a new label to the parent
  36  *
  37  * @param parent The parent object
  38  * @return The new object or NULL if it cannot be created
  39  */
  40 EAPI Evas_Object *
  41                                  elm_label_add(Evas_Object *parent)
  42 EINA_ARG_NONNULL(1);
  43
  44 /**
  45  * @brief Set the label on the label object
  46  *
  47  * @param obj The label object
  48  * @param label The label will be used on the label object
  49  * @deprecated See elm_object_text_set()
  50  */
  51 EINA_DEPRECATED EAPI void        elm_label_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
  52
  53 /**
  54  * @brief Get the label used on the label object
  55  *
  56  * @param obj The label object
  57  * @return The string inside the label
  58  * @deprecated See elm_object_text_get()
  59  */
  60 EINA_DEPRECATED EAPI const char *elm_label_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  61
  62 /**
  63  * @brief Set the wrapping behavior of the label
  64  *
  65  * @param obj The label object
  66  * @param wrap To wrap text or not
  67  *
  68  * By default no wrapping is done. Possible values for @p wrap are:
  69  * @li ELM_WRAP_NONE - No wrapping
  70  * @li ELM_WRAP_CHAR - wrap between characters
  71  * @li ELM_WRAP_WORD - wrap between words
  72  * @li ELM_WRAP_MIXED - Word wrap, and if that fails, char wrap
  73  */
  74 EAPI void                        elm_label_line_wrap_set(Evas_Object *obj, Elm_Wrap_Type wrap) EINA_ARG_NONNULL(1);
  75
  76 /**
  77  * @brief Get the wrapping behavior of the label
  78  *
  79  * @param obj The label object
  80  * @return Wrap type
  81  *
  82  * @see elm_label_line_wrap_set()
  83  */
  84 EAPI Elm_Wrap_Type               elm_label_line_wrap_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  85
  86 /**
  87  * @brief Set wrap width of the label
  88  *
  89  * @param obj The label object
  90  * @param w The wrap width in pixels at a minimum where words need to wrap
  91  *
  92  * This function sets the maximum width size hint of the label.
  93  *
  94  * @warning This is only relevant if the label is inside a container.
  95  */
  96 EAPI void                        elm_label_wrap_width_set(Evas_Object *obj, Evas_Coord w) EINA_ARG_NONNULL(1);
  97
  98 /**
  99  * @brief Get wrap width of the label
 100  *
 101  * @param obj The label object
 102  * @return The wrap width in pixels at a minimum where words need to wrap
 103  *
 104  * @see elm_label_wrap_width_set()
 105  */
 106 EAPI Evas_Coord                  elm_label_wrap_width_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 107
 108 /**
 109  * @brief Set wrap height of the label
 110  *
 111  * @param obj The label object
 112  * @param h The wrap height in pixels at a minimum where words need to wrap
 113  *
 114  * This function sets the maximum height size hint of the label.
 115  *
 116  * @warning This is only relevant if the label is inside a container.
 117  */
 118 EAPI void                        elm_label_wrap_height_set(Evas_Object *obj, Evas_Coord h) EINA_ARG_NONNULL(1);
 119
 120 /**
 121  * @brief get wrap width of the label
 122  *
 123  * @param obj The label object
 124  * @return The wrap height in pixels at a minimum where words need to wrap
 125  */
 126 EAPI Evas_Coord                  elm_label_wrap_height_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 127
 128 /**
 129  * @brief Set the font size on the label object.
 130  *
 131  * @param obj The label object
 132  * @param size font size
 133  *
 134  * @warning NEVER use this. It is for hyper-special cases only. use styles
 135  * instead. e.g. "default", "marker", "slide_long" etc.
 136  */
 137 EAPI void                        elm_label_fontsize_set(Evas_Object *obj, int fontsize) EINA_ARG_NONNULL(1);
 138
 139 /**
 140  * @brief Set the text color on the label object
 141  *
 142  * @param obj The label object
 143  * @param r Red property background color of The label object
 144  * @param g Green property background color of The label object
 145  * @param b Blue property background color of The label object
 146  * @param a Alpha property background color of The label object
 147  *
 148  * @warning NEVER use this. It is for hyper-special cases only. use styles
 149  * instead. e.g. "default", "marker", "slide_long" etc.
 150  */
 151 EAPI void                        elm_label_text_color_set(Evas_Object *obj, unsigned int r, unsigned int g, unsigned int b, unsigned int a) EINA_ARG_NONNULL(1);
 152
 153 /**
 154  * @brief Set the text align on the label object
 155  *
 156  * @param obj The label object
 157  * @param align align mode ("left", "center", "right")
 158  *
 159  * @warning NEVER use this. It is for hyper-special cases only. use styles
 160  * instead. e.g. "default", "marker", "slide_long" etc.
 161  */
 162 EAPI void                        elm_label_text_align_set(Evas_Object *obj, const char *alignmode) EINA_ARG_NONNULL(1);
 163
 164 /**
 165  * @brief Set background color of the label
 166  *
 167  * @param obj The label object
 168  * @param r Red property background color of The label object
 169  * @param g Green property background color of The label object
 170  * @param b Blue property background color of The label object
 171  * @param a Alpha property background alpha of The label object
 172  *
 173  * @warning NEVER use this. It is for hyper-special cases only. use styles
 174  * instead. e.g. "default", "marker", "slide_long" etc.
 175  */
 176 EAPI void                        elm_label_background_color_set(Evas_Object *obj, unsigned int r, unsigned int g, unsigned int b, unsigned int a) EINA_ARG_NONNULL(1);
 177
 178 /**
 179  * @brief Set the ellipsis behavior of the label
 180  *
 181  * @param obj The label object
 182  * @param ellipsis To ellipsis text or not
 183  *
 184  * If set to true and the text doesn't fit in the label an ellipsis("...")
 185  * will be shown at the end of the widget.
 186  *
 187  * @warning This doesn't work with slide(elm_label_slide_set()) or if the
 188  * choosen wrap method was ELM_WRAP_WORD.
 189  */
 190 EAPI void                        elm_label_ellipsis_set(Evas_Object *obj, Eina_Bool ellipsis) EINA_ARG_NONNULL(1);
 191
 192 /**
 193  * @brief Set the text slide of the label
 194  *
 195  * @param obj The label object
 196  * @param slide To start slide or stop
 197  *
 198  * If set to true, the text of the label will slide/scroll through the length of
 199  * label.
 200  *
 201  * @warning This only works with the themes "slide_short", "slide_long" and
 202  * "slide_bounce".
 203  */
 204 EAPI void                        elm_label_slide_set(Evas_Object *obj, Eina_Bool slide) EINA_ARG_NONNULL(1);
 205
 206 /**
 207  * @brief Get the text slide mode of the label
 208  *
 209  * @param obj The label object
 210  * @return slide slide mode value
 211  *
 212  * @see elm_label_slide_set()
 213  */
 214 EAPI Eina_Bool                   elm_label_slide_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
 215
 216 /**
 217  * @brief Set the slide duration(speed) of the label
 218  *
 219  * @param obj The label object
 220  * @return The duration in seconds in moving text from slide begin position
 221  * to slide end position
 222  */
 223 EAPI void                        elm_label_slide_duration_set(Evas_Object *obj, double duration) EINA_ARG_NONNULL(1);
 224
 225 /**
 226  * @brief Get the slide duration(speed) of the label
 227  *
 228  * @param obj The label object
 229  * @return The duration time in moving text from slide begin position to slide end position
 230  *
 231  * @see elm_label_slide_duration_set()
 232  */
 233 EAPI double                      elm_label_slide_duration_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
 234
 235 /**
 236  * @}
 237  */