← Back to branch summary

~canonical-dx-team/ubuntu/maverick/gtk+2.0/menuproxy

« back to all changes in this revision

Viewing changes to docs/reference/gtk/tmpl/gtkeditable.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2007-05-04 12:24:25 UTC
  • mfrom: (1.1.21 upstream)
  • Revision ID: james.westby@ubuntu.com-20070504122425-0m8midgzrp40y8w2
Tags: 2.10.12-1ubuntu1
* Sync with Debian
* New upstream version:
  Fixed bugs:
  - 379414 file chooser warnings when changing path in the entry
  - 418585 GtkFileChooserDefault sizing code is not DPI independent
  - 419568 Crash in search if start with special letter
  - 435062 build dies with icon cache validation
  - 379399 Segfault to call gtk_print_operation_run twice.
  - 387889 cups backend has problems when there are too many printers
  - 418531 invalid read to gtkicontheme.c gtk_icon_theme_lookup_icon...
  - 423916 crash in color scheme code
  - 424042 Segmentation fault while quickly pressing Alt+arrows
  - 415260 Protect against negative indices when setting values in G...
  - 419171 XGetVisualInfo() may not set nxvisuals
  - 128852 Gdk cursors don't look good on win32
  - 344657 Ctrl-H doesn't toggle "Show Hidden Files" setting
  - 345345 PrintOperation::paginate is not emitted for class handler
  - 347567 GtkPrintOperation::end-print is not emitted if it's cance...
  - 369112 gtk_ui_manager_add_ui should accept unnamed separator
  - 392015 Selected menu item invisible on Windows Vista
  - 399253 MS-Windows Theme Bottom Tab placement rendering glitches
  - 399425 gtk_input_dialog_fill_axes() adds child to gtkscrolledwin...
  - 403251 [patch] little memory leak in GtkPrintJob
  - 403267 [patch] memory leak in GtkPageSetupUnixDialog
  - 403470 MS-Windows Theme tab placement other than on top leaks a ...
  - 404506 Windows system fonts that have multi-byte font names cann...
  - 405089 Incorrect window placement for GtkEventBox private window
  - 405515 Minor leak in gtkfilesystemmodel.c
  - 405539 gdk_pixbuf_save() for PNG saver can return FALSE without ...
  - 415681 gdk_window_clear_area includes an extra line and column o...
  - 418219 GtkRecentChooser should apply filter before sorting and c...
  - 418403 Scroll to printer after selecting it from settings
  - 421985 _gtk_print_operation_platform_backend_launch_preview
  - 421990 gtk_print_job_get_surface
  - 421993 gtk_print_operation_init
  - 423064 Conditional jump or move depends on uninitialised value(s...
  - 423722 Fix printing header in gtk-demo
  - 424168 gtk_print_operation_run on async preview
  - 425655 Don't install gtk+-unix-print-2.0.pc on non-UNIX platforms
  - 425786 GDK segfaults if XineramaQueryScreens fails
  - 428665 Lpr Backend gets stuck in infinite loop during gtk_enumer...
  - 429902 GtkPrintOperation leaks cairo contextes
  - 431997 First delay of GdkPixbufAnimationIter is wrong
  - 433242 Inconsistent scroll arrow position calculations
  - 433972 Placing gtk.Expander inside a gtk.TextView() changes gtk....
  - 434261 _gtk_toolbar_elide_underscores incorrectly handles some s...
  - 383354 ctrl-L should make 'Location' entry disappear
  - 418673 gtk_recent_manager_add_item
  - 429732 gtk_accel_group_finalize accesses invalid memory
  - 435028 WM_CLIENT_LEADER is wrong on the leader_window
  - 431067 Background of the header window is not updated
  - 338843 add recent files support inside the ui manager
  - 148535 add drop shadow to menus, tooltips, etc. under Windows XP
* debian/control.in:
  - Conflicts on ubuntulooks (<= 0.9.11-1)
* debian/patches/15_default-fallback-icon-theme.patch:
  - patch from Debian, fallback on gnome icon theme

Show diffs side-by-side

added added

removed removed

Lines of Context:
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_utf8_strup (text, length);
 
35
 
 
36
  g_signal_handlers_block_by_func (editable,
 
37
                                   (gpointer) insert_text_handler, data);
 
38
  gtk_editable_insert_text (editable, result, length, position);
 
39
  g_signal_handlers_unblock_by_func (editable,
 
40
                                     (gpointer) insert_text_handler, data);
 
41
 
 
42
  g_signal_stop_emission_by_name (editable, "insert_text"); 
 
43
 
 
44
  g_free (result);
 
45
}
 
