Top |
Functions
const char * | gtk_editable_get_text () |
void | gtk_editable_set_text () |
char * | gtk_editable_get_chars () |
void | gtk_editable_insert_text () |
void | gtk_editable_delete_text () |
gboolean | gtk_editable_get_selection_bounds () |
void | gtk_editable_select_region () |
void | gtk_editable_delete_selection () |
void | gtk_editable_set_position () |
int | gtk_editable_get_position () |
void | gtk_editable_set_editable () |
gboolean | gtk_editable_get_editable () |
void | gtk_editable_set_alignment () |
float | gtk_editable_get_alignment () |
int | gtk_editable_get_width_chars () |
void | gtk_editable_set_width_chars () |
int | gtk_editable_get_max_width_chars () |
void | gtk_editable_set_max_width_chars () |
gboolean | gtk_editable_get_enable_undo () |
void | gtk_editable_set_enable_undo () |
guint | gtk_editable_install_properties () |
GtkEditable * | gtk_editable_get_delegate () |
void | gtk_editable_init_delegate () |
void | gtk_editable_finish_delegate () |
gboolean | gtk_editable_delegate_set_property () |
gboolean | gtk_editable_delegate_get_property () |
Properties
int | cursor-position | Read |
gboolean | editable | Read / Write |
gboolean | enable-undo | Read / Write |
int | max-width-chars | Read / Write |
int | selection-bound | Read |
char * | text | Read / Write |
int | width-chars | Read / Write |
float | xalign | Read / Write |
Known Implementations
GtkEditable is implemented by GtkEditableLabel, GtkEntry, GtkPasswordEntry, GtkSearchEntry, GtkSpinButton and GtkText.
Description
The GtkEditable interface is an interface which should be implemented by text editing widgets, such as 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 “insert-text”, an application can convert all entry into a widget into uppercase.
Forcing entry to uppercase.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
#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:
1 2 3 4 5 6 7 8 |
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:
1 2 3 4 5 6 7 8 9 10 11 |
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()
:
1 2 3 4 5 6 7 8 |
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:
1 2 3 4 5 6 7 8 |
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:
1 2 3 4 5 6 |
... 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 “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 gtk_editable_get_delegate()
.
Functions
gtk_editable_get_text ()
const char *
gtk_editable_get_text (GtkEditable *editable
);
Retrieves the contents of editable
. The returned string is
owned by GTK and must not be modified or freed.
gtk_editable_set_text ()
void gtk_editable_set_text (GtkEditable *editable
,const char *text
);
Sets the text in the editable to the given value, replacing the current contents.
gtk_editable_get_chars ()
char * gtk_editable_get_chars (GtkEditable *editable
,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.
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.
[transfer full]
gtk_editable_insert_text ()
void gtk_editable_insert_text (GtkEditable *editable
,const char *text
,int length
,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.
[virtual do_insert_text]
gtk_editable_delete_text ()
void gtk_editable_delete_text (GtkEditable *editable
,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.
[virtual do_delete_text]
gtk_editable_get_selection_bounds ()
gboolean gtk_editable_get_selection_bounds (GtkEditable *editable
,int *start_pos
,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.
gtk_editable_select_region ()
void gtk_editable_select_region (GtkEditable *editable
,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.
[virtual set_selection_bounds]
gtk_editable_delete_selection ()
void
gtk_editable_delete_selection (GtkEditable *editable
);
Deletes the currently selected text of the editable. This call doesn’t do anything if there is no selected text.
gtk_editable_set_position ()
void gtk_editable_set_position (GtkEditable *editable
,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.
gtk_editable_get_position ()
int
gtk_editable_get_position (GtkEditable *editable
);
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.
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()
.
gtk_editable_set_alignment ()
void gtk_editable_set_alignment (GtkEditable *editable
,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.
gtk_editable_get_alignment ()
float
gtk_editable_get_alignment (GtkEditable *editable
);
Gets the value set by gtk_editable_set_alignment()
.
gtk_editable_get_width_chars ()
int
gtk_editable_get_width_chars (GtkEditable *editable
);
Gets the value set by gtk_editable_set_width_chars()
.
gtk_editable_set_width_chars ()
void gtk_editable_set_width_chars (GtkEditable *editable
,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.
gtk_editable_get_max_width_chars ()
int
gtk_editable_get_max_width_chars (GtkEditable *editable
);
Retrieves the desired maximum width of editable
, in characters.
See gtk_editable_set_max_width_chars()
.
gtk_editable_set_max_width_chars ()
void gtk_editable_set_max_width_chars (GtkEditable *editable
,int n_chars
);
Sets the desired maximum width in characters of editable
.
gtk_editable_get_enable_undo ()
gboolean
gtk_editable_get_enable_undo (GtkEditable *editable
);
Gets if undo/redo actions are enabled for editable
gtk_editable_set_enable_undo ()
void gtk_editable_set_enable_undo (GtkEditable *editable
,gboolean 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”
is set to FALSE
.
gtk_editable_install_properties ()
guint gtk_editable_install_properties (GObjectClass *object_class
,guint first_prop
);
Installs the GtkEditable properties for class
.
This is a helper function that should be called in class_init, after installing your own properties.
To handle the properties in your set_property and get_property
functions, you can either use gtk_editable_delegate_set_property()
and 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
GtkEditableProperties enumeration to get the property IDs for these
properties.
gtk_editable_get_delegate ()
GtkEditable *
gtk_editable_get_delegate (GtkEditable *editable
);
Gets the GtkEditable that editable
is delegating its
implementation to. Typically, the delegate is a GtkText widget.
gtk_editable_init_delegate ()
void
gtk_editable_init_delegate (GtkEditable *editable
);
Sets up a delegate for GtkEditable, 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.
gtk_editable_finish_delegate ()
void
gtk_editable_finish_delegate (GtkEditable *editable
);
Undoes the setup done by gtk_editable_init_delegate()
.
This is a helper function that should be called from dispose, before removing the delegate object.
gtk_editable_delegate_set_property ()
gboolean gtk_editable_delegate_set_property (GObject *object
,guint prop_id
,const GValue *value
,GParamSpec *pspec
);
Sets a property on the GtkEditable delegate for object
.
This is a helper function that should be called in set_property, before handling your own properties.
gtk_editable_delegate_get_property ()
gboolean gtk_editable_delegate_get_property (GObject *object
,guint prop_id
,GValue *value
,GParamSpec *pspec
);
Gets a property of the GtkEditable delegate for object
.
This is helper function that should be called in get_property, before handling your own properties.
Types and Values
struct GtkEditableInterface
struct GtkEditableInterface { GTypeInterface base_iface; /* signals */ 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); /* vtable */ 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); };
Property Details
The “cursor-position”
property
“cursor-position” int
The current position of the insertion cursor in chars.
Owner: GtkEditable
Flags: Read
Allowed values: [0,65535]
Default value: 0
The “editable”
property
“editable” gboolean
Whether the entry contents can be edited.
Owner: GtkEditable
Flags: Read / Write
Default value: TRUE
The “enable-undo”
property
“enable-undo” gboolean
If undo/redo should be enabled for the editable.
Owner: GtkEditable
Flags: Read / Write
Default value: TRUE
The “max-width-chars”
property
“max-width-chars” int
The desired maximum width of the entry, in characters.
Owner: GtkEditable
Flags: Read / Write
Allowed values: >= -1
Default value: -1
The “selection-bound”
property
“selection-bound” int
The position of the opposite end of the selection from the cursor in chars.
Owner: GtkEditable
Flags: Read
Allowed values: [0,65535]
Default value: 0
The “text”
property
“text” char *
The contents of the entry.
Owner: GtkEditable
Flags: Read / Write
Default value: ""
The “width-chars”
property
“width-chars” int
Number of characters to leave space for in the entry.
Owner: GtkEditable
Flags: Read / Write
Allowed values: >= -1
Default value: -1
Signal Details
The “changed”
signal
void user_function (GtkEditable *editable, gpointer user_data)
The ::changed signal is emitted at the end of a single user-visible operation on the contents of the GtkEditable.
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).
Parameters
editable |
the object which received the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “delete-text”
signal
void user_function (GtkEditable *editable, int start_pos, int 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 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
gtk_editable_delete_text()
.
Parameters
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. |
Flags: Run Last
The “insert-text”
signal
void user_function (GtkEditable *editable, char *text, int length, gpointer 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 g_signal_stop_emission()
, it
is possible to modify the inserted text, or prevent
it from being inserted entirely.
Parameters
editable |
the object which received the signal |
|
text |
the new text to insert |
|
length |
the length of the new text, in bytes, or -1 if new_text is nul-terminated |
|
position |
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. |
[inout][type int] |
user_data |
user data set when the signal handler was connected. |
Flags: Run Last