## ClutterText ClutterText — An actor for displaying and editing text |

## Synopsis

    struct              ClutterText;
    struct              ClutterTextClass;
    ClutterActor *      clutter_text_new                    (void);
    ClutterActor *      clutter_text_new_full               (const gchar *font_name,
                                                             const gchar *text,
                                                             const ClutterColor *color);
    ClutterActor *      clutter_text_new_with_text          (const gchar *font_name,
                                                             const gchar *text);

    void                clutter_text_set_text               (ClutterText *self,
                                                             const gchar *text);
    void                clutter_text_set_markup             (ClutterText *self,
                                                             const gchar *markup);
    const gchar *       clutter_text_get_text               (ClutterText *self);
    void                clutter_text_set_activatable        (ClutterText *self,
                                                             gboolean activatable);
    gboolean            clutter_text_get_activatable        (ClutterText *self);
    void                clutter_text_set_attributes         (ClutterText *self,
                                                             PangoAttrList *attrs);
    PangoAttrList *     clutter_text_get_attributes         (ClutterText *self);
    void                clutter_text_set_color              (ClutterText *self,
                                                             const ClutterColor *color);
    void                clutter_text_get_color              (ClutterText *self,
                                                             ClutterColor *color);
    void                clutter_text_set_ellipsize          (ClutterText *self,
                                                             PangoEllipsizeMode mode);
    PangoEllipsizeMode  clutter_text_get_ellipsize          (ClutterText *self);
    void                clutter_text_set_font_name          (ClutterText *self,
                                                             const gchar *font_name);
    const gchar *       clutter_text_get_font_name          (ClutterText *self);
    void                clutter_text_set_font_description   (ClutterText *self,
                                                             PangoFontDescription *font_desc);
    PangoFontDescription * clutter_text_get_font_description
                                                            (ClutterText *self);
    void                clutter_text_set_password_char      (ClutterText *self,
                                                             gunichar wc);
    gunichar            clutter_text_get_password_char      (ClutterText *self);
    void                clutter_text_set_justify            (ClutterText *self,
                                                             gboolean justify);
    gboolean            clutter_text_get_justify            (ClutterText *self);
    PangoLayout *       clutter_text_get_layout             (ClutterText *self);
    void                clutter_text_set_line_alignment     (ClutterText *self,
                                                             PangoAlignment alignment);
    PangoAlignment      clutter_text_get_line_alignment     (ClutterText *self);
    void                clutter_text_set_line_wrap          (ClutterText *self,
                                                             gboolean line_wrap);
    gboolean            clutter_text_get_line_wrap          (ClutterText *self);
    void                clutter_text_set_line_wrap_mode     (ClutterText *self,
                                                             PangoWrapMode wrap_mode);
    PangoWrapMode       clutter_text_get_line_wrap_mode     (ClutterText *self);
    void                clutter_text_set_max_length         (ClutterText *self,
                                                             gint max);
    gint                clutter_text_get_max_length         (ClutterText *self);
    void                clutter_text_set_selectable         (ClutterText *self,
                                                             gboolean selectable);
    gboolean            clutter_text_get_selectable         (ClutterText *self);
    void                clutter_text_set_selection          (ClutterText *self,
                                                             gssize start_pos,
                                                             gssize end_pos);
    gchar *             clutter_text_get_selection          (ClutterText *self);
    void                clutter_text_set_selection_bound    (ClutterText *self,
                                                             gint selection_bound);
    gint                clutter_text_get_selection_bound    (ClutterText *self);
    void                clutter_text_set_single_line_mode   (ClutterText *self,
                                                             gboolean single_line);
    gboolean            clutter_text_get_single_line_mode   (ClutterText *self);
    void                clutter_text_set_use_markup         (ClutterText *self,
                                                             gboolean setting);
    gboolean            clutter_text_get_use_markup         (ClutterText *self);

    void                clutter_text_set_editable           (ClutterText *self,
                                                             gboolean editable);
    gboolean            clutter_text_get_editable           (ClutterText *self);
    void                clutter_text_insert_text            (ClutterText *self,
                                                             const gchar *text,
                                                             gssize position);
    void                clutter_text_insert_unichar         (ClutterText *self,
                                                             gunichar wc);
    void                clutter_text_delete_chars           (ClutterText *self,
                                                             guint n_chars);
    void                clutter_text_delete_text            (ClutterText *self,
                                                             gssize start_pos,
                                                             gssize end_pos);
    gboolean            clutter_text_delete_selection       (ClutterText *self);
    gchar *             clutter_text_get_chars              (ClutterText *self,
                                                             gssize start_pos,
                                                             gssize end_pos);
    void                clutter_text_set_cursor_color       (ClutterText *self,
                                                             const ClutterColor *color);
    void                clutter_text_get_cursor_color       (ClutterText *self,
                                                             ClutterColor *color);
    void                clutter_text_set_selection_color    (ClutterText *self,
                                                             const ClutterColor *color);
    void                clutter_text_get_selection_color    (ClutterText *self,
                                                             ClutterColor *color);
    void                clutter_text_set_selected_text_color
                                                            (ClutterText *self,
                                                             const ClutterColor *color);
    void                clutter_text_get_selected_text_color
                                                            (ClutterText *self,
                                                             ClutterColor *color);
    void                clutter_text_set_cursor_position    (ClutterText *self,
                                                             gint position);
    gint                clutter_text_get_cursor_position    (ClutterText *self);
    void                clutter_text_set_cursor_visible     (ClutterText *self,
                                                             gboolean cursor_visible);
    gboolean            clutter_text_get_cursor_visible     (ClutterText *self);
    void                clutter_text_set_cursor_size        (ClutterText *self,
                                                             gint size);
    guint               clutter_text_get_cursor_size        (ClutterText *self);

    gboolean            clutter_text_activate               (ClutterText *self);
    gboolean            clutter_text_position_to_coords     (ClutterText *self,
                                                             gint position,
                                                             gfloat *x,
                                                             gfloat *y,
                                                             gfloat *line_height);
    void                clutter_text_set_preedit_string     (ClutterText *self,
                                                             const gchar *preedit_str,
                                                             PangoAttrList *preedit_attrs,
                                                             guint cursor_pos);
    void                clutter_text_get_layout_offsets     (ClutterText *self,
                                                             gint *x,
                                                             gint *y);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----ClutterText

