## ClutterEntry

ClutterEntry — A single line text entry actor

## Synopsis

                        ClutterEntry;
                        ClutterEntryClass;
    ClutterActor*       clutter_entry_new                   (void);
    ClutterActor*       clutter_entry_new_with_text         (const gchar *font_name,
                                                             const gchar *text);
    ClutterActor*       clutter_entry_new_full              (const gchar *font_name,
                                                             const gchar *text,
                                                             const ClutterColor *color);
    void                clutter_entry_set_text              (ClutterEntry *entry,
                                                             const gchar *text);
    const gchar*        clutter_entry_get_text              (ClutterEntry *entry);
    void                clutter_entry_set_font_name         (ClutterEntry *entry,
                                                             const gchar *font_name);
    const gchar*        clutter_entry_get_font_name         (ClutterEntry *entry);
    void                clutter_entry_set_color             (ClutterEntry *entry,
                                                             const ClutterColor *color);
    void                clutter_entry_get_color             (ClutterEntry *entry,
                                                             ClutterColor *color);
    PangoLayout*        clutter_entry_get_layout            (ClutterEntry *entry);
    void                clutter_entry_set_alignment         (ClutterEntry *entry,
                                                             PangoAlignment alignment);
    PangoAlignment      clutter_entry_get_alignment         (ClutterEntry *entry);
    void                clutter_entry_set_cursor_position   (ClutterEntry *entry,
                                                             gint position);
    gint                clutter_entry_get_cursor_position   (ClutterEntry *entry);
    void                clutter_entry_handle_key_event      (ClutterEntry *entry,
                                                             ClutterKeyEvent *kev);
    void                clutter_entry_insert_unichar        (ClutterEntry *entry,
                                                             gunichar wc);
    void                clutter_entry_delete_chars          (ClutterEntry *entry,
                                                             guint len);
    void                clutter_entry_insert_text           (ClutterEntry *entry,
                                                             const gchar *text,
                                                             gssize position);
    void                clutter_entry_delete_text           (ClutterEntry *entry,
                                                             gssize start_pos,
                                                             gssize end_pos);
    void                clutter_entry_set_visible_cursor    (ClutterEntry *entry,
                                                             gboolean visible);
    gboolean            clutter_entry_get_visible_cursor    (ClutterEntry *entry);
    void                clutter_entry_set_visibility        (ClutterEntry *entry,
                                                             gboolean visible);
    gboolean            clutter_entry_get_visibility        (ClutterEntry *entry);
    void                clutter_entry_set_invisible_char    (ClutterEntry *entry,
                                                             gunichar wc);
    gunichar            clutter_entry_get_invisible_char    (ClutterEntry *entry);
    void                clutter_entry_set_max_length        (ClutterEntry *entry,
                                                             gint max);
    gint                clutter_entry_get_max_length        (ClutterEntry *entry);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----ClutterEntry

## Implemented Interfaces

ClutterEntry implements

## Properties

      "alignment"                PangoAlignment        : Read / Write
      "color"                    ClutterColor*         : Read / Write
      "cursor-visible"           gboolean              : Read / Write
      "entry-padding"            guint                 : Read / Write
      "font-name"                gchar*                : Read / Write
      "max-length"               gint                  : Read / Write
      "position"                 gint                  : Read / Write
      "text"                     gchar*                : Read / Write
      "text-visible"             gboolean              : Read / Write
      "x-align"                  gdouble               : Read / Write

## Signals

      "activate"                                       : Run Last
      "cursor-event"                                   : Run Last
      "text-changed"                                   : Run Last

## Description

ClutterEntry is a ClutterTexture that allows single line text entry.

ClutterEntry is available since Clutter 0.4.

## Details

### ClutterEntry

    typedef struct _ClutterEntry ClutterEntry;

