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.