gtktextbuffer.h 21.1 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GTK - The GIMP Toolkit
2
3
4
5
6
7
8
9
10
 * gtktextbuffer.h Copyright (C) 2000 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12
13
14
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
Javier Jardón's avatar
Javier Jardón committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16
17
18
19
20
21
 */

/*
 * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
 * file for a list of people on the GTK+ Team.  See the ChangeLog
 * files for a list of changes.  These files are distributed with
22
 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
23
24
 */

25
26
27
#ifndef __GTK_TEXT_BUFFER_H__
#define __GTK_TEXT_BUFFER_H__

28
#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
29
30
31
#error "Only <gtk/gtk.h> can be included directly."
#endif

32
#include <gtk/gtkwidget.h>
33
#include <gtk/gtkclipboard.h>
34
35
36
#include <gtk/gtktexttagtable.h>
#include <gtk/gtktextiter.h>
#include <gtk/gtktextmark.h>
37
#include <gtk/gtktextchild.h>
38

39
G_BEGIN_DECLS
40
41
42
43
44
45

/*
 * This is the PUBLIC representation of a text buffer.
 * GtkTextBTree is the PRIVATE internal representation of it.
 */

46
47
48
49
50
/**
 * GtkTextBufferTargetInfo:
 * @GTK_TEXT_BUFFER_TARGET_INFO_BUFFER_CONTENTS: Buffer contents
 * @GTK_TEXT_BUFFER_TARGET_INFO_RICH_TEXT: Rich text
 * @GTK_TEXT_BUFFER_TARGET_INFO_TEXT: Text
51
 *
William Jon McCann's avatar
William Jon McCann committed
52
 * These values are used as “info” for the targets contained in the
53
54
55
 * lists returned by gtk_text_buffer_get_copy_target_list() and
 * gtk_text_buffer_get_paste_target_list().
 *
56
 * The values counts down from `-1` to avoid clashes
57
 * with application added drag destinations which usually start at 0.
58
59
60
 */
typedef enum
{
61
62
63
  GTK_TEXT_BUFFER_TARGET_INFO_BUFFER_CONTENTS = - 1,
  GTK_TEXT_BUFFER_TARGET_INFO_RICH_TEXT       = - 2,
  GTK_TEXT_BUFFER_TARGET_INFO_TEXT            = - 3
64
65
} GtkTextBufferTargetInfo;

66
67
typedef struct _GtkTextBTree GtkTextBTree;

68
#define GTK_TYPE_TEXT_BUFFER            (gtk_text_buffer_get_type ())
69
70
71
72
73
#define GTK_TEXT_BUFFER(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TEXT_BUFFER, GtkTextBuffer))
#define GTK_TEXT_BUFFER_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_TEXT_BUFFER, GtkTextBufferClass))
#define GTK_IS_TEXT_BUFFER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_TEXT_BUFFER))
#define GTK_IS_TEXT_BUFFER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_TEXT_BUFFER))
#define GTK_TEXT_BUFFER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_TEXT_BUFFER, GtkTextBufferClass))
74

75
typedef struct _GtkTextBufferPrivate GtkTextBufferPrivate;
76
77
typedef struct _GtkTextBufferClass GtkTextBufferClass;

78
79
struct _GtkTextBuffer
{
80
  GObject parent_instance;
81

82
  GtkTextBufferPrivate *priv;
83
84
};

