forked from AuroraMiddleware/gtk
b55352f6c2
Sat Feb 21 17:57:35 2004 Soeren Sandmann <sandmann@daimi.au.dk> * gtk/docs: Commit auto-generated changes
294 lines
8.2 KiB
Plaintext
294 lines
8.2 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
GtkEditable
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Interface for text-editing widgets.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
The #GtkEditable interface is an interface which should be implemented by
|
|
text editing widgets, such as #GtkEntry and #GtkText. 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 to modify the behavior of a widget.
|
|
</para>
|
|
|
|
<para>
|
|
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>
|
|
<title>Forcing entry to uppercase.</title>
|
|
<programlisting>
|
|
#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);
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### STRUCT GtkEditable ##### -->
|
|
<para>
|
|
The #GtkEditable structure contains the following fields.
|
|
(These fields should be considered read-only. They should
|
|
never be set by an application.)
|
|
|
|
<informaltable pgwide="1" frame="none" role="struct">
|
|
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
|
|
<tbody>
|
|
|
|
<row>
|
|
<entry>#guint selection_start;</entry>
|
|
<entry>the starting position of the selected characters
|
|
in the widget.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>#guint selection_end;</entry>
|
|
<entry>the end position of the selected characters
|
|
in the widget.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>#guint editable;</entry>
|
|
<entry>a flag indicating whether or not the widget is
|
|
editable by the user.</entry>
|
|
</row>
|
|
|
|
</tbody></tgroup></informaltable>
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_select_region ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
@start: the starting position.
|
|
@end: the end position.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_get_selection_bounds ##### -->
|
|
<para>
|
|
Gets the current selection bounds, if there is a selection.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
@start: location to store the starting position, or %NULL.
|
|
@end: location to store the end position, or %NULL.
|
|
@Returns: %TRUE if there is a selection.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_insert_text ##### -->
|
|
<para>
|
|
Inserts text at a given position.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
@new_text: the text to insert.
|
|
@new_text_length: the length of the text to insert, in bytes
|
|
@position: an inout parameter. The caller initializes it to
|
|
the position at which to insert the text. After the
|
|
call it points at the position after the newly
|
|
inserted text.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_delete_text ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
@start_pos: the starting position.
|
|
@end_pos: the end position.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_get_chars ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
@start_pos: the starting position.
|
|
@end_pos: the end position.
|
|
@Returns: the characters in the indicated region.
|
|
The result must be freed with g_free() when
|
|
the application is finished with it.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_cut_clipboard ##### -->
|
|
<para>
|
|
Causes the characters in the current selection to
|
|
be copied to the clipboard and then deleted from
|
|
the widget.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_copy_clipboard ##### -->
|
|
<para>
|
|
Causes the characters in the current selection to
|
|
be copied to the clipboard.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_paste_clipboard ##### -->
|
|
<para>
|
|
Causes the contents of the clipboard to be pasted into
|
|
the given widget at the current cursor position.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_delete_selection ##### -->
|
|
<para>
|
|
Deletes the current contents of the widgets selection and
|
|
disclaims the selection.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_set_position ##### -->
|
|
<para>
|
|
Sets the cursor position.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
@position: the position of the cursor. The cursor is displayed
|
|
before the character with the given (base 0) index
|
|
in the widget. The value must be less than or
|
|
equal to the number of characters in the widget.
|
|
A value of -1 indicates that the position should
|
|
be set after the last character in the entry.
|
|
Note that this position is in characters, not in
|
|
bytes.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_get_position ##### -->
|
|
<para>
|
|
Retrieves the current cursor position.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
@Returns: the position of the cursor. The cursor is displayed
|
|
before the character with the given (base 0) index
|
|
in the widget. The value will be less than or
|
|
equal to the number of characters in the widget.
|
|
Note that this position is in characters, not in
|
|
bytes.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_set_editable ##### -->
|
|
<para>
|
|
Determines if the user can edit the text in the editable
|
|
widget or not.
|
|
</para>
|
|
|
|
@editable: a #GtkEditable widget.
|
|
@is_editable: %TRUE if the user is allowed to edit the text
|
|
in the widget.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_editable_get_editable ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@editable:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### SIGNAL GtkEditable::changed ##### -->
|
|
<para>
|
|
Indicates that the user has changed the contents
|
|
of the widget.
|
|
</para>
|
|
|
|
@editable: the object which received the signal.
|
|
|
|
<!-- ##### SIGNAL GtkEditable::delete-text ##### -->
|
|
<para>
|
|
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()
|
|
</para>
|
|
|
|
@editable: the object which received the signal.
|
|
@start_pos: the starting position.
|
|
@end_pos: the end position.
|
|
|
|
<!-- ##### SIGNAL GtkEditable::insert-text ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@editable: the object which received the signal.
|
|
@new_text: the new text to insert.
|
|
@new_text_length: the length of the new text.
|
|
@position: the position at which to insert the new text.
|
|
this is an in-out paramter. After the signal
|
|
emission is finished, it should point after
|
|
the newly inserted text.
|
|
|