## Implemented Interfaces

ClutterText implements ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Properties

      "activatable"              gboolean              : Read / Write
      "attributes"               PangoAttrList*        : Read / Write
      "color"                    ClutterColor*         : Read / Write
      "cursor-color"             ClutterColor*         : Read / Write
      "cursor-color-set"         gboolean              : Read
      "cursor-size"              gint                  : Read / Write
      "cursor-visible"           gboolean              : Read / Write
      "editable"                 gboolean              : Read / Write
      "ellipsize"                PangoEllipsizeMode    : Read / Write
      "font-description"         PangoFontDescription*  : Read / Write
      "font-name"                gchar*                : Read / Write
      "justify"                  gboolean              : Read / Write
      "line-alignment"           PangoAlignment        : Read / Write
      "line-wrap"                gboolean              : Read / Write
      "line-wrap-mode"           PangoWrapMode         : Read / Write
      "max-length"               gint                  : Read / Write
      "password-char"            guint                 : Read / Write
      "position"                 gint                  : Read / Write
      "selectable"               gboolean              : Read / Write
      "selected-text-color"      ClutterColor*         : Read / Write
      "selected-text-color-set"  gboolean              : Read
      "selection-bound"          gint                  : Read / Write
      "selection-color"          ClutterColor*         : Read / Write
      "selection-color-set"      gboolean              : Read
      "single-line-mode"         gboolean              : Read / Write
      "text"                     gchar*                : Read / Write
      "use-markup"               gboolean              : Read / Write

## Signals

      "activate"                                       : Run Last
      "cursor-event"                                   : Run Last
      "delete-text"                                    : Action
      "insert-text"                                    : Action
      "text-changed"                                   : Run Last

## Description

ClutterText is an actor that displays custom text using Pango as the text rendering engine.

ClutterText also allows inline editing of the text if the actor is set editable using `clutter_text_set_editable()`.

Selection using keyboard or pointers can be enabled using `clutter_text_set_selectable()`.

ClutterText is available since Clutter 1.0

## Details

### struct ClutterText

    struct ClutterText;

The ClutterText struct contains only private data.

Since 1.0

### struct ClutterTextClass

    struct ClutterTextClass {
      /* signals, not vfuncs */
      void (* text_changed) (ClutterText           *self);
      void (* activate)     (ClutterText           *self);
      void (* cursor_event) (ClutterText           *self,
                             const ClutterGeometry *geometry);
    };

The ClutterTextClass struct contains only private data.

`text_changed` () | class handler for the "text-changed" signal
`activate` () | class handler for the "activate" signal
`cursor_event` () | class handler for the "cursor_event" signal

Since 1.0

### clutter_text_new ()

    ClutterActor *      clutter_text_new                    (void);

Creates a new ClutterText actor. This actor can be used to display and edit text.

Returns : | the newly created ClutterText actor

Since 1.0

### clutter_text_new_full ()

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

Creates a new ClutterText actor, using `font_name` as the font description; `text` will be used to set the contents of the actor; and `color` will be used as the color to render `text`.

This function is equivalent to calling `clutter_text_new()`, `clutter_text_set_font_name()`, `clutter_text_set_text()` and `clutter_text_set_color()`.

`font_name` : | a string with a font description
`text` : | the contents of the actor
`color` : | the color to be used to render `text`
Returns : | the newly created ClutterText actor

Since 1.0

### clutter_text_new_with_text ()

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

Creates a new ClutterText actor, using `font_name` as the font description; `text` will be used to set the contents of the actor.

This function is equivalent to calling `clutter_text_new()`, `clutter_text_set_font_name()`, and `clutter_text_set_text()`.

`font_name` : | a string with a font description
`text` : | the contents of the actor
Returns : | the newly created ClutterText actor

Since 1.0

### clutter_text_set_text ()

    void                clutter_text_set_text               (ClutterText *self,
                                                             const gchar *text);

Sets the contents of a ClutterText actor.

If the "use-markup" property was set to `TRUE` it will be reset to `FALSE` as a side effect. If you want to maintain the "use-markup" you should use the `clutter_text_set_markup()` function instead