85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
/**
 * GtkTextBufferClass:
 * @parent_class: The object class structure needs to be the first.
 * @insert_text: The class handler for the #GtkTextBuffer::insert-text signal.
 * @insert_pixbuf: The class handler for the #GtkTextBuffer::insert-pixbuf
 *   signal.
 * @insert_child_anchor: The class handler for the
 *   #GtkTextBuffer::insert-child-anchor signal.
 * @delete_range: The class handler for the #GtkTextBuffer::delete-range signal.
 * @changed: The class handler for the #GtkTextBuffer::changed signal.
 * @modified_changed: The class handler for the #GtkTextBuffer::modified-changed
 *   signal.
 * @mark_set: The class handler for the #GtkTextBuffer::mark-set signal.
 * @mark_deleted: The class handler for the #GtkTextBuffer::mark-deleted signal.
 * @apply_tag: The class handler for the #GtkTextBuffer::apply-tag signal.
 * @remove_tag: The class handler for the #GtkTextBuffer::remove-tag signal.
 * @begin_user_action: The class handler for the
 *   #GtkTextBuffer::begin-user-action signal.
 * @end_user_action: The class handler for the #GtkTextBuffer::end-user-action
 *   signal.
 * @paste_done: The class handler for the #GtkTextBuffer::paste-done signal.
 */
107
108
struct _GtkTextBufferClass
{
109
  GObjectClass parent_class;
110

111
112
113
114
115
116
117
118
  void (* insert_text)            (GtkTextBuffer      *buffer,
                                   GtkTextIter        *pos,
                                   const gchar        *new_text,
                                   gint                new_text_length);

  void (* insert_pixbuf)          (GtkTextBuffer      *buffer,
                                   GtkTextIter        *iter,
                                   GdkPixbuf          *pixbuf);
119

120
121
122
  void (* insert_child_anchor)    (GtkTextBuffer      *buffer,
                                   GtkTextIter        *iter,
                                   GtkTextChildAnchor *anchor);
123

124
125
126
  void (* delete_range)           (GtkTextBuffer      *buffer,
                                   GtkTextIter        *start,
                                   GtkTextIter        *end);
127

128
  void (* changed)                (GtkTextBuffer      *buffer);
129

130
  void (* modified_changed)       (GtkTextBuffer      *buffer);
131

132
133
134
  void (* mark_set)               (GtkTextBuffer      *buffer,
                                   const GtkTextIter  *location,
                                   GtkTextMark        *mark);
135

136
137
  void (* mark_deleted)           (GtkTextBuffer      *buffer,
                                   GtkTextMark        *mark);
138

139
140
141
142
  void (* apply_tag)              (GtkTextBuffer      *buffer,
                                   GtkTextTag         *tag,
                                   const GtkTextIter  *start,
                                   const GtkTextIter  *end);
143

144
145
146
147
  void (* remove_tag)             (GtkTextBuffer      *buffer,
                                   GtkTextTag         *tag,
                                   const GtkTextIter  *start,
                                   const GtkTextIter  *end);
148

149
  void (* begin_user_action)      (GtkTextBuffer      *buffer);
150

151
  void (* end_user_action)        (GtkTextBuffer      *buffer);
152

153
154
  void (* paste_done)             (GtkTextBuffer      *buffer,
                                   GtkClipboard       *clipboard);
155

156
  /*< private >*/
157

158
159
160
161
162
  /* Padding for future expansion */
  void (*_gtk_reserved1) (void);
  void (*_gtk_reserved2) (void);
  void (*_gtk_reserved3) (void);
  void (*_gtk_reserved4) (void);
163
164
};

165
GDK_AVAILABLE_IN_ALL
166
GType        gtk_text_buffer_get_type       (void) G_GNUC_CONST;
167
168
169
170



/* table is NULL to create a new one */
171
GDK_AVAILABLE_IN_ALL
172
GtkTextBuffer *gtk_text_buffer_new            (GtkTextTagTable *table);
173
GDK_AVAILABLE_IN_ALL
174
gint           gtk_text_buffer_get_line_count (GtkTextBuffer   *buffer);
175
GDK_AVAILABLE_IN_ALL
176
177
178
gint           gtk_text_buffer_get_char_count (GtkTextBuffer   *buffer);


179
GDK_AVAILABLE_IN_ALL
180
GtkTextTagTable* gtk_text_buffer_get_tag_table (GtkTextBuffer  *buffer);
181

