ClutterText: Clutter Reference Manual

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

## Functions

ClutterActor * | clutter_text_new ()
ClutterActor * | clutter_text_new_full ()
ClutterActor * | clutter_text_new_with_text ()
ClutterActor * | clutter_text_new_with_buffer ()
void | clutter_text_set_buffer ()
ClutterTextBuffer * | clutter_text_get_buffer ()
void | clutter_text_set_text ()
void | clutter_text_set_markup ()
const gchar * | clutter_text_get_text ()
void | clutter_text_set_activatable ()
gboolean | clutter_text_get_activatable ()
void | clutter_text_set_attributes ()
PangoAttrList * | clutter_text_get_attributes ()
void | clutter_text_set_color ()
void | clutter_text_get_color ()
void | clutter_text_set_ellipsize ()
PangoEllipsizeMode | clutter_text_get_ellipsize ()
void | clutter_text_set_font_name ()
const gchar * | clutter_text_get_font_name ()
void | clutter_text_set_font_description ()
PangoFontDescription * | clutter_text_get_font_description ()
void | clutter_text_set_password_char ()
gunichar | clutter_text_get_password_char ()
void | clutter_text_set_justify ()
gboolean | clutter_text_get_justify ()
PangoLayout * | clutter_text_get_layout ()
void | clutter_text_set_line_alignment ()
PangoAlignment | clutter_text_get_line_alignment ()
void | clutter_text_set_line_wrap ()
gboolean | clutter_text_get_line_wrap ()
void | clutter_text_set_line_wrap_mode ()
PangoWrapMode | clutter_text_get_line_wrap_mode ()
void | clutter_text_set_max_length ()
gint | clutter_text_get_max_length ()
void | clutter_text_set_selectable ()
gboolean | clutter_text_get_selectable ()
void | clutter_text_set_selection ()
gchar * | clutter_text_get_selection ()
void | clutter_text_set_selection_bound ()
gint | clutter_text_get_selection_bound ()
void | clutter_text_set_single_line_mode ()
gboolean | clutter_text_get_single_line_mode ()
void | clutter_text_set_use_markup ()
gboolean | clutter_text_get_use_markup ()
void | clutter_text_set_editable ()
gboolean | clutter_text_get_editable ()
void | clutter_text_insert_text ()
void | clutter_text_insert_unichar ()
void | clutter_text_delete_chars ()
void | clutter_text_delete_text ()
gboolean | clutter_text_delete_selection ()
gchar * | clutter_text_get_chars ()
void | clutter_text_set_cursor_color ()
void | clutter_text_get_cursor_color ()
void | clutter_text_set_selection_color ()
void | clutter_text_get_selection_color ()
void | clutter_text_set_selected_text_color ()
void | clutter_text_get_selected_text_color ()
void | clutter_text_set_cursor_position ()
gint | clutter_text_get_cursor_position ()
void | clutter_text_set_cursor_visible ()
gboolean | clutter_text_get_cursor_visible ()
void | clutter_text_set_cursor_size ()
guint | clutter_text_get_cursor_size ()
void | clutter_text_get_cursor_rect ()
gboolean | clutter_text_activate ()
gint | clutter_text_coords_to_position ()
gboolean | clutter_text_position_to_coords ()
void | clutter_text_set_preedit_string ()
void | clutter_text_get_layout_offsets ()

## Properties

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

## Signals

void | activate | Run Last
void | cursor-changed | Run Last
void | cursor-event | Run Last
void | delete-text | Action
void | insert-text | Action
void | text-changed | Run Last

## Types and Values

struct | ClutterText
struct | ClutterTextClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActor
                ╰── ClutterText

## Implemented Interfaces

ClutterText implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## 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

## Functions

### 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()`.