`self` : | a ClutterText
`text` : | the text to set. Passing `NULL` is the same as passing "" (the empty string)

Since 1.0

### clutter_text_set_markup ()

    void                clutter_text_set_markup             (ClutterText *self,
                                                             const gchar *markup);

Sets `markup` as the contents of a ClutterText.

This is a convenience function for setting a string containing Pango markup, and it is logically equivalent to:

    1
    2
    clutter_text_set_text (CLUTTER_TEXT (actor), markup);
    clutter_text_set_use_markup (CLUTTER_TEXT (actor), TRUE);

`self` : | a ClutterText
`markup` : | a string containing Pango markup. Passing `NULL` is the same as passing "" (the empty string)

Since 1.0

### clutter_text_get_text ()

    const gchar *       clutter_text_get_text               (ClutterText *self);

Retrieves a pointer to the current contents of a ClutterText actor.

If you need a copy of the contents for manipulating, either use `g_strdup()` on the returned string, or use:

    1
    copy = clutter_text_get_chars (text, 0, -1);

Which will return a newly allocated string.

`self` : | a ClutterText
Returns : | the contents of the actor. The returned string is owned by the ClutterText actor and should never be modified or freed

Since 1.0

### clutter_text_set_activatable ()

    void                clutter_text_set_activatable        (ClutterText *self,
                                                             gboolean activatable);

Sets whether a ClutterText actor should be activatable.

An activatable ClutterText actor will emit the "activate" signal whenever the 'Enter' (or 'Return') key is pressed; if it is not activatable, a new line will be appended to the current content.

An activatable ClutterText must also be set as editable using `clutter_text_set_editable()`.

`self` : | a ClutterText
`activatable` : | whether the ClutterText actor should be activatable

Since 1.0

### clutter_text_get_activatable ()

    gboolean            clutter_text_get_activatable        (ClutterText *self);

Retrieves whether a ClutterText is activatable or not.

`self` : | a ClutterText
Returns : | `TRUE` if the actor is activatable

Since 1.0

### clutter_text_set_attributes ()

    void                clutter_text_set_attributes         (ClutterText *self,
                                                             PangoAttrList *attrs);

Sets the attributes list that are going to be applied to the ClutterText contents.

The ClutterText actor will take a reference on the PangoAttrList passed to this function.

`self` : | a ClutterText
`attrs` : | a PangoAttrList or `NULL` to unset the attributes

Since 1.0

### clutter_text_get_attributes ()

    PangoAttrList *     clutter_text_get_attributes         (ClutterText *self);

Gets the attribute list that was set on the ClutterText actor `clutter_text_set_attributes()`, if any.

`self` : | a ClutterText
Returns : | the attribute list, or `NULL` if none was set. The returned value is owned by the ClutterText and should not be unreferenced. [transfer none]

Since 1.0

### clutter_text_set_color ()

    void                clutter_text_set_color              (ClutterText *self,
                                                             const ClutterColor *color);

Sets the color of the contents of a ClutterText actor.

The overall opacity of the ClutterText actor will be the result of the alpha value of `color` and the composited opacity of the actor itself on the scenegraph, as returned by `clutter_actor_get_paint_opacity()`.

`self` : | a ClutterText
`color` : | a ClutterColor

Since 1.0

### clutter_text_get_color ()

    void                clutter_text_get_color              (ClutterText *self,
                                                             ClutterColor *color);

Retrieves the text color as set by `clutter_text_set_color()`.

`self` : | a ClutterText
`color` : | return location for a ClutterColor. [out caller-allocates]

Since 1.0

### clutter_text_set_ellipsize ()

    void                clutter_text_set_ellipsize          (ClutterText *self,
                                                             PangoEllipsizeMode mode);

Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there is not enough space to render the entire contents of a ClutterText actor

`self` : | a ClutterText
`mode` : | a PangoEllipsizeMode

Since 1.0

### clutter_text_get_ellipsize ()

    PangoEllipsizeMode  clutter_text_get_ellipsize          (ClutterText *self);

Returns the ellipsizing position of a ClutterText actor, as set by `clutter_text_set_ellipsize()`.

`self` : | a ClutterText
Returns : | PangoEllipsizeMode

Since 1.0

### clutter_text_set_font_name ()

    void                clutter_text_set_font_name          (ClutterText *self,
                                                             const gchar *font_name);

Sets the font used by a ClutterText. The `font_name` string must either be `NULL`, which means that the font name from the default ClutterBackend will be used; or be something that can be parsed by the `pango_font_description_from_string()` function, like:

    1
    2
    3
    clutter_text_set_font_name (text, "Sans 10pt");
    clutter_text_set_font_name (text, "Serif 16px");
    clutter_text_set_font_name (text, "Helvetica 10");

`self` : | a ClutterText
`font_name` : | a font name, or `NULL` to set the default font name. [allow-none]

Since 1.0

### clutter_text_get_font_name ()

    const gchar *       clutter_text_get_font_name          (ClutterText *self);

Retrieves the font name as set by `clutter_text_set_font_name()`.

`self` : | a ClutterText
Returns : | a string containing the font name. The returned string is owned by the ClutterText actor and should not be modified or freed

