ClutterEntry

ClutterEntry — A single line text entry actor

Synopsis




                    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_position          (ClutterEntry *entry,
                                                         gint position);
gint                clutter_entry_get_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);


Description

ClutterEntry is a ClutterTexture that allows single line text entry.

In order to update the contents of the entry with the text inserted by the user you should connect to the ClutterStage::key-press-event and forward the ClutterKeyEvent received by the ClutterStage to the ClutterEntry you want to update, using clutter_entry_handle_key_event().

ClutterEntry is available since Clutter 0.4.

Details

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 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 entrys PangoAlignment Since 0.4

clutter_entry_set_position ()

void                clutter_entry_set_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.4


clutter_entry_get_position ()

gint                clutter_entry_get_position          (ClutterEntry *entry);

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

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

Since 0.4


clutter_entry_handle_key_event ()

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

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 entrys text, and a value of -1 indicates that the text will be inserted after the last character in the entrys 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 cursors visiblity

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 visiblity

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, or -1 to disable

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