GtkEditable

GTK+ Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

Object Hierarchy

  GtkObject
   +----GtkWidget
         +----GtkEditable

Args

  "text_position"        gint                 : Read / Write
  "editable"             gboolean             : Read / Write

Signal Prototypes

"changed"   void        user_function      (GtkEditable *editable,
                                            gpointer user_data);
"insert-text"
            void        user_function      (GtkEditable *editable,
                                            gchar *new_text,
                                            gint new_text_length,
                                            gint *position,
                                            gpointer user_data);
"delete-text"
            void        user_function      (GtkEditable *editable,
                                            gint start_pos,
                                            gint end_pos,
                                            gpointer user_data);
"activate"  void        user_function      (GtkEditable *editable,
                                            gpointer user_data);
"set-editable"
            void        user_function      (GtkEditable *editable,
                                            gboolean is_editable,
                                            gpointer user_data);
"move-cursor"
            void        user_function      (GtkEditable *editable,
                                            gint x,
                                            gint y,
                                            gpointer user_data);
"move-word" void        user_function      (GtkEditable *editable,
                                            gint num_words,
                                            gpointer user_data);
"move-page" void        user_function      (GtkEditable *editable,
                                            gint x,
                                            gint y,
                                            gpointer user_data);
"move-to-row"
            void        user_function      (GtkEditable *editable,
                                            gint row,
                                            gpointer user_data);
"move-to-column"
            void        user_function      (GtkEditable *editable,
                                            gint column,
                                            gpointer user_data);
"kill-char" void        user_function      (GtkEditable *editable,
                                            gint direction,
                                            gpointer user_data);
"kill-word" void        user_function      (GtkEditable *editable,
                                            gint direction,
                                            gpointer user_data);
"kill-line" void        user_function      (GtkEditable *editable,
                                            gint direction,
                                            gpointer user_data);
"cut-clipboard"
            void        user_function      (GtkEditable *editable,
                                            gpointer user_data);
"copy-clipboard"
            void        user_function      (GtkEditable *editable,
                                            gpointer user_data);
"paste-clipboard"
            void        user_function      (GtkEditable *editable,
                                            gpointer user_data);

Description

The GtkEditable class is a base class for widgets for editing text, such as GtkEntry and GtkText. It cannot be instantiated by itself. The editable class contains functions for generically manipulating an editable widget, a large number of action signals used for key bindings, and several signals that an application can connect to to modify the behavior of a widget.

As an example of the latter usage, by connecting the following handler to "insert_text", an application can convert all entry into a widget into uppercase.

Example 1. Forcing entry to uppercase

include <ctype.h>

void
insert_text_handler (GtkEditable *editable,
                     const gchar *text,
                     gint         length,
                     gint        *position,
                     gpointer     data)
{
  int i;
  gchar *result = g_new (gchar, length);

  for (i=0; i<length; i++)
    result[i] = islower(text[i]) ? toupper(text[i]) : text[i];

  gtk_signal_handler_block_by_func (GTK_OBJECT (editable),
				    GTK_SIGNAL_FUNC (insert_text_handler),
				    data);
  gtk_editable_insert_text (editable, result, length, position);
  gtk_signal_handler_unblock_by_func (GTK_OBJECT (editable),
				      GTK_SIGNAL_FUNC (insert_text_handler),
				      data);

  gtk_signal_emit_stop_by_name (GTK_OBJECT (editable), "insert_text");

  g_free (result);
}

Details

struct GtkEditable

struct GtkEditable {
  guint      current_pos;

  guint      selection_start_pos;
  guint      selection_end_pos;
  guint      has_selection : 1;

};

The GtkEditable structure contains the following fields. (These fields should be considered read-only. They should never be set by an application.)

guint selection_start;	the starting position of the selected characters in the widget.
guint selection_end;	the end position of the selected characters in the widget.
guint editable;	a flag indicating whether or not the widget is editable by the user.

GtkTextFunction ()

void        (*GtkTextFunction)              (GtkEditable *editable,
                                             guint32 time);

Callback function for old method of setting key bindings. No longer publically used.

`editable` :
`time` :

gtk_editable_select_region ()

void        gtk_editable_select_region      (GtkEditable *editable,
                                             gint start,
                                             gint end);

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

`editable` :	a GtkEditable widget.
`start` :	the starting position.
`end` :	the end position.

gtk_editable_insert_text ()

void        gtk_editable_insert_text        (GtkEditable *editable,
                                             const gchar *new_text,
                                             gint new_text_length,
                                             gint *position);

Insert text at a given position.

`editable` :	a GtkEditable widget.
`new_text` :	the text to insert.
`new_text_length` :	the length of the text to insert, in bytes
`position` :	an inout parameter. The caller initializes it to the position at which to insert the text. After the call it points at the position after the newly inserted text.

gtk_editable_delete_text ()

void        gtk_editable_delete_text        (GtkEditable *editable,
                                             gint start_pos,
                                             gint end_pos);

Delete 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 the characters deleted will be those characters from start_pos to the end of the text.

