Gtk.Editable
Description: Reference for Gtk.Editable

### Interface

# GtkEditable

since: 4.0

#### Description [src]

    interface Gtk.Editable : Gtk.Widget

`GtkEditable` is an interface for text editing widgets.

Typical examples of editable widgets are `GtkEntry` and `GtkSpinButton`. It 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 modify the behavior of a widget.

As an example of the latter usage, by connecting the following handler to `GtkEditable::insert-text`, an application can convert all entry into a widget into uppercase.

## Forcing entry to uppercase.

    #include <ctype.h>

    void
    insert_text_handler (GtkEditable *editable,
                         const char  *text,
                         int          length,
                         int         *position,
                         gpointer     data)
    {
      char *result = g_utf8_strup (text, length);

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

      g_signal_stop_emission_by_name (editable, "insert_text");

      g_free (result);
    }

## Implementing GtkEditable

The most likely scenario for implementing `GtkEditable` on your own widget is that you will embed a `GtkText` inside a complex widget, and want to delegate the editable functionality to that text widget. `GtkEditable` provides some utility functions to make this easy.

In your class_init function, call `gtk_editable_install_properties()`, passing the first available property ID:

    static void
    my_class_init (MyClass *class)
    {
      ...
      g_object_class_install_properties (object_class, NUM_PROPERTIES, props);
      gtk_editable_install_properties (object_clas, NUM_PROPERTIES);
      ...
    }

In your interface_init function for the `GtkEditable` interface, provide an implementation for the get_delegate vfunc that returns your text widget:

    GtkEditable *
    get_editable_delegate (GtkEditable *editable)
    {
      return GTK_EDITABLE (MY_WIDGET (editable)->text_widget);
    }

    static void
    my_editable_init (GtkEditableInterface *iface)
    {
      iface->get_delegate = get_editable_delegate;
    }

You don’t need to provide any other vfuncs. The default implementations work by forwarding to the delegate that the GtkEditableInterface.get_delegate() vfunc returns.

In your instance_init function, create your text widget, and then call `gtk_editable_init_delegate()`:

    static void
    my_widget_init (MyWidget *self)
    {
      ...
      self->text_widget = gtk_text_new ();
      gtk_editable_init_delegate (GTK_EDITABLE (self));
      ...
    }

In your dispose function, call `gtk_editable_finish_delegate()` before destroying your text widget:

    static void
    my_widget_dispose (GObject *object)
    {
      ...
      gtk_editable_finish_delegate (GTK_EDITABLE (self));
      g_clear_pointer (&self->text_widget, gtk_widget_unparent);
      ...
    }

Finally, use `gtk_editable_delegate_set_property()` in your `set_property` function (and similar for `get_property`), to set the editable properties:

      ...
      if (gtk_editable_delegate_set_property (object, prop_id, value, pspec))
        return;

      switch (prop_id)
      ...

It is important to note that if you create a `GtkEditable` that uses a delegate, the low level `GtkEditable::insert-text` and `GtkEditable::delete-text` signals will be propagated from the “wrapper” editable to the delegate, but they will not be propagated from the delegate to the “wrapper” editable, as they would cause an infinite recursion. If you wish to connect to the `GtkEditable::insert-text` and `GtkEditable::delete-text` signals, you will need to connect to them on the delegate obtained via `gtk_editable_get_delegate()`.

Available since: 4.0

#### Prerequisite

In order to implement Editable, your type must inherit from`GtkWidget`.

#### Implementations

- GtkEditableLabel
- GtkEntry
- GtkPasswordEntry
- GtkSearchEntry
- GtkSpinButton
- GtkText

#### Functions

###### gtk_editable_delegate_get_property

Gets a property of the `GtkEditable` delegate for `object`.

since: 4.0

###### gtk_editable_delegate_set_property

Sets a property on the `GtkEditable` delegate for `object`.

since: 4.0

###### gtk_editable_install_properties

Overrides the `GtkEditable` properties for `class`.

since: 4.0

#### Instance methods

###### gtk_editable_delegate_get_accessible_platform_state

Retrieves the accessible platform state from the editable delegate.

since: 4.10

###### gtk_editable_delete_selection

Deletes the currently selected text of the editable.

since: 4.0

###### gtk_editable_delete_text

Deletes a sequence of characters.

since: 4.0

###### gtk_editable_finish_delegate

Undoes the setup done by `gtk_editable_init_delegate()`.

since: 4.0

###### gtk_editable_get_alignment

Gets the alignment of the editable.

since: 4.0

###### gtk_editable_get_chars

Retrieves a sequence of characters.

since: 4.0

###### gtk_editable_get_delegate

Gets the `GtkEditable` that `editable` is delegating its implementation to.

since: 4.0

###### gtk_editable_get_editable

Retrieves whether `editable` is editable.

since: 4.0

###### gtk_editable_get_enable_undo

Gets if undo/redo actions are enabled for `editable`.

since: 4.0

###### gtk_editable_get_max_width_chars

Retrieves the desired maximum width of `editable`, in characters.

since: 4.0

###### gtk_editable_get_position

Retrieves the current position of the cursor relative to the start of the content of the editable.

since: 4.0

###### gtk_editable_get_selection_bounds

Retrieves the selection bound of the editable.

since: 4.0

###### gtk_editable_get_text

Retrieves the contents of `editable`.

since: 4.0

###### gtk_editable_get_width_chars

Gets the number of characters of space reserved for the contents of the editable.

