GtkEditable

Name

GtkEditable -- Base class for text-editing widgets.

Synopsis


#include <gtk/gtk.h>


struct      GtkEditable;
void        gtk_editable_select_region      (GtkEditable *editable,
                                             gint start,
                                             gint end);
gboolean    gtk_editable_get_selection_bounds
                                            (GtkEditable *editable,
                                             gint *start,
                                             gint *end);
void        gtk_editable_insert_text        (GtkEditable *editable,
                                             const gchar *new_text,
                                             gint new_text_length,
                                             gint *position);
void        gtk_editable_delete_text        (GtkEditable *editable,
                                             gint start_pos,
                                             gint end_pos);
gchar*      gtk_editable_get_chars          (GtkEditable *editable,
                                             gint start_pos,
                                             gint end_pos);
void        gtk_editable_cut_clipboard      (GtkEditable *editable);
void        gtk_editable_copy_clipboard     (GtkEditable *editable);
void        gtk_editable_paste_clipboard    (GtkEditable *editable);
void        gtk_editable_delete_selection   (GtkEditable *editable);
void        gtk_editable_set_position       (GtkEditable *editable,
                                             gint position);
gint        gtk_editable_get_position       (GtkEditable *editable);
void        gtk_editable_set_editable       (GtkEditable *editable,
                                             gboolean is_editable);
gboolean    gtk_editable_get_editable       (GtkEditable *editable);


Signal Prototypes


"changed"   void        user_function      (GtkEditable *editable,
                                            gpointer user_data);
"delete-text"
            void        user_function      (GtkEditable *editable,
                                            gint start_pos,
                                            gint end_pos,
                                            gpointer user_data);
"insert-text"
            void        user_function      (GtkEditable *editable,
                                            gchar *new_text,
                                            gint new_text_length,
                                            gint *position,
                                            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];

  g_signal_handlers_block_by_func (GTK_OBJECT (editable), 
				   insert_text_handler, data);
  gtk_editable_insert_text (editable, result, length, position);
  g_signal_handlers_unblock_by_func (GTK_OBJECT (editable), 
                                     insert_text_handler, data);

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

  g_free (result);
}

Details

struct GtkEditable

struct GtkEditable;

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


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.


gtk_editable_get_selection_bounds ()

gboolean    gtk_editable_get_selection_bounds
                                            (GtkEditable *editable,
                                             gint *start,
                                             gint *end);

Gets the current selection bounds, if there is a selection.


gtk_editable_insert_text ()

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

Inserts text at a given position.


gtk_editable_delete_text ()

void        gtk_editable_delete_text        (GtkEditable *editable,
                                             gint start_pos,
                                             gint 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 the characters deleted will be those characters from start_pos to the end of the text.


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.


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.


gtk_editable_copy_clipboard ()

void        gtk_editable_copy_clipboard     (GtkEditable *editable);

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


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.


gtk_editable_delete_selection ()

void        gtk_editable_delete_selection   (GtkEditable *editable);

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


gtk_editable_set_position ()

void        gtk_editable_set_position       (GtkEditable *editable,
                                             gint position);

Sets the cursor position.


gtk_editable_get_position ()

gint        gtk_editable_get_position       (GtkEditable *editable);

Retrieves the current cursor position.


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.


gtk_editable_get_editable ()

gboolean    gtk_editable_get_editable       (GtkEditable *editable);

Retrieves whether editable is editable. See gtk_editable_set_editable().

Signals

The "changed" signal

void        user_function                  (GtkEditable *editable,
                                            gpointer user_data);

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


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


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.