`editable` :	a GtkEditable widget.
`start_pos` :	the starting position.
`end_pos` :	the end position.

gtk_editable_get_chars ()

gchar*      gtk_editable_get_chars          (GtkEditable *editable,
                                             gint start_pos,
                                             gint end_pos);

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

`editable` :	a GtkEditable widget.
`start_pos` :	the starting position.
`end_pos` :	the end position.
Returns :	the characters in the indicated region. The result must be freed with g_free() when the application is finished with it.

gtk_editable_cut_clipboard ()

void        gtk_editable_cut_clipboard      (GtkEditable *editable);

Causes the characters in the current selection to be copied to the clipboard and then deleted from the widget.

editable : a GtkEditable widget.

gtk_editable_copy_clipboard ()

void        gtk_editable_copy_clipboard     (GtkEditable *editable);

Causes the characters in the current selection to be copied to the clipboard.

editable : a GtkEditable widget.

gtk_editable_paste_clipboard ()

void        gtk_editable_paste_clipboard    (GtkEditable *editable);

Causes the contents of the clipboard to be pasted into the given widget at the current cursor position.

editable : a GtkEditable widget.

gtk_editable_claim_selection ()

void        gtk_editable_claim_selection    (GtkEditable *editable,
                                             gboolean claim,
                                             guint32 time);

Claim or disclaim ownership of the PRIMARY X selection.

`editable` :	a GtkEditable widget.
`claim` :	if `TRUE`, claim the selection, otherwise, disclaim it.
`time` :	the timestamp for claiming the selection.

gtk_editable_delete_selection ()

void        gtk_editable_delete_selection   (GtkEditable *editable);

Deletes the current contents of the widgets selection and disclaims the selection.

editable : a GtkEditable widget.

gtk_editable_changed ()

void        gtk_editable_changed            (GtkEditable *editable);

Causes the "changed" signal to be emitted.

editable : a GtkEditable widget.

gtk_editable_set_position ()

void        gtk_editable_set_position       (GtkEditable *editable,
                                             gint position);

Sets the cursor position.

`editable` :	a GtkEditable widget.
`position` :	the position of the cursor. The cursor is displayed before the character with the given (base 0) index in the widget. The value must be less than or equal to the number of characters in the widget. 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.

gtk_editable_get_position ()

gint        gtk_editable_get_position       (GtkEditable *editable);

Retrieves the current cursor position.

`editable` :	a GtkEditable widget.
Returns :	the position of the cursor. The cursor is displayed before the character with the given (base 0) index in the widget. The value will be less than or equal to the number of characters in the widget. Note that this position is in characters, not in bytes.

gtk_editable_set_editable ()

void        gtk_editable_set_editable       (GtkEditable *editable,
                                             gboolean is_editable);

Determines if the user can edit the text in the editable widget or not.

`editable` :	a GtkEditable widget.
`is_editable` :	`TRUE` if the user is allowed to edit the text in the widget.

Args

"text_position" (gint : Read / Write): The position of the cursor.
"editable" (gboolean : Read / Write): A boolean indicating whether the widget is editable by the user.

Signals

The "changed" signal

void        user_function                  (GtkEditable *editable,
                                            gpointer user_data);

Indicates that the user has changed the contents of the widget.

`editable` :	the object which received the signal.
`user_data` :	user data set when the signal handler was connected.

The "insert-text" signal

void        user_function                  (GtkEditable *editable,
                                            gchar *new_text,
                                            gint new_text_length,
                                            gint *position,
                                            gpointer user_data);

This signal is emitted when text is inserted into the widget by the user. The default handler for this signal will normally be responsible for inserting the text, so by connecting to this signal and then stopping the signal with gtk_signal_emit_stop(), it is possible to modify the inserted text, or prevent it from being inserted entirely.

`editable` :	the object which received the signal.
`new_text` :	the new text to insert.
`new_text_length` :	the length of the new text.
`position` :	the position at which to insert the new text. this is an in-out paramter. 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.

The "delete-text" signal

void        user_function                  (GtkEditable *editable,
                                            gint start_pos,
                                            gint end_pos,
                                            gpointer user_data);

This signal is emitted when text is deleted from the widget by the user. The default handler for this signal will normally be responsible for inserting the text, so by connecting to this signal and then stopping the signal with gtk_signal_emit_stop(), it is possible to modify the inserted text, or prevent it from being inserted entirely. The start_pos and end_pos parameters are interpreted as for gtk_editable_delete_text()

`editable` :	the object which received the signal.
`start_pos` :	the starting position.
`end_pos` :	the end position.
`user_data` :	user data set when the signal handler was connected.

The "activate" signal

void        user_function                  (GtkEditable *editable,
                                            gpointer user_data);

Indicates that the user has activated the widget in some fashion. Generally, this will be done with a keystroke. (The default binding for this action is Return for GtkEntry and Control-Return for GtkText.)

`editable` :	the object which received the signal.
`user_data` :	user data set when the signal handler was connected.

The "set-editable" signal