### ClutterEntryClass

    typedef struct {
      /* vfuncs, not signals */
      void (* paint_cursor) (ClutterEntry    *entry);

      /* signals */
      void (* text_changed) (ClutterEntry    *entry);
      void (* cursor_event) (ClutterEntry    *entry,
                             ClutterGeometry *geometry);
      void (* activate)     (ClutterEntry    *entry);
    } ClutterEntryClass;

Class fo entry actors.

`paint_cursor` () | virtual function for subclasses to use to draw a custom cursor instead of the default one
`text_changed` () | signal class handler for ClutterEntry::text-changed
`cursor_event` () | signal class handler for ClutterEntry::cursor-event
`activate` () | signal class handler for ClutterEntry::activate

Since 0.4

### clutter_entry_new ()

    ClutterActor*       clutter_entry_new                   (void);

Creates a new, empty ClutterEntry.

Returns : | the newly created ClutterEntry

### clutter_entry_new_with_text ()

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

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

`font_name` : | the name (and size) of the font to be used
`text` : | the text to be displayed
Returns : | the newly created ClutterEntry

Since 0.4

### clutter_entry_new_full ()

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

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

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

Since 0.4

### clutter_entry_set_text ()

    void                clutter_entry_set_text              (ClutterEntry *entry,
                                                             const gchar *text);

Sets `text` as the text to be displayed by `entry`. The ClutterEntry::text-changed signal is emitted.

`entry` : | a ClutterEntry
`text` : | the text to be displayed

Since 0.4

### clutter_entry_get_text ()

    const gchar*        clutter_entry_get_text              (ClutterEntry *entry);

Retrieves the text displayed by `entry`.

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

Since 0.4

### clutter_entry_set_font_name ()

    void                clutter_entry_set_font_name         (ClutterEntry *entry,
                                                             const gchar *font_name);

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

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

`entry` : | a ClutterEntry
`font_name` : | a font name and size, or `NULL` for the default font

Since 0.4

### clutter_entry_get_font_name ()

    const gchar*        clutter_entry_get_font_name         (ClutterEntry *entry);

Retrieves the font used by `entry`.

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

Since 0.4

### clutter_entry_set_color ()

    void                clutter_entry_set_color             (ClutterEntry *entry,
                                                             const ClutterColor *color);

Sets the color of `entry`.

`entry` : | a ClutterEntry
`color` : | a ClutterColor

Since 0.4

### clutter_entry_get_color ()

    void                clutter_entry_get_color             (ClutterEntry *entry,
                                                             ClutterColor *color);

Retrieves the color of `entry`.

`entry` : | a ClutterEntry
`color` : | return location for a ClutterColor

Since 0.4

### clutter_entry_get_layout ()

    PangoLayout*        clutter_entry_get_layout            (ClutterEntry *entry);

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

`entry` : | a ClutterEntry
Returns : | the PangoLayout for this entry

Since 0.4

### clutter_entry_set_alignment ()

    void                clutter_entry_set_alignment         (ClutterEntry *entry,
                                                             PangoAlignment alignment);

Sets text alignment of the entry.

`entry` : | a ClutterEntry
`alignment` : | A PangoAlignment

Since 0.4

### clutter_entry_get_alignment ()

    PangoAlignment      clutter_entry_get_alignment         (ClutterEntry *entry);

Returns the entry's text alignment

`entry` : | a ClutterEntry
Returns : | The entry's PangoAlignment Since 0.4

### clutter_entry_set_cursor_position ()

    void                clutter_entry_set_cursor_position   (ClutterEntry *entry,
                                                             gint position);

Sets the position of the cursor. The `position` must be less than or equal to the number of characters in the entry. A value of -1 indicates that the position should be set after the last character in the entry. Note that this position is in characters, not in bytes.

`entry` : | a ClutterEntry
`position` : | the position of the cursor.

Since 0.6

### clutter_entry_get_cursor_position ()

    gint                clutter_entry_get_cursor_position   (ClutterEntry *entry);

Gets the position, in characters, of the cursor in `entry`.

`entry` : | a ClutterEntry
Returns : | the position of the cursor.