Since 1.0

### clutter_text_set_font_description ()

    void                clutter_text_set_font_description   (ClutterText *self,
                                                             PangoFontDescription *font_desc);

Sets `font_desc` as the font description for a ClutterText

The PangoFontDescription is copied by the ClutterText actor so you can safely call `pango_font_description_free()` on it after calling this function.

`self` : | a ClutterText
`font_desc` : | a PangoFontDescription

Since 1.2

### clutter_text_get_font_description ()

    PangoFontDescription * clutter_text_get_font_description
                                                            (ClutterText *self);

Retrieves the PangoFontDescription used by `self`

`self` : | a ClutterText
Returns : | a PangoFontDescription. The returned value is owned by the ClutterText actor and it should not be modified or freed

Since 1.2

### clutter_text_set_password_char ()

    void                clutter_text_set_password_char      (ClutterText *self,
                                                             gunichar wc);

Sets the character to use in place of the actual text in a password text actor.

If `wc` is 0 the text will be displayed as it is entered in the ClutterText actor.

`self` : | a ClutterText
`wc` : | a Unicode character, or 0 to unset the password character

Since 1.0

### clutter_text_get_password_char ()

    gunichar            clutter_text_get_password_char      (ClutterText *self);

Retrieves the character to use in place of the actual text as set by `clutter_text_set_password_char()`.

`self` : | a ClutterText
Returns : | a Unicode character or 0 if the password character is not set

Since 1.0

### clutter_text_set_justify ()

    void                clutter_text_set_justify            (ClutterText *self,
                                                             gboolean justify);

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

`self` : | a ClutterText
`justify` : | whether the text should be justified

Since 1.0

### clutter_text_get_justify ()

    gboolean            clutter_text_get_justify            (ClutterText *self);

Retrieves whether the ClutterText actor should justify its contents on both margins.

`self` : | a ClutterText
Returns : | `TRUE` if the text should be justified

Since 0.6

### clutter_text_get_layout ()

    PangoLayout *       clutter_text_get_layout             (ClutterText *self);

Retrieves the current PangoLayout used by a ClutterText actor.

`self` : | a ClutterText
Returns : | a PangoLayout. The returned object is owned by the ClutterText actor and should not be modified or freed. [transfer none]

Since 1.0

### clutter_text_set_line_alignment ()

    void                clutter_text_set_line_alignment     (ClutterText *self,
                                                             PangoAlignment alignment);

Sets the way that the lines of a wrapped label are aligned with respect to each other. This does not affect the overall alignment of the label within its allocated or specified width.

To align a ClutterText actor you should add it to a container that supports alignment, or use the anchor point.

`self` : | a ClutterText
`alignment` : | A PangoAlignment

Since 1.0

### clutter_text_get_line_alignment ()

    PangoAlignment      clutter_text_get_line_alignment     (ClutterText *self);

Retrieves the alignment of a ClutterText, as set by `clutter_text_set_line_alignment()`.

`self` : | a ClutterText
Returns : | a PangoAlignment

Since 1.0

### clutter_text_set_line_wrap ()

    void                clutter_text_set_line_wrap          (ClutterText *self,
                                                             gboolean line_wrap);

Sets whether the contents of a ClutterText actor should wrap, if they don't fit the size assigned to the actor.

`self` : | a ClutterText
`line_wrap` : | whether the contents should wrap

Since 1.0

### clutter_text_get_line_wrap ()

    gboolean            clutter_text_get_line_wrap          (ClutterText *self);

Retrieves the value set using `clutter_text_set_line_wrap()`.

`self` : | a ClutterText
Returns : | `TRUE` if the ClutterText actor should wrap its contents

Since 1.0

### clutter_text_set_line_wrap_mode ()

    void                clutter_text_set_line_wrap_mode     (ClutterText *self,
                                                             PangoWrapMode wrap_mode);

If line wrapping is enabled (see `clutter_text_set_line_wrap()`) this function controls how the line wrapping is performed. The default is `PANGO_WRAP_WORD` which means wrap on word boundaries.

`self` : | a ClutterText
`wrap_mode` : | the line wrapping mode

Since 1.0

### clutter_text_get_line_wrap_mode ()

    PangoWrapMode       clutter_text_get_line_wrap_mode     (ClutterText *self);

Retrieves the line wrap mode used by the ClutterText actor.

See `clutter_text_set_line_wrap_mode()`.

`self` : | a ClutterText
Returns : | the wrap mode used by the ClutterText

Since 1.0

### clutter_text_set_max_length ()

    void                clutter_text_set_max_length         (ClutterText *self,
                                                             gint max);

Sets the maximum allowed length of the contents of the actor. If the current contents are longer than the given length, then they will be truncated to fit.

`self` : | a ClutterText
`max` : | the maximum number of characters allowed in the text actor; 0 to disable or -1 to set the length of the current string

Since 1.0

### clutter_text_get_max_length ()

    gint                clutter_text_get_max_length         (ClutterText *self);

Gets the maximum length of text that can be set into a text actor.

See `clutter_text_set_max_length()`.

`self` : | a ClutterText
Returns : | the maximum number of characters.

Since 1.0