182
/* Delete whole buffer, then insert */
183
GDK_AVAILABLE_IN_ALL
184
185
186
187
void gtk_text_buffer_set_text          (GtkTextBuffer *buffer,
                                        const gchar   *text,
                                        gint           len);

188
/* Insert into the buffer */
189
GDK_AVAILABLE_IN_ALL
190
191
192
193
void gtk_text_buffer_insert            (GtkTextBuffer *buffer,
                                        GtkTextIter   *iter,
                                        const gchar   *text,
                                        gint           len);
194
GDK_AVAILABLE_IN_ALL
195
196
197
198
void gtk_text_buffer_insert_at_cursor  (GtkTextBuffer *buffer,
                                        const gchar   *text,
                                        gint           len);

199
GDK_AVAILABLE_IN_ALL
200
201
202
203
204
gboolean gtk_text_buffer_insert_interactive           (GtkTextBuffer *buffer,
                                                       GtkTextIter   *iter,
                                                       const gchar   *text,
                                                       gint           len,
                                                       gboolean       default_editable);
205
GDK_AVAILABLE_IN_ALL
206
207
208
209
gboolean gtk_text_buffer_insert_interactive_at_cursor (GtkTextBuffer *buffer,
                                                       const gchar   *text,
                                                       gint           len,
                                                       gboolean       default_editable);
210

211
GDK_AVAILABLE_IN_ALL
212
213
214
215
void     gtk_text_buffer_insert_range             (GtkTextBuffer     *buffer,
                                                   GtkTextIter       *iter,
                                                   const GtkTextIter *start,
                                                   const GtkTextIter *end);
216
GDK_AVAILABLE_IN_ALL
217
218
219
220
221
222
gboolean gtk_text_buffer_insert_range_interactive (GtkTextBuffer     *buffer,
                                                   GtkTextIter       *iter,
                                                   const GtkTextIter *start,
                                                   const GtkTextIter *end,
                                                   gboolean           default_editable);

223
GDK_AVAILABLE_IN_ALL
224
225
226
227
228
void    gtk_text_buffer_insert_with_tags          (GtkTextBuffer     *buffer,
                                                   GtkTextIter       *iter,
                                                   const gchar       *text,
                                                   gint               len,
                                                   GtkTextTag        *first_tag,
229
                                                   ...) G_GNUC_NULL_TERMINATED;
230

231
GDK_AVAILABLE_IN_ALL
232
233
234
235
236
void    gtk_text_buffer_insert_with_tags_by_name  (GtkTextBuffer     *buffer,
                                                   GtkTextIter       *iter,
                                                   const gchar       *text,
                                                   gint               len,
                                                   const gchar       *first_tag_name,
237
                                                   ...) G_GNUC_NULL_TERMINATED;
238

239
240
241
242
243
244
GDK_AVAILABLE_IN_3_16
void     gtk_text_buffer_insert_markup            (GtkTextBuffer     *buffer,
                                                   GtkTextIter       *iter,
                                                   const gchar       *markup,
                                                   gint               len);

245
/* Delete from the buffer */
246
GDK_AVAILABLE_IN_ALL
247
void     gtk_text_buffer_delete             (GtkTextBuffer *buffer,
Owen Taylor's avatar
#155952    
Owen Taylor committed
248
249
					     GtkTextIter   *start,
					     GtkTextIter   *end);
250
GDK_AVAILABLE_IN_ALL
251
gboolean gtk_text_buffer_delete_interactive (GtkTextBuffer *buffer,
Owen Taylor's avatar
#155952    
Owen Taylor committed
252
253
254
					     GtkTextIter   *start_iter,
					     GtkTextIter   *end_iter,
					     gboolean       default_editable);
255
GDK_AVAILABLE_IN_ALL
Owen Taylor's avatar
#155952    
Owen Taylor committed
256
257
258
259
gboolean gtk_text_buffer_backspace          (GtkTextBuffer *buffer,
					     GtkTextIter   *iter,
					     gboolean       interactive,
					     gboolean       default_editable);
