## ClutterLabel

ClutterLabel — Actor for displaying text

## Synopsis

                        ClutterLabel;
                        ClutterLabelClass;
    ClutterActor *      clutter_label_new                   (void);
    ClutterActor *      clutter_label_new_with_text         (const gchar *font_name,
                                                             const gchar *text);
    ClutterActor*       clutter_label_new_full              (const gchar *font_name,
                                                             const gchar *text,
                                                             const ClutterColor *color);
    void                clutter_label_set_text              (ClutterLabel *label,
                                                             const gchar *text);
    const gchar *       clutter_label_get_text              (ClutterLabel *label);
    void                clutter_label_set_font_name         (ClutterLabel *label,
                                                             const gchar *font_name);
    const gchar *       clutter_label_get_font_name         (ClutterLabel *label);
    void                clutter_label_set_color             (ClutterLabel *label,
                                                             const ClutterColor *color);
    void                clutter_label_get_color             (ClutterLabel *label,
                                                             ClutterColor *color);
    void                clutter_label_set_ellipsize         (ClutterLabel *label,
                                                             PangoEllipsizeMode mode);
    PangoEllipsizeMode  clutter_label_get_ellipsize         (ClutterLabel *label);
    void                clutter_label_set_line_wrap         (ClutterLabel *label,
                                                             gboolean wrap);
    gboolean            clutter_label_get_line_wrap         (ClutterLabel *label);
    void                clutter_label_set_line_wrap_mode    (ClutterLabel *label,
                                                             PangoWrapMode wrap_mode);
    PangoWrapMode       clutter_label_get_line_wrap_mode    (ClutterLabel *label);
    PangoLayout *       clutter_label_get_layout            (ClutterLabel *label);
    void                clutter_label_set_attributes        (ClutterLabel *label,
                                                             PangoAttrList *attrs);
    PangoAttrList *     clutter_label_get_attributes        (ClutterLabel *label);
    void                clutter_label_set_use_markup        (ClutterLabel *label,
                                                             gboolean setting);
    gboolean            clutter_label_get_use_markup        (ClutterLabel *label);
    void                clutter_label_set_alignment         (ClutterLabel *label,
                                                             PangoAlignment alignment);
    PangoAlignment      clutter_label_get_alignment         (ClutterLabel *label);
    gboolean            clutter_label_get_justify           (ClutterLabel *label);
    void                clutter_label_set_justify           (ClutterLabel *label,
                                                             gboolean justify);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----ClutterLabel

## Implemented Interfaces

ClutterLabel implements

## Properties

      "alignment"                PangoAlignment        : Read / Write
      "attributes"               PangoAttrList*        : Read / Write
      "color"                    ClutterColor*         : Read / Write
      "ellipsize"                PangoEllipsizeMode    : Read / Write
      "font-name"                gchar*                : Read / Write
      "justify"                  gboolean              : Read / Write
      "text"                     gchar*                : Read / Write
      "use-markup"               gboolean              : Read / Write
      "wrap"                     gboolean              : Read / Write
      "wrap-mode"                PangoWrapMode         : Read / Write

## Description

ClutterLabel is a ClutterActor that displays text using Pango.

## Details

### ClutterLabel

    typedef struct _ClutterLabel ClutterLabel;

### ClutterLabelClass

    typedef struct {
    } ClutterLabelClass;

### clutter_label_new ()

    ClutterActor *      clutter_label_new                   (void);

Creates a new, empty ClutterLabel.

Returns : | the newly created ClutterLabel

### clutter_label_new_with_text ()

    ClutterActor *      clutter_label_new_with_text         (const gchar *font_name,
                                                             const gchar *text);

Creates a new ClutterLabel displaying `text` using `font_name`.

`font_name` : | the name (and size) of the font to be used
`text` : | the text to be displayed
Returns : | a ClutterLabel

### clutter_label_new_full ()

    ClutterActor*       clutter_label_new_full              (const gchar *font_name,
                                                             const gchar *text,
                                                             const ClutterColor *color);

Creates a new ClutterLabel displaying `text` with `color` using `font_name`.

`font_name` : | the name (and size) of the font to be used
`text` : | the text to be displayed
`color` : | ClutterColor for text
Returns : | a ClutterLabel