### clutter_text_set_selectable ()

    void                clutter_text_set_selectable         (ClutterText *self,
                                                             gboolean selectable);

Sets whether a ClutterText actor should be selectable.

A selectable ClutterText will allow selecting its contents using the pointer or the keyboard.

`self` : | a ClutterText
`selectable` : | whether the ClutterText actor should be selectable

Since 1.0

### clutter_text_get_selectable ()

    gboolean            clutter_text_get_selectable         (ClutterText *self);

Retrieves whether a ClutterText is selectable or not.

`self` : | a ClutterText
Returns : | `TRUE` if the actor is selectable

Since 1.0

### clutter_text_set_selection ()

    void                clutter_text_set_selection          (ClutterText *self,
                                                             gssize start_pos,
                                                             gssize end_pos);

Selects the region of text between `start_pos` and `end_pos`.

This function changes the position of the cursor to match `start_pos` and the selection bound to match `end_pos`.

`self` : | a ClutterText
`start_pos` : | start of the selection, in characters
`end_pos` : | end of the selection, in characters

Since 1.0

### clutter_text_get_selection ()

    gchar *             clutter_text_get_selection          (ClutterText *self);

Retrieves the currently selected text.

`self` : | a ClutterText
Returns : | a newly allocated string containing the currently selected text, or `NULL`. Use `g_free()` to free the returned string.

Since 1.0

### clutter_text_set_selection_bound ()

    void                clutter_text_set_selection_bound    (ClutterText *self,
                                                             gint selection_bound);

Sets the other end of the selection, starting from the current cursor position.

If `selection_bound` is -1, the selection unset.

`self` : | a ClutterText
`selection_bound` : | the position of the end of the selection, in characters

Since 1.0

### clutter_text_get_selection_bound ()

    gint                clutter_text_get_selection_bound    (ClutterText *self);

Retrieves the other end of the selection of a ClutterText actor, in characters from the current cursor position.

`self` : | a ClutterText
Returns : | the position of the other end of the selection

Since 1.0

### clutter_text_set_single_line_mode ()

    void                clutter_text_set_single_line_mode   (ClutterText *self,
                                                             gboolean single_line);

Sets whether a ClutterText actor should be in single line mode or not. Only editable ClutterTexts can be in single line mode.

A text actor in single line mode will not wrap text and will clip the visible area to the predefined size. The contents of the text actor will scroll to display the end of the text if its length is bigger than the allocated width.

When setting the single line mode the "activatable" property is also set as a side effect. Instead of entering a new line character, the text actor will emit the "activate" signal.

`self` : | a ClutterText
`single_line` : | whether to enable single line mode

Since 1.0

### clutter_text_get_single_line_mode ()

    gboolean            clutter_text_get_single_line_mode   (ClutterText *self);

Retrieves whether the ClutterText actor is in single line mode.

`self` : | a ClutterText
Returns : | `TRUE` if the ClutterText actor is in single line mode

Since 1.0

### clutter_text_set_use_markup ()

    void                clutter_text_set_use_markup         (ClutterText *self,
                                                             gboolean setting);

Sets whether the contents of the ClutterText actor contains markup in Pango's text markup language.

Setting "use-markup" on an editable ClutterText will not have any effect except hiding the markup.

See also "use-markup".

`self` : | a ClutterText
`setting` : | `TRUE` if the text should be parsed for markup.

Since 1.0

### clutter_text_get_use_markup ()

    gboolean            clutter_text_get_use_markup         (ClutterText *self);

Retrieves whether the contents of the ClutterText actor should be parsed for the Pango text markup.

`self` : | a ClutterText
Returns : | `TRUE` if the contents will be parsed for markup

Since 1.0

### clutter_text_set_editable ()

    void                clutter_text_set_editable           (ClutterText *self,
                                                             gboolean editable);

Sets whether the ClutterText actor should be editable.

An editable ClutterText with key focus set using `clutter_actor_grab_key_focus()` or `clutter_stage_take_key_focus()` will receive key events and will update its contents accordingly.

`self` : | a ClutterText
`editable` : | whether the ClutterText should be editable

Since 1.0

### clutter_text_get_editable ()

    gboolean            clutter_text_get_editable           (ClutterText *self);

Retrieves whether a ClutterText is editable or not.

`self` : | a ClutterText
Returns : | `TRUE` if the actor is editable

Since 1.0

### clutter_text_insert_text ()

    void                clutter_text_insert_text            (ClutterText *self,
                                                             const gchar *text,
                                                             gssize position);

Inserts `text` into a ClutterActor at the given position.

If `position` is a negative number, the text will be appended at the end of the current contents of the ClutterText.

The position is expressed in characters, not in bytes.

`self` : | a ClutterText
`text` : | the text to be inserted
`position` : | the position of the insertion, or -1

Since 1.0

### clutter_text_insert_unichar ()

    void                clutter_text_insert_unichar         (ClutterText *self,
                                                             gunichar wc);

Inserts `wc` at the current cursor position of a ClutterText actor.

`self` : | a ClutterText
`wc` : | a Unicode character

Since 1.0

### clutter_text_delete_chars ()

    void                clutter_text_delete_chars           (ClutterText *self,
                                                             guint n_chars);