Since 0.6

### clutter_entry_handle_key_event ()

    void                clutter_entry_handle_key_event      (ClutterEntry *entry,
                                                             ClutterKeyEvent *kev);

### Warning

`clutter_entry_handle_key_event` has been deprecated since version 0.8 and should not be used in newly-written code. The key events will automatically be handled when giving the key focus to an entry using `clutter_stage_set_key_focus()`.

This function will handle a ClutterKeyEvent, like those returned in a key-press/release-event, and will translate it for the `entry`. This includes non-alphanumeric keys, such as the arrows keys, which will move the input cursor. You should use this function inside a handler for the ClutterStage::key-press-event or ClutterStage::key-release-event.

`entry` : | a ClutterEntry
`kev` : | a ClutterKeyEvent

Since 0.4

### clutter_entry_insert_unichar ()

    void                clutter_entry_insert_unichar        (ClutterEntry *entry,
                                                             gunichar wc);

Insert a character to the right of the current position of the cursor, and updates the position of the cursor.

`entry` : | a ClutterEntry
`wc` : | a Unicode character

Since 0.4

### clutter_entry_delete_chars ()

    void                clutter_entry_delete_chars          (ClutterEntry *entry,
                                                             guint len);

Characters are removed from before the current postion of the cursor.

`entry` : | a ClutterEntry
`len` : | the number of characters to remove.

Since 0.4

### clutter_entry_insert_text ()

    void                clutter_entry_insert_text           (ClutterEntry *entry,
                                                             const gchar *text,
                                                             gssize position);

Insert text at a specifc position.

A value of 0 indicates that the text will be inserted before the first character in the entry's text, and a value of -1 indicates that the text will be inserted after the last character in the entry's text.

`entry` : | a ClutterEntry
`text` : | the text to insert
`position` : | the position at which to insert the text.

Since 0.4

### clutter_entry_delete_text ()

    void                clutter_entry_delete_text           (ClutterEntry *entry,
                                                             gssize start_pos,
                                                             gssize end_pos);

Deletes a sequence of characters. The characters that are deleted are those characters at positions from `start_pos` up to, but not including, `end_pos`. If `end_pos` is negative, then the characters deleted will be those characters from `start_pos` to the end of the text.

`entry` : | a ClutterEntry
`start_pos` : | the starting position.
`end_pos` : | the end position.

Since 0.4

### clutter_entry_set_visible_cursor ()

    void                clutter_entry_set_visible_cursor    (ClutterEntry *entry,
                                                             gboolean visible);

Sets the visibility of the input cursor.

`entry` : | a ClutterEntry
`visible` : | whether the input cursor should be visible

Since 0.4

### clutter_entry_get_visible_cursor ()

    gboolean            clutter_entry_get_visible_cursor    (ClutterEntry *entry);

Returns the input cursor's visibility

`entry` : | a ClutterEntry
Returns : | whether the input cursor is visible

Since 0.4

### clutter_entry_set_visibility ()

    void                clutter_entry_set_visibility        (ClutterEntry *entry,
                                                             gboolean visible);

Sets whether the contents of the entry are visible or not. When visibility is set to `FALSE`, characters are displayed as the invisible char, and will also appear that way when the text in the entry widget is copied elsewhere.

The default invisible char is the asterisk '*', but it can be changed with `clutter_entry_set_invisible_char()`.

`entry` : | a ClutterEntry
`visible` : | `TRUE` if the contents of the entry are displayed as plaintext.

Since 0.4

### clutter_entry_get_visibility ()

    gboolean            clutter_entry_get_visibility        (ClutterEntry *entry);

Returns the entry text visibility.

`entry` : | a ClutterEntry
Returns : | `TRUE` if the contents of the entry are displayed as plaintext.

Since 0.4

### clutter_entry_set_invisible_char ()

    void                clutter_entry_set_invisible_char    (ClutterEntry *entry,
                                                             gunichar wc);