since: 4.0

###### gtk_editable_init_delegate

Sets up a delegate for `GtkEditable`.

since: 4.0

###### gtk_editable_insert_text

Inserts `length` bytes of `text` into the contents of the widget, at position `position`.

since: 4.0

###### gtk_editable_select_region

Selects a region of text.

since: 4.0

###### gtk_editable_set_alignment

Sets the alignment for the contents of the editable.

since: 4.0

###### gtk_editable_set_editable

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

since: 4.0

###### gtk_editable_set_enable_undo

If enabled, changes to `editable` will be saved for undo/redo actions.

since: 4.0

###### gtk_editable_set_max_width_chars

Sets the desired maximum width in characters of `editable`.

since: 4.0

###### gtk_editable_set_position

Sets the cursor position in the editable to the given value.

since: 4.0

###### gtk_editable_set_text

Sets the text in the editable to the given value.

since: 4.0

###### gtk_editable_set_width_chars

Changes the size request of the editable to be about the right size for `n_chars` characters.

since: 4.0

#### Properties

###### Gtk.Editable:cursor-position

The current position of the insertion cursor in chars.

since: 4.0

###### Gtk.Editable:editable

Whether the entry contents can be edited.

since: 4.0

###### Gtk.Editable:enable-undo

If undo/redo should be enabled for the editable.

since: 4.0

###### Gtk.Editable:max-width-chars

The desired maximum width of the entry, in characters.

since: 4.0

###### Gtk.Editable:selection-bound

The position of the opposite end of the selection from the cursor in chars.

since: 4.0

###### Gtk.Editable:text

The contents of the entry.

since: 4.0

###### Gtk.Editable:width-chars

Number of characters to leave space for in the entry.

since: 4.0

###### Gtk.Editable:xalign

The horizontal alignment, from 0 (left) to 1 (right).

since: 4.0

#### Signals

###### Gtk.Editable::changed

Emitted at the end of a single user-visible operation on the contents.

since: 4.0

###### Gtk.Editable::delete-text

Emitted when text is deleted from the widget by the user.

since: 4.0

###### Gtk.Editable::insert-text

Emitted when text is inserted into the widget by the user.

since: 4.0

#### Interface structure

    struct GtkEditableInterface {
      GTypeInterface base_iface;
      void (* insert_text) (
        GtkEditable* editable,
        const char* text,
        int length,
        int* position
      );
      void (* delete_text) (
        GtkEditable* editable,
        int start_pos,
        int end_pos
      );
      void (* changed) (
        GtkEditable* editable
      );
      const char* (* get_text) (
        GtkEditable* editable
      );
      void (* do_insert_text) (
        GtkEditable* editable,
        const char* text,
        int length,
        int* position
      );
      void (* do_delete_text) (
        GtkEditable* editable,
        int start_pos,
        int end_pos
      );
      gboolean (* get_selection_bounds) (
        GtkEditable* editable,
        int* start_pos,
        int* end_pos
      );
      void (* set_selection_bounds) (
        GtkEditable* editable,
        int start_pos,
        int end_pos
      );
      GtkEditable* (* get_delegate) (
        GtkEditable* editable
      );

    }

No description available.

###### Interface members

`base_iface` |
    GTypeInterface
| No description available.
`insert_text` |
    void (* insert_text) (
        GtkEditable* editable,
        const char* text,
        int length,
        int* position
      )
| No description available.
`delete_text` |
    void (* delete_text) (
        GtkEditable* editable,
        int start_pos,
        int end_pos
      )
| No description available.
`changed` |
    void (* changed) (
        GtkEditable* editable
      )
| No description available.
`get_text` |
    const char* (* get_text) (
        GtkEditable* editable
      )
| No description available.
`do_insert_text` |
    void (* do_insert_text) (
        GtkEditable* editable,
        const char* text,
        int length,
        int* position
      )
| No description available.
`do_delete_text` |
    void (* do_delete_text) (
        GtkEditable* editable,
        int start_pos,
        int end_pos
      )
| No description available.
`get_selection_bounds` |
    gboolean (* get_selection_bounds) (
        GtkEditable* editable,
        int* start_pos,
        int* end_pos
      )
| No description available.
`set_selection_bounds` |
    void (* set_selection_bounds) (
        GtkEditable* editable,
        int start_pos,
        int end_pos
      )
| No description available.
`get_delegate` |
    GtkEditable* (* get_delegate) (
        GtkEditable* editable
      )
| No description available.

#### Virtual methods

###### Gtk.Editable.changed

No description available.

since: 4.0

###### Gtk.Editable.delete_text

Deletes a sequence of characters.

since: 4.0

###### Gtk.Editable.do_delete_text

Deletes a sequence of characters.

since: 4.0

###### Gtk.Editable.do_insert_text

Inserts `length` bytes of `text` into the contents of the widget, at position `position`.

since: 4.0

###### Gtk.Editable.get_delegate

Gets the `GtkEditable` that `editable` is delegating its implementation to.

since: 4.0

###### Gtk.Editable.get_selection_bounds

Retrieves the selection bound of the editable.

since: 4.0

###### Gtk.Editable.get_text

Retrieves the contents of `editable`.

since: 4.0

###### Gtk.Editable.insert_text

Inserts `length` bytes of `text` into the contents of the widget, at position `position`.

since: 4.0

###### Gtk.Editable.set_selection_bounds

Selects a region of text.

since: 4.0