Description

Gnome::Gtk4::R-Editable is an interface for text editing widgets.

Typical examples of editable widgets are Gnome::Gtk4::Entry and Gnome::Gtk4::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 insert-text, an application can convert all entry into a widget into uppercase.

Forcing entry to uppercase.

Implementing GtkEditable

The most likely scenario for implementing Gnome::Gtk4::R-Editable on your own widget is that you will embed a Gnome::Gtk4::Text inside a complex widget, and want to delegate the editable functionality to that text widget. Gnome::Gtk4::R-Editable provides some utility functions to make this easy.

In your class_init function, call .Editable.install-properties(), passing the first available property ID:

In your interface_init function for the Gnome::Gtk4::R-Editable interface, provide an implementation for the get_delegate vfunc that returns your text widget:

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 .init-delegate():

In your dispose function, call .finish-delegate() before destroying your text widget:

Finally, use .Editable.delegate-set-property() in your set_property function (and similar for get_property), to set the editable properties:

It is important to note that if you create a Gnome::Gtk4::R-Editable that uses a delegate, the low level insert-text and 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 insert-text and delete-text signals, you will need to connect to them on the delegate obtained via .get-delegate().

Methods

delegate-get-accessible-platform-state

Retrieves the accessible platform state from the editable delegate.

This is an helper function to retrieve the accessible state for Gnome::Gtk4::R-Editable interface implementations using a delegate pattern.

You should call this function in your editable widget implementation of the [vfunc $Gtk.Accessible.get_platform_state] virtual function, for instance:

method delegate-get-accessible-platform-state ( GtkAccessiblePlatformState $state --> Bool )

• $state; what kind of accessible state to retrieve.

Return value; No documentation about its value and use.

delete-selection

Deletes the currently selected text of the editable.

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

method delete-selection ( )

delete-text

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.

method delete-text ( Int() $start-pos, Int() $end-pos )

• $start-pos; start position.

• $end-pos; end position.

finish-delegate

Undoes the setup done by .init-delegate().

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

method finish-delegate ( )

get-alignment

Gets the alignment of the editable.

method get-alignment (--> Num )

Return value; the alignment.

get-chars

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.

method get-chars ( Int() $start-pos, Int() $end-pos --> Str )

• $start-pos; start of text.

• $end-pos; end of text.

Return value; a pointer to the contents of the widget as a string. This string is allocated by the Gnome::Gtk4::R-Editable implementation and should be freed by the caller..

get-delegate

Gets the Gnome::Gtk4::R-Editable that $editable is delegating its implementation to.

Typically, the delegate is a Gnome::Gtk4::Text widget.

method get-delegate (--> N-Object )

Return value; the delegate Gnome::Gtk4::R-Editable.

get-editable

Retrieves whether $editable is editable.

method get-editable (--> Bool )

Return value; True if $editable is editable..

get-enable-undo

Gets if undo/redo actions are enabled for $editable

method get-enable-undo (--> Bool )

Return value; True if undo is enabled.

get-max-width-chars

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

method get-max-width-chars (--> Int )

Return value; the maximum width of the entry, in characters.

get-position

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.

method get-position (--> Int )

Return value; the cursor position.

get-selection-bounds

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.

method get-selection-bounds ( Array[Int] $start-pos, Array[Int] $end-pos --> Bool )

• $start-pos; (transfer ownership: full) location to store the starting position.

• $end-pos; (transfer ownership: full) location to store the end position.

Return value; True if there is a non-empty selection, False otherwise.

get-text

Retrieves the contents of $editable.

The returned string is owned by GTK and must not be modified or freed.

method get-text (--> Str )

Return value; a pointer to the contents of the editable.

get-width-chars

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

method get-width-chars (--> Int )

Return value; number of chars to request space for, or negative if unset.

init-delegate

Sets up a delegate for Gnome::Gtk4::R-Editable.

This is assuming that the get_delegate vfunc in the Gnome::Gtk4::R-Editable 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.

method init-delegate ( )

insert-text

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.

method insert-text ( Str $text, Int() $length, Array[Int] $position )

• $text; the text to insert.

