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