### clutter_label_set_text ()

    void                clutter_label_set_text              (ClutterLabel *label,
                                                             const gchar *text);

Sets `text` as the text to be displayed by `label`.

`label` : | a ClutterLabel
`text` : | the text to be displayed

### clutter_label_get_text ()

    const gchar *       clutter_label_get_text              (ClutterLabel *label);

Retrieves the text displayed by `label`

`label` : | a ClutterLabel
Returns : | the text of the label. The returned string is owned by ClutterLabel and should not be modified or freed.

### clutter_label_set_font_name ()

    void                clutter_label_set_font_name         (ClutterLabel *label,
                                                             const gchar *font_name);

Sets `font_name` as the font used by `label`.

`font_name` must be a string containing the font name and its size, similarly to what you would feed to the `pango_font_description_from_string()` function.

`label` : | a ClutterLabel
`font_name` : | a font name and size, or `NULL` for the default font

### clutter_label_get_font_name ()

    const gchar *       clutter_label_get_font_name         (ClutterLabel *label);

Retrieves the font used by `label`.

`label` : | a ClutterLabel
Returns : | a string containing the font name, in a format understandable by `pango_font_description_from_string()`. The string is owned by `label` and should not be modified or freed.

### clutter_label_set_color ()

    void                clutter_label_set_color             (ClutterLabel *label,
                                                             const ClutterColor *color);

Sets the color of `label`.

`label` : | a ClutterLabel
`color` : | a ClutterColor

### clutter_label_get_color ()

    void                clutter_label_get_color             (ClutterLabel *label,
                                                             ClutterColor *color);

Retrieves the color of `label`.

`label` : | a ClutterLabel
`color` : | return location for a ClutterColor

### clutter_label_set_ellipsize ()

    void                clutter_label_set_ellipsize         (ClutterLabel *label,
                                                             PangoEllipsizeMode mode);

Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there is not enough space to render the entire string.

`label` : | a ClutterLabel
`mode` : | a PangoEllipsizeMode

Since 0.2

### clutter_label_get_ellipsize ()

    PangoEllipsizeMode  clutter_label_get_ellipsize         (ClutterLabel *label);

Returns the ellipsizing position of the label. See `clutter_label_set_ellipsize()`.

`label` : | a ClutterLabel
Returns : | PangoEllipsizeMode

Since 0.2

### clutter_label_set_line_wrap ()

    void                clutter_label_set_line_wrap         (ClutterLabel *label,
                                                             gboolean wrap);

Toggles line wrapping within the ClutterLabel widget. `TRUE` makes it break lines if text exceeds the widget's size. `FALSE` lets the text get cut off by the edge of the widget if it exceeds the widget size.

`label` : | a ClutterLabel
`wrap` : | the setting

Since 0.2

### clutter_label_get_line_wrap ()

    gboolean            clutter_label_get_line_wrap         (ClutterLabel *label);

Returns whether lines in the label are automatically wrapped. See `clutter_label_set_line_wrap()`.

`label` : | a ClutterLabel
Returns : | `TRUE` if the lines of the label are automatically wrapped.

Since 0.2

### clutter_label_set_line_wrap_mode ()

    void                clutter_label_set_line_wrap_mode    (ClutterLabel *label,
                                                             PangoWrapMode wrap_mode);

If line wrapping is on (see `clutter_label_set_line_wrap()`) this controls how the line wrapping is done. The default is `PANGO_WRAP_WORD` which means wrap on word boundaries.

`label` : | a ClutterLabel
`wrap_mode` : | the line wrapping mode

Since 0.2

### clutter_label_get_line_wrap_mode ()

    PangoWrapMode       clutter_label_get_line_wrap_mode    (ClutterLabel *label);

Returns line wrap mode used by the label. See `clutter_label_set_line_wrap_mode()`.

`label` : | a ClutterLabel
Returns : | `TRUE` if the lines of the label are automatically wrapped.

Since 0.2

### clutter_label_get_layout ()

    PangoLayout *       clutter_label_get_layout            (ClutterLabel *label);

Gets the PangoLayout used to display the label. The layout is useful to e.g. convert text positions to pixel positions. The returned layout is owned by the label so need not be freed by the caller.