#### Parameters

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()`.

#### Parameters

font_name | a string with a font description. | [allow-none]
text | the contents of the actor |

#### Returns

the newly created ClutterText actor

Since: 1.0

### clutter_text_new_with_buffer ()

    ClutterActor *
    clutter_text_new_with_buffer (ClutterTextBuffer *buffer);

Creates a new entry with the specified text buffer.

#### Parameters

buffer | The buffer to use for the new ClutterText. |

#### Returns

a new ClutterText

Since: 1.10

### clutter_text_set_buffer ()

    void
    clutter_text_set_buffer (ClutterText *self,
                             ClutterTextBuffer *buffer);

Set the ClutterTextBuffer object which holds the text for this widget.

#### Parameters

self | a ClutterText |
buffer | a ClutterTextBuffer |

Since: 1.10

### clutter_text_get_buffer ()

    ClutterTextBuffer *
    clutter_text_get_buffer (ClutterText *self);

Get the ClutterTextBuffer object which holds the text for this widget.

#### Parameters

self | a ClutterText |

#### Returns

A GtkEntryBuffer object.

[transfer none]

Since: 1.10

### 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

#### Parameters

self | a ClutterText |
text | the text to set. Passing `NULL` is the same as passing "" (the empty string). | [allow-none]

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
    3
    /* the order is important */
    clutter_text_set_text (CLUTTER_TEXT (actor), markup);
    clutter_text_set_use_markup (CLUTTER_TEXT (actor), TRUE);

#### Parameters

self | a ClutterText |
markup | a string containing Pango markup. Passing `NULL` is the same as passing "" (the empty string). | [allow-none]

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.

If the ClutterText actor is empty, this function will return an empty string, and not `NULL`.

#### Parameters

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.

[transfer none]

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

self | a ClutterText |
attrs | a PangoAttrList or `NULL` to unset the attributes. | [allow-none]

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.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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

#### Parameters

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()`.

#### Parameters

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
    4
    5
    6
    7
    8
    // Set the font to the system's Sans, 10 points
    clutter_text_set_font_name (text, "Sans 10");

    // Set the font to the system's Serif, 16 pixels
    clutter_text_set_font_name (text, "Serif 16px");

    // Set the font to Helvetica, 10 points
    clutter_text_set_font_name (text, "Helvetica 10");

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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`

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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”.

#### Parameters

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.

#### Parameters

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_set_key_focus()` will receive key events and will update its contents accordingly.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

Somewhat awkwardly, the cursor position is decremented by the same number of characters you've deleted.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

self | a ClutterText |
color | the color of the cursor, or `NULL` to unset it. | [allow-none]

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.

#### Parameters

self | a ClutterText |
color | return location for a ClutterColor. | [out]

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.

#### Parameters

self | a ClutterText |
color | the color of the selection, or `NULL` to unset it. | [allow-none]

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.

#### Parameters

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.

#### Parameters

self | a ClutterText |
color | the selected text color, or `NULL` to unset it. | [allow-none]

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

self | a ClutterText |

#### Returns

the size of the cursor, in pixels

Since: 1.0

### clutter_text_get_cursor_rect ()

    void
    clutter_text_get_cursor_rect (ClutterText *self,
                                  ClutterRect *rect);

Retrieves the rectangle that contains the cursor.

The coordinates of the rectangle's origin are in actor-relative coordinates.

#### Parameters

self | a ClutterText |
rect | return location of a ClutterRect. | [out caller-allocates]

Since: 1.16

### 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.

#### Parameters

self | a ClutterText |

#### Returns

`TRUE` if the ::activate signal has been emitted, and `FALSE` otherwise

Since: 1.0

### clutter_text_coords_to_position ()

    gint
    clutter_text_coords_to_position (ClutterText *self,
                                     gfloat x,
                                     gfloat y);

Retrieves the position of the character at the given coordinates.

Return: the position of the character

#### Parameters

self | a ClutterText |
x | the X coordinate, relative to the actor |
y | the Y coordinate, relative to the actor |

Since: 1.10

### 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` .

#### Parameters

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

#### Parameters

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.

#### Parameters

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.8

## Types and Values

### 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);
      void (* cursor_changed) (ClutterText           *self);
    };

The ClutterTextClass struct contains only private data.

#### Members