void        user_function                  (GtkEditable *editable,
                                            gboolean is_editable,
                                            gpointer user_data);

Determines if the user can edit the text in the editable widget or not. This is meant to be overriden by child classes and should not generally useful to applications.

`editable` :	the object which received the signal.
`is_editable` :	`TRUE` if the user is allowed to edit the text in the widget.
`user_data` :	user data set when the signal handler was connected.

The "move-cursor" signal

void        user_function                  (GtkEditable *editable,
                                            gint x,
                                            gint y,
                                            gpointer user_data);

An action signal. Move the cursor position.

`editable` :	the object which received the signal.
`x` :	horizontal distance to move the cursor.
`y` :	vertical distance to move the cursor.
`user_data` :	user data set when the signal handler was connected.

The "move-word" signal

void        user_function                  (GtkEditable *editable,
                                            gint num_words,
                                            gpointer user_data);

An action signal. Move the cursor by words.

`editable` :	the object which received the signal.
`num_words` :	The number of words to move the cursor. (Can be negative).
`user_data` :	user data set when the signal handler was connected.

The "move-page" signal

void        user_function                  (GtkEditable *editable,
                                            gint x,
                                            gint y,
                                            gpointer user_data);

An action signal. Move the cursor by pages.

`editable` :	the object which received the signal.
`x` :	Number of pages to move the cursor horizontally.
`y` :	Number of pages to move the cursor vertically.
`user_data` :	user data set when the signal handler was connected.

The "move-to-row" signal

void        user_function                  (GtkEditable *editable,
                                            gint row,
                                            gpointer user_data);

An action signal. Move the cursor to the given row.

`editable` :	the object which received the signal.
`row` :	the row to move to. (A negative value indicates the last row)
`user_data` :	user data set when the signal handler was connected.

The "move-to-column" signal

void        user_function                  (GtkEditable *editable,
                                            gint column,
                                            gpointer user_data);

An action signal. Move the cursor to the given column.

`editable` :	the object which received the signal.
`column` :	the column to move to. (A negative value indicates the last column)
`user_data` :	user data set when the signal handler was connected.

The "kill-char" signal

void        user_function                  (GtkEditable *editable,
                                            gint direction,
                                            gpointer user_data);

An action signal. Delete a single character.

`editable` :	the object which received the signal.
`direction` :	the direction in which to delete. Positive indicates forward deletion, negative, backwards deletion.
`user_data` :	user data set when the signal handler was connected.

The "kill-word" signal

void        user_function                  (GtkEditable *editable,
                                            gint direction,
                                            gpointer user_data);

An action signal. Delete a single word.

`editable` :	the object which received the signal.
`direction` :	the direction in which to delete. Positive indicates forward deletion, negative, backwards deletion.
`user_data` :	user data set when the signal handler was connected.

The "kill-line" signal

void        user_function                  (GtkEditable *editable,
                                            gint direction,
                                            gpointer user_data);

An action signal. Delete a single line.

`editable` :	the object which received the signal.
`direction` :	the direction in which to delete. Positive indicates forward deletion, negative, backwards deletion.
`user_data` :	user data set when the signal handler was connected.

The "cut-clipboard" signal

void        user_function                  (GtkEditable *editable,
                                            gpointer user_data);

An action signal. Causes the characters in the current selection to be copied to the clipboard and then deleted from the widget.

`editable` :	the object which received the signal.
`user_data` :	user data set when the signal handler was connected.

The "copy-clipboard" signal

void        user_function                  (GtkEditable *editable,
                                            gpointer user_data);

An action signal. Causes the characters in the current selection to be copied to the clipboard.

`editable` :	the object which received the signal.
`user_data` :	user data set when the signal handler was connected.

The "paste-clipboard" signal

void        user_function                  (GtkEditable *editable,
                                            gpointer user_data);

An action signal. Causes the contents of the clipboard to be pasted into the editable widget at the current cursor position.

`editable` :	the object which received the signal.
`user_data` :	user data set when the signal handler was connected.

GtkEditable

Name

Synopsis

Object Hierarchy

Args

Signal Prototypes

Description

Details

struct GtkEditable

GtkTextFunction ()

gtk_editable_select_region ()

gtk_editable_insert_text ()

gtk_editable_delete_text ()

gtk_editable_get_chars ()

gtk_editable_cut_clipboard ()

gtk_editable_copy_clipboard ()

gtk_editable_paste_clipboard ()

gtk_editable_claim_selection ()

gtk_editable_delete_selection ()

gtk_editable_changed ()

gtk_editable_set_position ()

gtk_editable_get_position ()

gtk_editable_set_editable ()

Args

Signals

The "changed" signal

The "insert-text" signal

The "delete-text" signal

The "activate" signal

The "set-editable" signal

The "move-cursor" signal

The "move-word" signal

The "move-page" signal

The "move-to-row" signal

The "move-to-column" signal

The "kill-char" signal

The "kill-word" signal

The "kill-line" signal

The "cut-clipboard" signal

The "copy-clipboard" signal

The "paste-clipboard" signal