Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkeditable.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkEditable
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Interface for text-editing widgets.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkEditable class is a base class for widgets
  10 for editing text, such as #GtkEntry and #GtkText. It
  11 cannot be instantiated by itself. The editable
  12 class contains functions for generically manipulating
  13 an editable widget, a large number of action signals
  14 used for key bindings, and several signals that
  15 an application can connect to to modify the behavior
  16 of a widget.
  17 </para>
  18
  19 <para>
  20 As an example of the latter usage, by connecting
  21 the following handler to "insert_text", an application
  22 can convert all entry into a widget into uppercase.
  23
  24 <example>
  25 <title>Forcing entry to uppercase.</title>
  26 <programlisting>
  27 #include &lt;ctype.h&gt;
  28
  29 void
  30 insert_text_handler (GtkEditable *editable,
  31                      const gchar *text,
  32                      gint         length,
  33                      gint        *position,
  34                      gpointer     data)
  35 {
  36   int i;
  37   gchar *result = g_new (gchar, length);
  38
  39   for (i = 0; i &lt; length; i++)
  40     result[i] = islower (text[i]) ? toupper (text[i]) : text[i];
  41
  42   g_signal_handlers_block_by_func (GTK_OBJECT (editable),
  43                                    insert_text_handler, data);
  44   gtk_editable_insert_text (editable, result, length, position);
  45   g_signal_handlers_unblock_by_func (GTK_OBJECT (editable),
  46                                      insert_text_handler, data);
  47
  48   g_signal_stop_emission_by_name (GTK_OBJECT (editable), "insert_text");
  49
  50   g_free (result);
  51 }
  52 </programlisting>
  53 </example>
  54 </para>
  55
  56 <!-- ##### SECTION See_Also ##### -->
  57 <para>
  58
  59 </para>
  60
  61 <!-- ##### STRUCT GtkEditable ##### -->
  62 <para>
  63 The #GtkEditable structure contains the following fields.
  64 (These fields should be considered read-only. They should
  65 never be set by an application.)
  66
  67 <informaltable pgwide="1" frame="none" role="struct">
  68 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
  69 <tbody>
  70
  71 <row>
  72 <entry>#guint selection_start;</entry>
  73 <entry>the starting position of the selected characters
  74  in the widget.</entry>
  75 </row>
  76
  77 <row>
  78 <entry>#guint selection_end;</entry>
  79 <entry>the end position of the selected characters
  80  in the widget.</entry>
  81 </row>
  82
  83 <row>
  84 <entry>#guint editable;</entry>
  85 <entry>a flag indicating whether or not the widget is
  86 editable by the user.</entry>
  87 </row>
  88
  89 </tbody></tgroup></informaltable>
  90 </para>
  91
  92
  93 <!-- ##### FUNCTION gtk_editable_select_region ##### -->
  94 <para>
  95 Selects a region of text. The characters that
  96 are selected are those characters at positions from
  97 @start_pos up to, but not including @end_pos. If
  98 @end_pos is negative, then the the characters selected
  99 will be those characters from @start_pos to the end
 100 of the text.
 101 </para>
 102
 103 @editable: a #GtkEditable widget.
 104 @start: the starting position.
 105 @end: the end position.
 106
 107
 108 <!-- ##### FUNCTION gtk_editable_get_selection_bounds ##### -->
 109 <para>
 110 Gets the current selection bounds, if there is a selection.
 111 </para>
 112
 113 @editable: a #GtkEditable widget.
 114 @start: location to store the starting position, or %NULL.
 115 @end: location to store the end position, or %NULL.
 116 @Returns: %TRUE if there is a selection.
 117
 118
 119 <!-- ##### FUNCTION gtk_editable_insert_text ##### -->
 120 <para>
 121 Inserts text at a given position.
 122 </para>
 123
 124 @editable: a #GtkEditable widget.
 125 @new_text: the text to insert.
 126 @new_text_length: the length of the text to insert, in bytes
 127 @position: an inout parameter. The caller initializes it to
 128            the position at which to insert the text. After the
 129            call it points at the position after the newly
 130            inserted text.
 131
 132
 133 <!-- ##### FUNCTION gtk_editable_delete_text ##### -->
 134 <para>
 135 Deletes a sequence of characters. The characters that
 136 are deleted are those characters at positions from
 137 @start_pos up to, but not including @end_pos. If
 138 @end_pos is negative, then the the characters deleted
 139 will be those characters from @start_pos to the end
 140 of the text.
 141 </para>
 142
 143 @editable: a #GtkEditable widget.
 144 @start_pos: the starting position.
 145 @end_pos: the end position.
 146
 147
 148 <!-- ##### FUNCTION gtk_editable_get_chars ##### -->
 149 <para>
 150 Retrieves a sequence of characters. The characters that
 151 are retrieved are those characters at positions from
 152 @start_pos up to, but not including @end_pos. If
 153 @end_pos is negative, then the the characters retrieved
 154 will be those characters from @start_pos to the end
 155 of the text.
 156 </para>
 157
 158 @editable: a #GtkEditable widget.
 159 @start_pos: the starting position.
 160 @end_pos: the end position.
 161 @Returns: the characters in the indicated region.
 162           The result must be freed with g_free() when
 163           the application is finished with it.
 164
 165
 166 <!-- ##### FUNCTION gtk_editable_cut_clipboard ##### -->
 167 <para>
 168 Causes the characters in the current selection to
 169 be copied to the clipboard and then deleted from
 170 the widget.
 171 </para>
 172
 173 @editable: a #GtkEditable widget.
 174
 175
 176 <!-- ##### FUNCTION gtk_editable_copy_clipboard ##### -->
 177 <para>
 178 Causes the characters in the current selection to
 179 be copied to the clipboard.
 180 </para>
 181
 182 @editable: a #GtkEditable widget.
 183
 184
 185 <!-- ##### FUNCTION gtk_editable_paste_clipboard ##### -->
 186 <para>
 187 Causes the contents of the clipboard to be pasted into
 188 the given widget at the current cursor position.
 189 </para>
 190
 191 @editable: a #GtkEditable widget.
 192
 193
 194 <!-- ##### FUNCTION gtk_editable_delete_selection ##### -->
 195 <para>
 196 Deletes the current contents of the widgets selection and
 197 disclaims the selection.
 198 </para>
 199
 200 @editable: a #GtkEditable widget.
 201
 202
 203 <!-- ##### FUNCTION gtk_editable_set_position ##### -->
 204 <para>
 205 Sets the cursor position.
 206 </para>
 207
 208 @editable: a #GtkEditable widget.
 209 @position: the position of the cursor. The cursor is displayed
 210            before the character with the given (base 0) index
 211            in the widget. The value must be less than or
 212            equal to the number of characters in the widget.
 213            A value of -1 indicates that the position should
 214            be set after the last character in the entry.
 215            Note that this position is in characters, not in
 216            bytes.
 217
 218
 219 <!-- ##### FUNCTION gtk_editable_get_position ##### -->
 220 <para>
 221 Retrieves the current cursor position.
 222 </para>
 223
 224 @editable: a #GtkEditable widget.
 225 @Returns: the position of the cursor. The cursor is displayed
 226            before the character with the given (base 0) index
 227            in the widget. The value will be less than or
 228            equal to the number of characters in the widget.
 229            Note that this position is in characters, not in
 230            bytes.
 231
 232
 233 <!-- ##### FUNCTION gtk_editable_set_editable ##### -->
 234 <para>
 235 Determines if the user can edit the text in the editable
 236 widget or not.
 237 </para>
 238
 239 @editable: a #GtkEditable widget.
 240 @is_editable: %TRUE if the user is allowed to edit the text
 241   in the widget.
 242
 243
 244 <!-- ##### FUNCTION gtk_editable_get_editable ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @editable:
 250 @Returns:
 251
 252
 253 <!-- ##### SIGNAL GtkEditable::changed ##### -->
 254 <para>
 255 Indicates that the user has changed the contents
 256 of the widget.
 257 </para>
 258
 259 @editable: the object which received the signal.
 260
 261 <!-- ##### SIGNAL GtkEditable::delete-text ##### -->
 262 <para>
 263 This signal is emitted when text is deleted from
 264 the widget by the user. The default handler for
 265 this signal will normally be responsible for inserting
 266 the text, so by connecting to this signal and then
 267 stopping the signal with gtk_signal_emit_stop(), it
 268 is possible to modify the inserted text, or prevent
 269 it from being inserted entirely. The @start_pos
 270 and @end_pos parameters are interpreted as for
 271 gtk_editable_delete_text()
 272 </para>
 273
 274 @editable: the object which received the signal.
 275 @start_pos: the starting position.
 276 @end_pos: the end position.
 277
 278 <!-- ##### SIGNAL GtkEditable::insert-text ##### -->
 279 <para>
 280 This signal is emitted when text is inserted into
 281 the widget by the user. The default handler for
 282 this signal will normally be responsible for inserting
 283 the text, so by connecting to this signal and then
 284 stopping the signal with gtk_signal_emit_stop(), it
 285 is possible to modify the inserted text, or prevent
 286 it from being inserted entirely.
 287 </para>
 288
 289 @editable: the object which received the signal.
 290 @new_text: the new text to insert.
 291 @new_text_length: the length of the new text.
 292 @position: the position at which to insert the new text.
 293            this is an in-out paramter. After the signal
 294            emission is finished, it should point after
 295            the newly inserted text.
 296