Deletes `n_chars` inside a ClutterText actor, starting from the current cursor position.

`self` : | a ClutterText
`n_chars` : | the number of characters to delete

Since 1.0

### clutter_text_delete_text ()

    void                clutter_text_delete_text            (ClutterText *self,
                                                             gssize start_pos,
                                                             gssize end_pos);

Deletes the text inside a ClutterText actor between `start_pos` and `end_pos`.

The starting and ending positions are expressed in characters, not in bytes.

`self` : | a ClutterText
`start_pos` : | starting position
`end_pos` : | ending position

Since 1.0

### clutter_text_delete_selection ()

    gboolean            clutter_text_delete_selection       (ClutterText *self);

Deletes the currently selected text

This function is only useful in subclasses of ClutterText

`self` : | a ClutterText
Returns : | `TRUE` if text was deleted or if the text actor is empty, and `FALSE` otherwise

Since 1.0

### clutter_text_get_chars ()

    gchar *             clutter_text_get_chars              (ClutterText *self,
                                                             gssize start_pos,
                                                             gssize end_pos);

Retrieves the contents of the ClutterText actor between `start_pos` and `end_pos`, but not including `end_pos`.

The positions are specified in characters, not in bytes.

`self` : | a ClutterText
`start_pos` : | start of text, in characters
`end_pos` : | end of text, in characters
Returns : | a newly allocated string with the contents of the text actor between the specified positions. Use `g_free()` to free the resources when done

Since 1.0

### clutter_text_set_cursor_color ()

    void                clutter_text_set_cursor_color       (ClutterText *self,
                                                             const ClutterColor *color);

Sets the color of the cursor of a ClutterText actor.

If `color` is `NULL`, the cursor color will be the same as the text color.

`self` : | a ClutterText
`color` : | the color of the cursor, or `NULL` to unset it

Since 1.0

### clutter_text_get_cursor_color ()

    void                clutter_text_get_cursor_color       (ClutterText *self,
                                                             ClutterColor *color);

Retrieves the color of the cursor of a ClutterText actor.

`self` : | a ClutterText
`color` : | return location for a ClutterColor

Since 1.0

### clutter_text_set_selection_color ()

    void                clutter_text_set_selection_color    (ClutterText *self,
                                                             const ClutterColor *color);

Sets the color of the selection of a ClutterText actor.

If `color` is `NULL`, the selection color will be the same as the cursor color, or if no cursor color is set either then it will be the same as the text color.

`self` : | a ClutterText
`color` : | the color of the selection, or `NULL` to unset it

Since 1.0

### clutter_text_get_selection_color ()

    void                clutter_text_get_selection_color    (ClutterText *self,
                                                             ClutterColor *color);

Retrieves the color of the selection of a ClutterText actor.

`self` : | a ClutterText
`color` : | return location for a ClutterColor. [out caller-allocates]

Since 1.0

### clutter_text_set_selected_text_color ()

    void                clutter_text_set_selected_text_color
                                                            (ClutterText *self,
                                                             const ClutterColor *color);

Sets the selected text color of a ClutterText actor.

If `color` is `NULL`, the selected text color will be the same as the selection color, which then falls back to cursor, and then text color.

`self` : | a ClutterText
`color` : | the selected text color, or `NULL` to unset it

Since 1.8

### clutter_text_get_selected_text_color ()

    void                clutter_text_get_selected_text_color
                                                            (ClutterText *self,
                                                             ClutterColor *color);

Retrieves the color of selected text of a ClutterText actor.

`self` : | a ClutterText
`color` : | return location for a ClutterColor. [out caller-allocates]

Since 1.8

### clutter_text_set_cursor_position ()

    void                clutter_text_set_cursor_position    (ClutterText *self,
                                                             gint position);

Sets the cursor of a ClutterText actor at `position`.

The position is expressed in characters, not in bytes.

`self` : | a ClutterText
`position` : | the new cursor position, in characters

Since 1.0

### clutter_text_get_cursor_position ()

    gint                clutter_text_get_cursor_position    (ClutterText *self);

Retrieves the cursor position.

`self` : | a ClutterText
Returns : | the cursor position, in characters

Since 1.0

### clutter_text_set_cursor_visible ()

    void                clutter_text_set_cursor_visible     (ClutterText *self,
                                                             gboolean cursor_visible);

Sets whether the cursor of a ClutterText actor should be visible or not.

The color of the cursor will be the same as the text color unless `clutter_text_set_cursor_color()` has been called.

The size of the cursor can be set using `clutter_text_set_cursor_size()`.

The position of the cursor can be changed programmatically using `clutter_text_set_cursor_position()`.

`self` : | a ClutterText
`cursor_visible` : | whether the cursor should be visible

Since 1.0

### clutter_text_get_cursor_visible ()

    gboolean            clutter_text_get_cursor_visible     (ClutterText *self);

Retrieves whether the cursor of a ClutterText actor is visible.

`self` : | a ClutterText
Returns : | `TRUE` if the cursor is visible

Since 1.0

### clutter_text_set_cursor_size ()

    void                clutter_text_set_cursor_size        (ClutterText *self,
                                                             gint size);

Sets the size of the cursor of a ClutterText. The cursor will only be visible if the "cursor-visible" property is set to `TRUE`.