`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 |
`cursor_changed` () | class handler for the “cursor-changed” signal |

Since: 1.0

## Property Details

### The `“activatable”` property

      “activatable”              gboolean

Toggles whether return invokes the activate signal or not.

Flags: Read / Write

Default value: TRUE

Since: 1.0

### The `“attributes”` property

      “attributes”               PangoAttrList *

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

Flags: Read / Write

Since: 1.0

### The `“buffer”` property

      “buffer”                   ClutterTextBuffer *

The buffer which stores the text for this ClutterText.

If set to `NULL`, a default buffer will be created.

Flags: Read / Write

Since: 1.8

### The `“color”` property

      “color”                    ClutterColor *

The color used to render the text.

Flags: Read / Write

Since: 1.0

### The `“cursor-color”` property

      “cursor-color”             ClutterColor *

The color of the cursor.

Flags: Read / Write

Since: 1.0

### The `“cursor-color-set”` property

      “cursor-color-set”         gboolean

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

Flags: Read

Default value: FALSE

Since: 1.0

### The `“cursor-position”` property

      “cursor-position”          gint

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

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since: 1.12

### The `“cursor-size”` property

      “cursor-size”              gint

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

Flags: Read / Write

Allowed values: >= -1

Default value: 2

Since: 1.0

### The `“cursor-visible”` property

      “cursor-visible”           gboolean

Whether the input cursor is visible or not.

The cursor will only be visible if this property and either the “editable” or the “selectable” properties are set to `TRUE`.

Flags: Read / Write

Default value: TRUE

Since: 1.0

### The `“editable”` property

      “editable”                 gboolean

Whether key events delivered to the actor causes editing.

Flags: Read / Write

Default value: FALSE

Since: 1.0

### The `“ellipsize”` property

      “ellipsize”                PangoEllipsizeMode

The preferred place to ellipsize the contents of the ClutterText actor

Flags: Read / Write

Default value: PANGO_ELLIPSIZE_NONE

Since: 1.0

### The `“font-description”` property

      “font-description”         PangoFontDescription *

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

Flags: Read / Write

Since: 1.2

### The `“font-name”` property

      “font-name”                gchar *

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.

Flags: Read / Write

Default value: NULL

Since: 1.0

### The `“justify”` property

      “justify”                  gboolean

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

Flags: Read / Write

Default value: FALSE

Since: 1.0

### The `“line-alignment”` property

      “line-alignment”           PangoAlignment

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

Flags: Read / Write

Default value: PANGO_ALIGN_LEFT

Since: 1.0

### The `“line-wrap”` property

      “line-wrap”                gboolean

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.

Flags: Read / Write

Default value: FALSE

Since: 1.0

### The `“line-wrap-mode”` property

      “line-wrap-mode”           PangoWrapMode

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

Flags: Read / Write

Default value: PANGO_WRAP_WORD

Since: 1.0

### The `“max-length”` property

      “max-length”               gint

The maximum length of the contents of the ClutterText actor.

Flags: Read / Write

Allowed values: >= -1

Default value: 0

Since: 1.0

### The `“password-char”` property

      “password-char”            guint

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

Flags: Read / Write

Default value: 0

Since: 1.0

### The `“position”` property

      “position”                 gint

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

`ClutterText:position` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterText:cursor-position instead.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since: 1.0

### The `“selectable”` property

      “selectable”               gboolean

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

This property depends on the “reactive” property being set to `TRUE`.

Flags: Read / Write

Default value: TRUE

Since: 1.0

### The `“selected-text-color”` property

      “selected-text-color”      ClutterColor *

The color of selected text.

Flags: Read / Write

Since: 1.8

### The `“selected-text-color-set”` property

      “selected-text-color-set”  gboolean

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

Flags: Read

Default value: FALSE

Since: 1.8

### The `“selection-bound”` property

      “selection-bound”          gint

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

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since: 1.0

### The `“selection-color”` property

      “selection-color”          ClutterColor *

The color of the selection.

Flags: Read / Write

Since: 1.0

### The `“selection-color-set”` property

      “selection-color-set”      gboolean

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

Flags: Read

Default value: FALSE

Since: 1.0

### The `“single-line-mode”` property

      “single-line-mode”         gboolean

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`.

Flags: Read / Write

Default value: FALSE

Since: 1.0

### The `“text”` property

      “text”                     gchar *

The text to render inside the actor.

Flags: Read / Write

Default value: ""

Since: 1.0

### The `“use-markup”` property

      “use-markup”               gboolean

Whether the text includes Pango markup.

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

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.

Flags: Read / Write

Default value: FALSE

Since: 1.0

## Signal Details

### The `“activate”` signal

    void
    user_function (ClutterText *self,
                   gpointer     user_data)

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`.

#### Parameters

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

Flags: Run Last

Since: 1.0

### The `“cursor-changed”` signal

    void
    user_function (ClutterText *self,
                   gpointer     user_data)

The ::cursor-changed signal is emitted whenever the cursor position or size changes.

#### Parameters

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

Flags: Run Last

Since: 1.16

### The `“cursor-event”` signal

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

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.

`ClutterText::cursor-event` has been deprecated since version 1.16 and should not be used in newly-written code.

Use the “cursor-changed” signal instead

#### Parameters

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

Flags: Run Last

Since: 1.0

### The `“delete-text”` signal

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

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

#### Parameters

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. |

Flags: Action

Since: 1.2

### The `“insert-text”` signal

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

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

#### Parameters

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. |

Flags: Action

Since: 1.2

### The `“text-changed”` signal

    void
    user_function (ClutterText *self,
                   gpointer     user_data)

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

#### Parameters

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

Flags: Run Last

Since: 1.0