46
</programlisting>
 
47
</example>
 
48
</para>
 
49
 
 
50
<!-- ##### SECTION See_Also ##### -->
 
51
<para>
 
52
 
 
53
</para>
 
54
 
 
55
<!-- ##### SECTION Stability_Level ##### -->
 
56
 
 
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
<!-- ##### SIGNAL GtkEditable::changed ##### -->
 
91
<para>
 
92
Indicates that the user has changed the contents
 
93
of the widget.
 
94
</para>
 
95
 
 
96
@editable: the object which received the signal.
 
97
 
 
98
<!-- ##### SIGNAL GtkEditable::delete-text ##### -->
 
99
<para>
 
100
This signal is emitted when text is deleted from
 
101
the widget by the user. The default handler for
 
102
this signal will normally be responsible for inserting
 
103
the text, so by connecting to this signal and then
 
104
stopping the signal with gtk_signal_emit_stop(), it
 
105
is possible to modify the inserted text, or prevent
 
106
it from being inserted entirely. The @start_pos
 
107
and @end_pos parameters are interpreted as for
 
108
gtk_editable_delete_text()
 
109
</para>
 
110
 
 
111
@editable: the object which received the signal.
 
112
@start_pos: the starting position.
 
113
@end_pos: the end position.
 
114
 
 
115
<!-- ##### SIGNAL GtkEditable::insert-text ##### -->
 
116
<para>
 
117
This signal is emitted when text is inserted into
 
118
the widget by the user. The default handler for
 
119
this signal will normally be responsible for inserting
 
120
the text, so by connecting to this signal and then
 
121
stopping the signal with gtk_signal_emit_stop(), it
 
122
is possible to modify the inserted text, or prevent
 
123
it from being inserted entirely.
 
124
</para>
 
125
 
 
126
@editable: the object which received the signal.
 
127
@new_text: the new text to insert.
 
128
@new_text_length: the length of the new text, in bytes, 
 
129
  or -1 if new_text is nul-terminated
 
130
@position: the position, in characters, at which to insert 
 
131
           the new text. this is an in-out parameter. 
 
132
           After the signal emission is finished, it should 
 
133
           point after the newly inserted text.
 
134
 
 
135
<!-- ##### FUNCTION gtk_editable_select_region ##### -->
 
136
<para>
 
137
Selects a region of text. The characters that
 
138
are selected are those characters at positions from
 
139
@start_pos up to, but not including @end_pos. If 
 
140
@end_pos is negative, then the the characters selected
 
141
will be those characters from @start_pos to the end
 
142
of the text.
 
143
</para>
 
144
 
 
145
@editable: a #GtkEditable widget.
 
146
@start: the starting position.
 
147
@end: the end position.
 
148
 
 
149
 
 
150
<!-- ##### FUNCTION gtk_editable_get_selection_bounds ##### -->
 
151
<para>
 
152
Gets the current selection bounds, if there is a selection.
 
153
</para>
 
154
 
 
155
@editable: a #GtkEditable widget.
 
156
@start: location to store the starting position, or %NULL.
 
157
@end: location to store the end position, or %NULL.
 
158
@Returns: %TRUE if there is a selection.
 
159
 
 
160
 
 
161
<!-- ##### FUNCTION gtk_editable_insert_text ##### -->
 
162
<para>
 
163
Inserts text at a given position.
 
164
</para>
 
165
 
 
166
@editable: a #GtkEditable widget.
 
167
@new_text: the text to insert.
 
168
@new_text_length: the length of the text to insert, in bytes
 
169
@position: an inout parameter. The caller initializes it to
 
170
           the position at which to insert the text. After the
 
171
           call it points at the position after the newly
 
172
           inserted text.
 
173
 
 
174
 
 
175
<!-- ##### FUNCTION gtk_editable_delete_text ##### -->
 
176
<para>
 