`self` : | a ClutterText
`size` : | the size of the cursor, in pixels, or -1 to use the default value

Since 1.0

### clutter_text_get_cursor_size ()

    guint               clutter_text_get_cursor_size        (ClutterText *self);

Retrieves the size of the cursor of a ClutterText actor.

`self` : | a ClutterText
Returns : | the size of the cursor, in pixels

Since 1.0

### clutter_text_activate ()

    gboolean            clutter_text_activate               (ClutterText *self);

Emits the "activate" signal, if `self` has been set as activatable using `clutter_text_set_activatable()`.

This function can be used to emit the ::activate signal inside a "captured-event" or "key-press-event" signal handlers before the default signal handler for the ClutterText is invoked.

`self` : | a ClutterText
Returns : | `TRUE` if the ::activate signal has been emitted, and `FALSE` otherwise

Since 1.0

### clutter_text_position_to_coords ()

    gboolean            clutter_text_position_to_coords     (ClutterText *self,
                                                             gint position,
                                                             gfloat *x,
                                                             gfloat *y,
                                                             gfloat *line_height);

Retrieves the coordinates of the given `position`.

`self` : | a ClutterText
`position` : | position in characters
`x` : | return location for the X coordinate, or `NULL`. [out]
`y` : | return location for the Y coordinate, or `NULL`. [out]
`line_height` : | return location for the line height, or `NULL`. [out]
Returns : | `TRUE` if the conversion was successful

Since 1.0

### clutter_text_set_preedit_string ()

    void                clutter_text_set_preedit_string     (ClutterText *self,
                                                             const gchar *preedit_str,
                                                             PangoAttrList *preedit_attrs,
                                                             guint cursor_pos);

Sets, or unsets, the pre-edit string. This function is useful for input methods to display a string (with eventual specific Pango attributes) before it is entered inside the ClutterText buffer.

The preedit string and attributes are ignored if the ClutterText actor is not editable.

This function should not be used by applications

`self` : | a ClutterText
`preedit_str` : | the pre-edit string, or `NULL` to unset it. [allow-none]
`preedit_attrs` : | the pre-edit string attributes. [allow-none]
`cursor_pos` : | the cursor position for the pre-edit string

Since 1.2

### clutter_text_get_layout_offsets ()

    void                clutter_text_get_layout_offsets     (ClutterText *self,
                                                             gint *x,
                                                             gint *y);

Obtains the coordinates where the ClutterText will draw the PangoLayout representing the text.

`self` : | a ClutterText
`x` : | location to store X offset of layout, or `NULL`. [out]
`y` : | location to store Y offset of layout, or `NULL`. [out]

Since 1.7

## Property Details

### The `"activatable"` property

      "activatable"              gboolean              : Read / Write

Toggles whether return invokes the activate signal or not.

Default value: TRUE

Since 1.0

### The `"attributes"` property

      "attributes"               PangoAttrList*        : Read / Write

A list of PangoStyleAttributes to be applied to the contents of the ClutterText actor.

Since 1.0

### The `"color"` property

      "color"                    ClutterColor*         : Read / Write

The color used to render the text.

Since 1.0

### The `"cursor-color"` property

      "cursor-color"             ClutterColor*         : Read / Write

The color of the cursor.

Since 1.0

### The `"cursor-color-set"` property

      "cursor-color-set"         gboolean              : Read

Will be set to `TRUE` if "cursor-color" has been set.

Default value: FALSE

Since 1.0

### The `"cursor-size"` property

      "cursor-size"              gint                  : Read / Write

The size of the cursor, in pixels. If set to -1 the size used will be the default cursor size of 2 pixels.

Allowed values: >= -1

Default value: 2

Since 1.0

### The `"cursor-visible"` property

      "cursor-visible"           gboolean              : Read / Write

Whether the input cursor is visible or not, it will only be visible if both "cursor-visible" and "editable" are set to `TRUE`.

Default value: TRUE

Since 1.0

### The `"editable"` property

      "editable"                 gboolean              : Read / Write

Whether key events delivered to the actor causes editing.

Default value: FALSE

Since 1.0

### The `"ellipsize"` property

      "ellipsize"                PangoEllipsizeMode    : Read / Write

The preferred place to ellipsize the contents of the ClutterText actor

Default value: PANGO_ELLIPSIZE_NONE

Since 1.0

### The `"font-description"` property

      "font-description"         PangoFontDescription*  : Read / Write

The PangoFontDescription that should be used by the ClutterText

If you have a string describing the font then you should look at "font-name" instead

Since 1.2

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

      "font-name"                gchar*                : Read / Write

The font to be used by the ClutterText, as a string that can be parsed by `pango_font_description_from_string()`.

If set to `NULL`, the default system font will be used instead.

Default value: NULL

Since 1.0

### The `"justify"` property

      "justify"                  gboolean              : Read / Write

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

Default value: FALSE

Since 1.0

### The `"line-alignment"` property

      "line-alignment"           PangoAlignment        : Read / Write

The preferred alignment for the text. This property controls the alignment of multi-line paragraphs.

Default value: PANGO_ALIGN_LEFT

Since 1.0

### The `"line-wrap"` property

      "line-wrap"                gboolean              : Read / Write