260
261

/* Obtain strings from the buffer */
262
GDK_AVAILABLE_IN_ALL
263
gchar          *gtk_text_buffer_get_text            (GtkTextBuffer     *buffer,
264
265
                                                     const GtkTextIter *start,
                                                     const GtkTextIter *end,
266
                                                     gboolean           include_hidden_chars);
267

268
GDK_AVAILABLE_IN_ALL
269
gchar          *gtk_text_buffer_get_slice           (GtkTextBuffer     *buffer,
270
271
                                                     const GtkTextIter *start,
                                                     const GtkTextIter *end,
272
273
                                                     gboolean           include_hidden_chars);

Havoc Pennington's avatar
Havoc Pennington committed
274
/* Insert a pixbuf */
275
GDK_AVAILABLE_IN_ALL
Havoc Pennington's avatar
Havoc Pennington committed
276
void gtk_text_buffer_insert_pixbuf         (GtkTextBuffer *buffer,
277
                                            GtkTextIter   *iter,
Havoc Pennington's avatar
Havoc Pennington committed
278
                                            GdkPixbuf     *pixbuf);
279

280
/* Insert a child anchor */
281
GDK_AVAILABLE_IN_ALL
282
283
284
285
286
void               gtk_text_buffer_insert_child_anchor (GtkTextBuffer      *buffer,
                                                        GtkTextIter        *iter,
                                                        GtkTextChildAnchor *anchor);

/* Convenience, create and insert a child anchor */
287
GDK_AVAILABLE_IN_ALL
288
289
290
GtkTextChildAnchor *gtk_text_buffer_create_child_anchor (GtkTextBuffer *buffer,
                                                         GtkTextIter   *iter);

291
/* Mark manipulation */
292
GDK_AVAILABLE_IN_ALL
293
294
295
void           gtk_text_buffer_add_mark    (GtkTextBuffer     *buffer,
                                            GtkTextMark       *mark,
                                            const GtkTextIter *where);
296
GDK_AVAILABLE_IN_ALL
297
298
299
300
GtkTextMark   *gtk_text_buffer_create_mark (GtkTextBuffer     *buffer,
                                            const gchar       *mark_name,
                                            const GtkTextIter *where,
                                            gboolean           left_gravity);
301
GDK_AVAILABLE_IN_ALL
302
void           gtk_text_buffer_move_mark   (GtkTextBuffer     *buffer,
303
                                            GtkTextMark       *mark,
304
                                            const GtkTextIter *where);
305
GDK_AVAILABLE_IN_ALL
306
void           gtk_text_buffer_delete_mark (GtkTextBuffer     *buffer,
307
                                            GtkTextMark       *mark);
308
GDK_AVAILABLE_IN_ALL
Havoc Pennington's avatar
Havoc Pennington committed
309
GtkTextMark*   gtk_text_buffer_get_mark    (GtkTextBuffer     *buffer,
310
311
                                            const gchar       *name);

312
GDK_AVAILABLE_IN_ALL
313
314
315
void gtk_text_buffer_move_mark_by_name   (GtkTextBuffer     *buffer,
                                          const gchar       *name,
                                          const GtkTextIter *where);
316
GDK_AVAILABLE_IN_ALL
317
318
319
void gtk_text_buffer_delete_mark_by_name (GtkTextBuffer     *buffer,
                                          const gchar       *name);

320
GDK_AVAILABLE_IN_ALL
Havoc Pennington's avatar
Havoc Pennington committed
321
GtkTextMark* gtk_text_buffer_get_insert          (GtkTextBuffer *buffer);
322
GDK_AVAILABLE_IN_ALL
Havoc Pennington's avatar
Havoc Pennington committed
323
324
GtkTextMark* gtk_text_buffer_get_selection_bound (GtkTextBuffer *buffer);