`label` : | a ClutterLabel
Returns : | the PangoLayout for this label

Since 0.2

### clutter_label_set_attributes ()

    void                clutter_label_set_attributes        (ClutterLabel *label,
                                                             PangoAttrList *attrs);

Sets a PangoAttrList; the attributes in the list are applied to the label text. The attributes set with this function will be ignored if the "use_markup" property is `TRUE`.

`label` : | a ClutterLabel
`attrs` : | a PangoAttrList

Since 0.2

### clutter_label_get_attributes ()

    PangoAttrList *     clutter_label_get_attributes        (ClutterLabel *label);

Gets the attribute list that was set on the label using `clutter_label_set_attributes()`, if any.

`label` : | a ClutterLabel
Returns : | the attribute list, or `NULL` if none was set.

Since 0.2

### clutter_label_set_use_markup ()

    void                clutter_label_set_use_markup        (ClutterLabel *label,
                                                             gboolean setting);

Sets whether the text of the label contains markup in Pango's text markup language.

`label` : | a ClutterLabel
`setting` : | `TRUE` if the label's text should be parsed for markup.

### clutter_label_get_use_markup ()

    gboolean            clutter_label_get_use_markup        (ClutterLabel *label);

Returns whether the label's text is interpreted as marked up with the Pango text markup language. See `clutter_label_set_use_markup()`.

`label` : | a ClutterLabel
Returns : | `TRUE` if the label's text will be parsed for markup.

### clutter_label_set_alignment ()

    void                clutter_label_set_alignment         (ClutterLabel *label,
                                                             PangoAlignment alignment);

Sets text alignment of the label.

The alignment will only be used when the contents of the label are enough to wrap, and the "wrap" property is set to `TRUE`.

`label` : | a ClutterLabel
`alignment` : | A PangoAlignment

### clutter_label_get_alignment ()

    PangoAlignment      clutter_label_get_alignment         (ClutterLabel *label);

Returns the label's text alignment

`label` : | a ClutterLabel
Returns : | The label's PangoAlignment Since 0.2

### clutter_label_get_justify ()

    gboolean            clutter_label_get_justify           (ClutterLabel *label);

Retrieves whether the label should justify the text on both margins.

`label` : | a ClutterLabel
Returns : | `TRUE` if the text should be justified

Since 0.6

### clutter_label_set_justify ()

    void                clutter_label_set_justify           (ClutterLabel *label,
                                                             gboolean justify);

Sets whether the text of the `label` actor should be justified on both margins. This setting is ignored if Clutter is compiled against Pango < 1.18.

`label` : | a ClutterLabel
`justify` : | whether the text should be justified

Since 0.6

## Property Details

### The `"alignment"` property

      "alignment"                PangoAlignment        : Read / Write

The preferred alignment for the string.

Default value: PANGO_ALIGN_LEFT

### The `"attributes"` property

      "attributes"               PangoAttrList*        : Read / Write

A list of style attributes to apply to the text of the label.

### The `"color"` property

      "color"                    ClutterColor*         : Read / Write

Font Colour.

### The `"ellipsize"` property

      "ellipsize"                PangoEllipsizeMode    : Read / Write

The preferred place to ellipsize the string, if the label does not have enough room to display the entire string.

Default value: PANGO_ELLIPSIZE_NONE

### The `"font-name"` property

      "font-name"                gchar*                : Read / Write

Pango font description.

Default value: NULL

### The `"justify"` property

      "justify"                  gboolean              : Read / Write

Whether the contents of the label should be justified on both margins.

Default value: FALSE

Since 0.6

### The `"text"` property

      "text"                     gchar*                : Read / Write

Text to render.

Default value: NULL

### The `"use-markup"` property

      "use-markup"               gboolean              : Read / Write

The text of the label includes XML markup. See pango_parse_markup().

Default value: FALSE

### The `"wrap"` property

      "wrap"                     gboolean              : Read / Write

If set, wrap lines if the text becomes too wide.

Default value: FALSE

### The `"wrap-mode"` property

      "wrap-mode"                PangoWrapMode         : Read / Write

If wrap is set, controls how line-wrapping is done.

Default value: PANGO_WRAP_WORD