• $length; the length of the text in bytes, or -1.

• $position; (transfer ownership: full) location of the position text will be inserted at.

select-region

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.

method select-region ( Int() $start-pos, Int() $end-pos )

• $start-pos; start of region.

• $end-pos; end of region.

set-alignment

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.

method set-alignment ( Num() $xalign )

• $xalign; The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts.

set-editable

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

method set-editable ( Bool() $is-editable )

• $is-editable; True if the user is allowed to edit the text in the widget.

set-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 visibility defined in Gnome::Gtk4::Text is set to False.

method set-enable-undo ( Bool() $enable-undo )

• $enable-undo; if undo/redo should be enabled.

set-max-width-chars

Sets the desired maximum width in characters of $editable.

method set-max-width-chars ( Int() $n-chars )

• $n-chars; the new desired maximum width, in characters.

set-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.

method set-position ( Int() $position )

• $position; the position of the cursor.

set-text

Sets the text in the editable to the given value.

This is replacing the current contents.

method set-text ( Str $text )

• $text; the text to set.

set-width-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.

method set-width-chars ( Int() $n-chars )

• $n-chars; width in chars.

Functions

delegate-get-property

Gets a property of the Gnome::Gtk4::R-Editable delegate for $object.

This is helper function that should be called in the get_property function of your Gnome::Gtk4::R-Editable implementation, before handling your own properties.

method delegate-get-property ( N-Object() $object, UInt() $prop-id, N-Object $value, N-Object() $pspec --> Bool )

• $object; a Gnome::GObject::Object.

• $prop-id; a property ID.

• $value; value to set

• $pspec; the Gnome::GObject::ParamSpec for the property.

Return value; True if the property was found.

delegate-set-property

Sets a property on the Gnome::Gtk4::R-Editable delegate for $object.

This is a helper function that should be called in the set_property function of your Gnome::Gtk4::R-Editable implementation, before handling your own properties.

method delegate-set-property ( N-Object() $object, UInt() $prop-id, N-Object $value, N-Object() $pspec --> Bool )

• $object; a Gnome::GObject::Object.

• $prop-id; a property ID.

• $value; value to set

• $pspec; the Gnome::GObject::ParamSpec for the property.

Return value; True if the property was found.

install-properties This function is not yet available

Overrides the Gnome::Gtk4::R-Editable 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 .Editable.delegate-set-property() and .Editable.delegate-get-property() (if you are using a delegate), or remember the $first-prop offset and add it to the values in the enumeration EditableProperties from Gnome::Gtk4::T-editable enumeration to get the property IDs for these properties.

method install-properties ( …, UInt() $first-prop --> UInt )

• object-class; a GObjectClass. Note that each argument must be specified as a type followed by its value!

• $first-prop; property ID to use for the first property.

Return value; the number of properties that were installed.

Signals

changed

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

E.g., a paste operation that replaces the contents of the selection will cause only one signal emission (even though it is implemented by first deleting the selection, then inserting the new content, and may cause multiple notify::text signals to be emitted).

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Editable :$_widget,
  *C<user>-options
)

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Editable object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

delete-text

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

The default handler for this signal will normally be responsible for deleting the text, so by connecting to this signal and then stopping the signal with g_signal_stop_emission(), it is possible to modify the range of deleted text, or prevent it from being deleted entirely.

The $start-pos and $end-pos parameters are interpreted as for .delete-text().

method handler (
  gint $start-pos,
  gint $end-pos,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Editable :$_widget,
  *C<user>-options
)

• $start-pos; the starting position.

• $end-pos; the end position.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Editable object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

insert-text

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 g_signal_stop_emission(), it is possible to modify the inserted text, or prevent it from being inserted entirely.

method handler (
  Str $text,
  gint $length,
  gpointer $position,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Editable :$_widget,
  *C<user>-options
)

• $text; the new text to insert.

• $length; the length of the new text, in bytes, or -1 if new_text is nul-terminated.

• $position; (transfer ownership: full)the position, in characters, at which to insert the new text. this is an in-out parameter. After the signal emission is finished, it should point after the newly inserted text..

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Editable object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.