Whether to wrap the lines of "text" if the contents exceed the available allocation. The wrapping strategy is controlled by the "line-wrap-mode" property.

Default value: FALSE

Since 1.0

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

      "line-wrap-mode"           PangoWrapMode         : Read / Write

If "line-wrap" is set to `TRUE`, this property will control how the text is wrapped.

Default value: PANGO_WRAP_WORD

Since 1.0

### The `"max-length"` property

      "max-length"               gint                  : Read / Write

The maximum length of the contents of the ClutterText actor.

Allowed values: >= -1

Default value: 0

Since 1.0

### The `"password-char"` property

      "password-char"            guint                 : Read / Write

If non-zero, the character that should be used in place of the actual text in a password text actor.

Default value: 0

Since 1.0

### The `"position"` property

      "position"                 gint                  : Read / Write

The current input cursor position. -1 is taken to be the end of the text

Allowed values: >= -1

Default value: -1

Since 1.0

### The `"selectable"` property

      "selectable"               gboolean              : Read / Write

Whether it is possible to select text, either using the pointer or the keyboard.

Default value: TRUE

Since 1.0

### The `"selected-text-color"` property

      "selected-text-color"      ClutterColor*         : Read / Write

The color of selected text.

Since 1.8

### The `"selected-text-color-set"` property

      "selected-text-color-set"  gboolean              : Read

Will be set to `TRUE` if "selected-text-color" has been set.

Default value: FALSE

Since 1.8

### The `"selection-bound"` property

      "selection-bound"          gint                  : Read / Write

The current input cursor position. -1 is taken to be the end of the text

Allowed values: >= -1

Default value: -1

Since 1.0

### The `"selection-color"` property

      "selection-color"          ClutterColor*         : Read / Write

The color of the selection.

Since 1.0

### The `"selection-color-set"` property

      "selection-color-set"      gboolean              : Read

Will be set to `TRUE` if "selection-color" has been set.

Default value: FALSE

Since 1.0

### The `"single-line-mode"` property

      "single-line-mode"         gboolean              : Read / Write

Whether the ClutterText actor should be in single line mode or not. A single line ClutterText actor will only contain a single line of text, scrolling it in case its length is bigger than the allocated size.

Setting this property will also set the "activatable" property as a side-effect.

The "single-line-mode" property is used only if the "editable" property is set to `TRUE`.

Default value: FALSE

Since 1.0

### The `"text"` property

      "text"                     gchar*                : Read / Write

The text to render inside the actor.

Default value: ""

Since 1.0

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

      "use-markup"               gboolean              : Read / Write

Whether the text includes Pango markup.

For more informations about the Pango markup format, see `pango_layout_set_markup()` in the Pango documentation.

### Note

It is not possible to round-trip this property between `TRUE` and `FALSE`. Once a string with markup has been set on a ClutterText actor with :use-markup set to `TRUE`, the markup is stripped from the string.

Default value: FALSE

Since 1.0

## Signal Details

### The `"activate"` signal

    void                user_function                      (ClutterText *self,
                                                            gpointer     user_data)      : Run Last

The ::activate signal is emitted each time the actor is 'activated' by the user, normally by pressing the 'Enter' key. The signal is emitted only if "activatable" is set to `TRUE`.

`self` : | the ClutterText that emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.0

### The `"cursor-event"` signal

    void                user_function                      (ClutterText     *self,
                                                            ClutterGeometry *geometry,
                                                            gpointer         user_data)      : Run Last

The ::cursor-event signal is emitted whenever the cursor position changes inside a ClutterText actor. Inside `geometry` it is stored the current position and size of the cursor, relative to the actor itself.

`self` : | the ClutterText that emitted the signal
`geometry` : | the coordinates of the cursor
`user_data` : | user data set when the signal handler was connected.

Since 1.0

### The `"delete-text"` signal

    void                user_function                      (ClutterText *self,
                                                            gint         start_pos,
                                                            gint         end_pos,
                                                            gpointer     user_data)      : Action

This signal is emitted when text is deleted from the actor by the user. It is emitted before `self` text changes.

`self` : | the ClutterText that emitted the signal
`start_pos` : | the starting position
`end_pos` : | the end position
`user_data` : | user data set when the signal handler was connected.

Since 1.2

### The `"insert-text"` signal

    void                user_function                      (ClutterText *self,
                                                            gchar       *new_text,
                                                            gint         new_text_length,
                                                            gpointer     position,
                                                            gpointer     user_data)            : Action

This signal is emitted when text is inserted into the actor by the user. It is emitted before `self` text changes.

`self` : | the ClutterText that emitted the signal
`new_text` : | the new text to insert
`new_text_length` : | the length of the new text, in bytes, or -1 if new_text is nul-terminated
`position` : | the position, in characters, at which to insert the new text. this is an in-out parameter. After the signal emission is finished, it should point after the newly inserted text.
`user_data` : | user data set when the signal handler was connected.

Since 1.2

### The `"text-changed"` signal

    void                user_function                      (ClutterText *self,
                                                            gpointer     user_data)      : Run Last

The ::text-changed signal is emitted after `actor`'s text changes

`self` : | the ClutterText that emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.0