325
/* efficiently move insert and selection_bound at the same time */
326
GDK_AVAILABLE_IN_ALL
327
328
void gtk_text_buffer_place_cursor (GtkTextBuffer     *buffer,
                                   const GtkTextIter *where);
329
GDK_AVAILABLE_IN_ALL
330
331
332
void gtk_text_buffer_select_range (GtkTextBuffer     *buffer,
                                   const GtkTextIter *ins,
				   const GtkTextIter *bound);
333
334
335
336



/* Tag manipulation */
337
GDK_AVAILABLE_IN_ALL
338
void gtk_text_buffer_apply_tag             (GtkTextBuffer     *buffer,
339
                                            GtkTextTag        *tag,
340
341
                                            const GtkTextIter *start,
                                            const GtkTextIter *end);
342
GDK_AVAILABLE_IN_ALL
343
void gtk_text_buffer_remove_tag            (GtkTextBuffer     *buffer,
344
                                            GtkTextTag        *tag,
345
346
                                            const GtkTextIter *start,
                                            const GtkTextIter *end);
347
GDK_AVAILABLE_IN_ALL
348
349
void gtk_text_buffer_apply_tag_by_name     (GtkTextBuffer     *buffer,
                                            const gchar       *name,
350
351
                                            const GtkTextIter *start,
                                            const GtkTextIter *end);
352
GDK_AVAILABLE_IN_ALL
353
void gtk_text_buffer_remove_tag_by_name    (GtkTextBuffer     *buffer,
354
                                            const gchar       *name,
355
356
                                            const GtkTextIter *start,
                                            const GtkTextIter *end);
357
GDK_AVAILABLE_IN_ALL
Havoc Pennington's avatar
Havoc Pennington committed
358
359
360
void gtk_text_buffer_remove_all_tags       (GtkTextBuffer     *buffer,
                                            const GtkTextIter *start,
                                            const GtkTextIter *end);
361
362
363


/* You can either ignore the return value, or use it to
364
365
 * set the attributes of the tag. tag_name can be NULL
 */
366
GDK_AVAILABLE_IN_ALL
367
GtkTextTag    *gtk_text_buffer_create_tag (GtkTextBuffer *buffer,
368
369
                                           const gchar   *tag_name,
                                           const gchar   *first_property_name,
370
                                           ...);
371
372

/* Obtain iterators pointed at various places, then you can move the
373
374
 * iterator around using the GtkTextIter operators
 */
375
GDK_AVAILABLE_IN_ALL
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
void gtk_text_buffer_get_iter_at_line_offset (GtkTextBuffer *buffer,
                                              GtkTextIter   *iter,
                                              gint           line_number,
                                              gint           char_offset);
GDK_AVAILABLE_IN_ALL
void gtk_text_buffer_get_iter_at_line_index  (GtkTextBuffer *buffer,
                                              GtkTextIter   *iter,
                                              gint           line_number,
                                              gint           byte_index);
GDK_AVAILABLE_IN_ALL
void gtk_text_buffer_get_iter_at_offset      (GtkTextBuffer *buffer,
                                              GtkTextIter   *iter,
                                              gint           char_offset);
GDK_AVAILABLE_IN_ALL
void gtk_text_buffer_get_iter_at_line        (GtkTextBuffer *buffer,
                                              GtkTextIter   *iter,
                                              gint           line_number);
393
GDK_AVAILABLE_IN_ALL
Havoc Pennington's avatar
Havoc Pennington committed
394
395
void gtk_text_buffer_get_start_iter          (GtkTextBuffer *buffer,
                                              GtkTextIter   *iter);
396
GDK_AVAILABLE_IN_ALL
397
void gtk_text_buffer_get_end_iter            (GtkTextBuffer *buffer,
398
                                              GtkTextIter   *iter);
399
GDK_AVAILABLE_IN_ALL
400
401
402
void gtk_text_buffer_get_bounds              (GtkTextBuffer *buffer,
                                              GtkTextIter   *start,
                                              GtkTextIter   *end);
