Package ch.bailu.gtk.gtk

Class Editable

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.type.Interface
ch.bailu.gtk.gtk.Editable
All Implemented Interfaces:
PointerInterface
public class Editable extends Interface
`GtkEditable` is an interface for text editing widgets.

Typical examples of editable widgets are [class@Gtk.Entry] and
[class@Gtk.SpinButton]. 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
[signal@Gtk.Editable::insert-text], an application can convert all entry
into a widget into uppercase.

## Forcing entry to uppercase.

```c
#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 [func@Gtk.Editable.install_properties],
passing the first available property ID:

```c
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:

```c
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
[method@Gtk.Editable.init_delegate]:

```c
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 [method@Gtk.Editable.finish_delegate] before
destroying your text widget:

```c
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 [func@Gtk.Editable.delegate_set_property] in your `set_property`
function (and similar for `get_property`), to set the editable properties:

```c
...
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 [signal@Gtk.Editable::insert-text] and
[signal@Gtk.Editable::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 [signal@Gtk.Editable::insert-text]
and [signal@Gtk.Editable::delete-text] signals, you will need to connect
to them on the delegate obtained via [method@Gtk.Editable.get_delegate].

https://docs.gtk.org/gtk4/iface.Editable.html

  • Field Details

  • Constructor Details

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • deleteSelection

      public void deleteSelection()
      Deletes the currently selected text of the editable.

      This call doesn’t do anything if there is no selected text.

    • deleteText

      public void deleteText(int start_pos, int 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 are those from @start_pos to
      the end of the text.

      Note that the positions are specified in characters, not bytes.
      Parameters:
      start_pos - start position
      end_pos - end position

    • finishDelegate

      public void finishDelegate()
      Undoes the setup done by [method@Gtk.Editable.init_delegate].

      This is a helper function that should be called from dispose,
      before removing the delegate object.

    • getAlignment

      public float getAlignment()
      Gets the alignment of the editable.
      Returns:
      the alignment

    • getChars

      public Str getChars(int start_pos, int 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 characters retrieved are those characters from @start_pos to
      the end of the text.

      Note that positions are specified in characters, not bytes.
      Parameters:
      start_pos - start of text
      end_pos - end of text
      Returns:
      a pointer to the contents of the widget as a string. This string is allocated by the `GtkEditable` implementation and should be freed by the caller.

    • getDelegate

      public Editable getDelegate()
      Gets the `GtkEditable` that @editable is delegating its
      implementation to.

      Typically, the delegate is a [class@Gtk.Text] widget.
      Returns:
      the delegate `GtkEditable`

    • getEditable

      public boolean getEditable()
      Retrieves whether @editable is editable.
      Returns:
      %TRUE if @editable is editable.

    • getEnableUndo

      public boolean getEnableUndo()
      Gets if undo/redo actions are enabled for @editable
      Returns:
      %TRUE if undo is enabled

    • getMaxWidthChars

      public int getMaxWidthChars()
      Retrieves the desired maximum width of @editable, in characters.
      Returns:
      the maximum width of the entry, in characters

    • getPosition

      public int getPosition()
      Retrieves the current position of the cursor relative
      to the start of the content of the editable.

      Note that this position is in characters, not in bytes.
      Returns:
      the cursor position

    • getSelectionBounds

      public boolean getSelectionBounds(@Nullable Int start_pos, @Nullable Int end_pos)
      Retrieves the selection bound of the editable.

      @start_pos will be filled with the start of the selection and
      @end_pos with end. If no text was selected both will be identical
      and %FALSE will be returned.

      Note that positions are specified in characters, not bytes.
      Parameters:
      start_pos - location to store the starting position
      end_pos - location to store the end position
      Returns:
      %TRUE if there is a non-empty selection, %FALSE otherwise

    • getText

      public Str getText()
      Retrieves the contents of @editable.

      The returned string is owned by GTK and must not be modified or freed.
      Returns:
      a pointer to the contents of the editable

    • getWidthChars

      public int getWidthChars()
      Gets the number of characters of space reserved
      for the contents of the editable.
      Returns:
      number of chars to request space for, or negative if unset

    • initDelegate

      public void initDelegate()
      Sets up a delegate for `GtkEditable`.

      This is assuming that the get_delegate vfunc in the `GtkEditable`
      interface has been set up for the @editable's type.

      This is a helper function that should be called in instance init,
      after creating the delegate object.

    • insertText

      public void insertText(@Nonnull Str text, int length, @Nonnull Int position)
      Inserts @length bytes of @text into the contents of the
      widget, at position @position.

      Note that the position is in characters, not in bytes.
      The function updates @position to point after the newly
      inserted text.
      Parameters:
      text - the text to append
      length - the length of the text in bytes, or -1
      position - location of the position text will be inserted at

    • insertText

      public void insertText(String text, int length, @Nonnull Int position)
      Inserts @length bytes of @text into the contents of the
      widget, at position @position.

      Note that the position is in characters, not in bytes.
      The function updates @position to point after the newly
      inserted text.
      Parameters:
      text - the text to append
      length - the length of the text in bytes, or -1
      position - location of the position text will be inserted at

    • selectRegion

      public void selectRegion(int start_pos, int end_pos)
      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 characters selected are those characters from
      @start_pos to the end of the text.

      Note that positions are specified in characters, not bytes.
      Parameters:
      start_pos - start of region
      end_pos - end of region

    • setAlignment

      public void setAlignment(float xalign)
      Sets the alignment for the contents of the editable.

      This controls the horizontal positioning of the contents when
      the displayed text is shorter than the width of the editable.
      Parameters:
      xalign - The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts

    • setEditable

      public void setEditable(boolean is_editable)
      Determines if the user can edit the text in the editable widget.
      Parameters:
      is_editable - %TRUE if the user is allowed to edit the text in the widget

    • setEnableUndo

      public void setEnableUndo(boolean enable_undo)
      If enabled, changes to @editable will be saved for undo/redo
      actions.

      This results in an additional copy of text changes and are not
      stored in secure memory. As such, undo is forcefully disabled
      when [property@Gtk.Text:visibility] is set to %FALSE.
      Parameters:
      enable_undo - if undo/redo should be enabled

    • setMaxWidthChars

      public void setMaxWidthChars(int n_chars)
      Sets the desired maximum width in characters of @editable.
      Parameters:
      n_chars - the new desired maximum width, in characters

    • setPosition

      public void setPosition(int position)
      Sets the cursor position in the editable to the given value.

      The cursor is displayed before the character with the given (base 0)
      index in the contents of the editable. The value must be less than
      or equal to the number of characters in the editable. A value of -1
      indicates that the position should be set after the last character
      of the editable. Note that @position is in characters, not in bytes.
      Parameters:
      position - the position of the cursor

    • setText

      public void setText(@Nonnull Str text)
      Sets the text in the editable to the given value.

      This is replacing the current contents.
      Parameters:
      text - the text to set

    • setText

      public void setText(String text)
      Sets the text in the editable to the given value.

      This is replacing the current contents.
      Parameters:
      text - the text to set

    • setWidthChars

      public void setWidthChars(int n_chars)
      Changes the size request of the editable to be about the
      right size for @n_chars characters.

      Note that it changes the size request, the size can still
      be affected by how you pack the widget into containers.
      If @n_chars is -1, the size reverts to the default size.
      Parameters:
      n_chars - width in chars

    • onChanged

      public SignalHandler onChanged(Editable.OnChanged signal)
      Connect to signal "changed".
      See Editable.OnChanged.onChanged() for signal description.
      Field SIGNAL_ON_CHANGED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onDeleteText

      public SignalHandler onDeleteText(Editable.OnDeleteText signal)
      Connect to signal "delete-text".
      See Editable.OnDeleteText.onDeleteText(int, int) for signal description.
      Field SIGNAL_ON_DELETE_TEXT contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onInsertText

      public SignalHandler onInsertText(Editable.OnInsertText signal)
      Connect to signal "insert-text".
      See Editable.OnInsertText.onInsertText(ch.bailu.gtk.type.Str, int, ch.bailu.gtk.type.Pointer) for signal description.
      Field SIGNAL_ON_INSERT_TEXT contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • delegateGetProperty

      public static boolean delegateGetProperty(@Nonnull Object object, int prop_id, @Nonnull Value value, @Nonnull ParamSpec pspec)
      Gets a property of the `GtkEditable` delegate for @object.

      This is helper function that should be called in the `get_property`
      function of your `GtkEditable` implementation, before handling your
      own properties.
      Parameters:
      object - a `GObject`
      prop_id - a property ID
      value - value to set
      pspec - the `GParamSpec` for the property
      Returns:
      %TRUE if the property was found

    • delegateSetProperty

      public static boolean delegateSetProperty(@Nonnull Object object, int prop_id, @Nonnull Value value, @Nonnull ParamSpec pspec)
      Sets a property on the `GtkEditable` delegate for @object.

      This is a helper function that should be called in the `set_property`
      function of your `GtkEditable` implementation, before handling your
      own properties.
      Parameters:
      object - a `GObject`
      prop_id - a property ID
      value - value to set
      pspec - the `GParamSpec` for the property
      Returns:
      %TRUE if the property was found

    • installProperties

      public static int installProperties(@Nonnull ObjectClass object_class, int first_prop)
      Overrides the `GtkEditable` properties for @class.

      This is a helper function that should be called in class_init,
      after installing your own properties.

      Note that your class must have "text", "cursor-position",
      "selection-bound", "editable", "width-chars", "max-width-chars",
      "xalign" and "enable-undo" properties for this function to work.

      To handle the properties in your set_property and get_property
      functions, you can either use [func@Gtk.Editable.delegate_set_property]
      and [func@Gtk.Editable.delegate_get_property] (if you are using
      a delegate), or remember the @first_prop offset and add it to the
      values in the [enum@Gtk.EditableProperties] enumeration to get the
      property IDs for these properties.
      Parameters:
      object_class - a `GObjectClass`
      first_prop - property ID to use for the first property
      Returns:
      the number of properties that were installed

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()