Sets the character to use in place of the actual text when `clutter_entry_set_visibility()` has been called to set text visibility to `FALSE`. i.e. this is the character used in "password mode" to show the user how many characters have been typed. The default invisible char is an asterisk ('*'). If you set the invisible char to 0, then the user will get no feedback at all; there will be no text on the screen as they type.

`entry` : | a ClutterEntry
`wc` : | a Unicode character

Since 0.4

### clutter_entry_get_invisible_char ()

    gunichar            clutter_entry_get_invisible_char    (ClutterEntry *entry);

Returns the character to use in place of the actual text when text-visibility is set to `FALSE`

`entry` : | a ClutterEntry
Returns : | a Unicode character

### clutter_entry_set_max_length ()

    void                clutter_entry_set_max_length        (ClutterEntry *entry,
                                                             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.

`entry` : | a ClutterEntry
`max` : | the maximum number of characters allowed in the entry; 0 to disable or -1 to set the length of the current string

Since 0.4

### clutter_entry_get_max_length ()

    gint                clutter_entry_get_max_length        (ClutterEntry *entry);

Gets the maximum length of text that can be set into `entry`. See `clutter_entry_set_max_length()`.

`entry` : | a ClutterEntry
Returns : | the maximum number of characters.

Since 0.4

## Property Details

### The `"alignment"` property

      "alignment"                PangoAlignment        : Read / Write

The preferred alignment for the string.

Default value: PANGO_ALIGN_LEFT

Since 0.4

### The `"color"` property

      "color"                    ClutterColor*         : Read / Write

The color of the text inside the entry.

Since 0.4

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

      "cursor-visible"           gboolean              : Read / Write

Whether the input cursor is visible or not.

Default value: TRUE

Since 0.4

### The `"entry-padding"` property

      "entry-padding"            guint                 : Read / Write

The padding space between the text and the entry right and left borders.

Default value: 5

Since 0.4

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

      "font-name"                gchar*                : Read / Write

The font to be used by the entry, expressed in a string that can be parsed by `pango_font_description_from_string()`.

Default value: NULL

Since 0.4

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

      "max-length"               gint                  : Read / Write

The maximum length of the entry text.

Allowed values: >= 0

Default value: 0

Since 0.4

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

### The `"text"` property

      "text"                     gchar*                : Read / Write

The text inside the entry.

Default value: NULL

Since 0.4

### The `"text-visible"` property

      "text-visible"             gboolean              : Read / Write

Whether the text is visible in plain form, or replaced by the character set by `clutter_entry_set_invisible_char()`.

Default value: TRUE

Since 0.4

### The `"x-align"` property

      "x-align"                  gdouble               : Read / Write

Horizontal alignment to be used for the text (0.0 for left alignment, 1.0 for right alignment).

Allowed values: [0,1]

Default value: 0

Since 0.6

## Signal Details

### The `"activate"` signal

    void                user_function                      (ClutterEntry *entry,
                                                            gpointer      user_data)      : Run Last

The ::activate signal is emitted each time the entry is 'activated' by the user, normally by pressing the 'Enter' key.

`entry` : | the actor which received the event
`user_data` : | user data set when the signal handler was connected.

Since 0.4

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

    void                user_function                      (ClutterEntry    *entry,
                                                            ClutterGeometry *geometry,
                                                            gpointer         user_data)      : Run Last

The ::cursor-event signal is emitted each time the input cursor's geometry changes, this could be a positional or size change. If you would like to implement your own input cursor, set the cursor-visible property to `FALSE`, and connect to this signal to position and size your own cursor.

`entry` : | the actor which received the event
`geometry` : | a ClutterGeometry
`user_data` : | user data set when the signal handler was connected.

Since 0.4

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

    void                user_function                      (ClutterEntry *entry,
                                                            gpointer      user_data)      : Run Last

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

`entry` : | the actor which received the event
`user_data` : | user data set when the signal handler was connected.