403
GDK_AVAILABLE_IN_ALL
404
405
406
void gtk_text_buffer_get_iter_at_mark        (GtkTextBuffer *buffer,
                                              GtkTextIter   *iter,
                                              GtkTextMark   *mark);
407

408
GDK_AVAILABLE_IN_ALL
409
410
411
void gtk_text_buffer_get_iter_at_child_anchor (GtkTextBuffer      *buffer,
                                               GtkTextIter        *iter,
                                               GtkTextChildAnchor *anchor);
412
413
414
415
416
417
418
419
420
421

/* There's no get_first_iter because you just get the iter for
   line or char 0 */

/* Used to keep track of whether the buffer needs saving; anytime the
   buffer contents change, the modified flag is turned on. Whenever
   you save, turn it off. Tags and marks do not affect the modified
   flag, but if you would like them to you can connect a handler to
   the tag/mark signals and call set_modified in your handler */

422
GDK_AVAILABLE_IN_ALL
423
gboolean        gtk_text_buffer_get_modified            (GtkTextBuffer *buffer);
424
GDK_AVAILABLE_IN_ALL
425
426
void            gtk_text_buffer_set_modified            (GtkTextBuffer *buffer,
                                                         gboolean       setting);
427

428
GDK_AVAILABLE_IN_ALL
Matthias Clasen's avatar
Matthias Clasen committed
429
430
gboolean        gtk_text_buffer_get_has_selection       (GtkTextBuffer *buffer);

431
GDK_AVAILABLE_IN_ALL
432
433
void gtk_text_buffer_add_selection_clipboard    (GtkTextBuffer     *buffer,
						 GtkClipboard      *clipboard);
434
GDK_AVAILABLE_IN_ALL
435
436
437
void gtk_text_buffer_remove_selection_clipboard (GtkTextBuffer     *buffer,
						 GtkClipboard      *clipboard);

438
GDK_AVAILABLE_IN_ALL
439
void            gtk_text_buffer_cut_clipboard           (GtkTextBuffer *buffer,
440
							 GtkClipboard  *clipboard,
441
                                                         gboolean       default_editable);
442
GDK_AVAILABLE_IN_ALL
443
444
void            gtk_text_buffer_copy_clipboard          (GtkTextBuffer *buffer,
							 GtkClipboard  *clipboard);
445
GDK_AVAILABLE_IN_ALL
446
void            gtk_text_buffer_paste_clipboard         (GtkTextBuffer *buffer,
447
448
							 GtkClipboard  *clipboard,
							 GtkTextIter   *override_location,
449
                                                         gboolean       default_editable);
450

451
GDK_AVAILABLE_IN_ALL
452
453
454
gboolean        gtk_text_buffer_get_selection_bounds    (GtkTextBuffer *buffer,
                                                         GtkTextIter   *start,
                                                         GtkTextIter   *end);
455
GDK_AVAILABLE_IN_ALL
456
457
gboolean        gtk_text_buffer_delete_selection        (GtkTextBuffer *buffer,
                                                         gboolean       interactive,
458
                                                         gboolean       default_editable);
459
460

/* Called to specify atomic user actions, used to implement undo */
461
GDK_AVAILABLE_IN_ALL
462
void            gtk_text_buffer_begin_user_action       (GtkTextBuffer *buffer);
463
GDK_AVAILABLE_IN_ALL
464
465
void            gtk_text_buffer_end_user_action         (GtkTextBuffer *buffer);

466
GDK_AVAILABLE_IN_ALL
467
GtkTargetList * gtk_text_buffer_get_copy_target_list    (GtkTextBuffer *buffer);
468
GDK_AVAILABLE_IN_ALL
469
470
GtkTargetList * gtk_text_buffer_get_paste_target_list   (GtkTextBuffer *buffer);

471

472
G_END_DECLS
473
474

#endif