177
Deletes a sequence of characters. The characters that
 
178
are deleted are those characters at positions from
 
179
@start_pos up to, but not including @end_pos. If 
 
180
@end_pos is negative, then the the characters deleted
 
181
will be those characters from @start_pos to the end
 
182
of the text.
 
183
</para>
 
184
 
 
185
@editable: a #GtkEditable widget.
 
186
@start_pos: the starting position.
 
187
@end_pos: the end position.
 
188
 
 
189
 
 
190
<!-- ##### FUNCTION gtk_editable_get_chars ##### -->
 
191
<para>
 
192
Retrieves a sequence of characters. The characters that
 
193
are retrieved are those characters at positions from
 
194
@start_pos up to, but not including @end_pos. If 
 
195
@end_pos is negative, then the the characters retrieved
 
196
will be those characters from @start_pos to the end
 
197
of the text.
 
198
</para>
 
199
 
 
200
@editable: a #GtkEditable widget.
 
201
@start_pos: the starting position.
 
202
@end_pos: the end position.
 
203
@Returns: the characters in the indicated region.
 
204
          The result must be freed with g_free() when
 
205
          the application is finished with it.
 
206
 
 
207
 
 
208
<!-- ##### FUNCTION gtk_editable_cut_clipboard ##### -->
 
209
<para>
 
210
Causes the characters in the current selection to
 
211
be copied to the clipboard and then deleted from
 
212
the widget.
 
213
</para>
 
214
 
 
215
@editable: a #GtkEditable widget.
 
216
 
 
217
 
 
218
<!-- ##### FUNCTION gtk_editable_copy_clipboard ##### -->
 
219
<para>
 
220
Causes the characters in the current selection to
 
221
be copied to the clipboard.
 
222
</para>
 
223
 
 
224
@editable: a #GtkEditable widget.
 
225
 
 
226
 
 
227
<!-- ##### FUNCTION gtk_editable_paste_clipboard ##### -->
 
228
<para>
 
229
Causes the contents of the clipboard to be pasted into
 
230
the given widget at the current cursor position.
 
231
</para>
 
232
 
 
233
@editable: a #GtkEditable widget.
 
234
 
 
235
 
 
236
<!-- ##### FUNCTION gtk_editable_delete_selection ##### -->
 
237
<para>
 
238
Deletes the current contents of the widgets selection and
 
239
disclaims the selection.
 
240
</para>
 
241
 
 
242
@editable: a #GtkEditable widget.
 
243
 
 
244
 
 
245
<!-- ##### FUNCTION gtk_editable_set_position ##### -->
 
246
<para>
 
247
Sets the cursor position.
 
248
</para>
 
249
 
 
250
@editable: a #GtkEditable widget.
 
251
@position: the position of the cursor. The cursor is displayed
 
252
           before the character with the given (base 0) index
 
253
           in the widget. The value must be less than or
 
254
           equal to the number of characters in the widget.
 
255
           A value of -1 indicates that the position should
 
256
           be set after the last character in the entry.
 
257
           Note that this position is in characters, not in
 
258
           bytes.
 
259
 
 
260
 
 
261
<!-- ##### FUNCTION gtk_editable_get_position ##### -->
 
262
<para>
 
263
Retrieves the current cursor position.
 
264
</para>
 
265
 
 
266
@editable: a #GtkEditable widget.
 
267
@Returns: the position of the cursor. The cursor is displayed
 
268
           before the character with the given (base 0) index
 
269
           in the widget. The value will be less than or
 
270
           equal to the number of characters in the widget.
 
271
           Note that this position is in characters, not in
 
272
           bytes.
 
273
 
 
274
 
 
275
<!-- ##### FUNCTION gtk_editable_set_editable ##### -->
 
276
<para>
 
277
Determines if the user can edit the text in the editable
 
278
widget or not.
 
279
</para>
 
280
 
 
281
@editable: a #GtkEditable widget.
 
282
@is_editable: %TRUE if the user is allowed to edit the text
 
283
  in the widget.
 
284
 
 
285
 
 
286
<!-- ##### FUNCTION gtk_editable_get_editable ##### -->
 
287
<para>
 
288
 
 
289
</para>
 
290
 
 
291
@editable: 
 
292
@Returns: 
 
293
 
 
294