gtktextlayout.h 20.1 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GTK - The GIMP Toolkit
2
 * gtktextlayout.h
3
 *
4 5 6 7 8 9 10 11
 * Copyright (c) 1992-1994 The Regents of the University of California.
 * Copyright (c) 1994-1997 Sun Microsystems, Inc.
 * Copyright (c) 2000 Red Hat, Inc.
 * Tk->Gtk port by Havoc Pennington
 * Pango support by Owen Taylor
 *
 * This file can be used under your choice of two licenses, the LGPL
 * and the original Tk license.
12
 *
13
 * LGPL:
14
 *
15 16 17 18 19 20 21 22 23 24 25
 * 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
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * 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
26
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
27 28 29 30 31 32 33
 *
 * Original Tk license:
 *
 * This software is copyrighted by the Regents of the University of
 * California, Sun Microsystems, Inc., and other parties.  The
 * following terms apply to all files associated with the software
 * unless explicitly disclaimed in individual files.
34
 *
35 36 37 38 39 40 41 42 43
 * The authors hereby grant permission to use, copy, modify,
 * distribute, and license this software and its documentation for any
 * purpose, provided that existing copyright notices are retained in
 * all copies and that this notice is included verbatim in any
 * distributions. No written agreement, license, or royalty fee is
 * required for any of the authorized uses.  Modifications to this
 * software may be copyrighted by their authors and need not follow
 * the licensing terms described here, provided that the new terms are
 * clearly indicated on the first page of each file where they apply.
44
 *
45 46 47 48 49
 * IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY
 * PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
 * DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION,
 * OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
50
 *
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
 * THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
 * NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS,
 * AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
 * MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 *
 * GOVERNMENT USE: If you are acquiring this software on behalf of the
 * U.S. government, the Government shall have only "Restricted Rights"
 * in the software and related documentation as defined in the Federal
 * Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
 * are acquiring the software on behalf of the Department of Defense,
 * the software shall be classified as "Commercial Computer Software"
 * and the Government shall have only "Restricted Rights" as defined
 * in Clause 252.227-7013 (c) (1) of DFARs.  Notwithstanding the
 * foregoing, the authors grant the U.S. Government and others acting
 * in its behalf permission to use and distribute the software in
 * accordance with the terms specified in this license.
 *
70 71 72 73 74 75 76 77
 */
/*
 * 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
 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
 */

78 79
#ifndef __GTK_TEXT_LAYOUT_H__
#define __GTK_TEXT_LAYOUT_H__
80 81 82

/* This is a "semi-private" header; it is intended for
 * use by the text widget, and the text canvas item,
83
 * but that’s all. We may have to install it so the
84
 * canvas item can use it, but users are not supposed
85
 * to use it.
86
 */
87 88 89
#ifndef GTK_TEXT_USE_INTERNAL_UNSUPPORTED_API
#error "You are not supposed to be including this file; the equivalent public API is in gtktextview.h"
#endif
90

91
#include <gtk/gtk.h>
92

93 94
G_BEGIN_DECLS

95 96 97 98 99 100
/* forward declarations that have to be here to avoid including
 * gtktextbtree.h
 */
typedef struct _GtkTextLine     GtkTextLine;
typedef struct _GtkTextLineData GtkTextLineData;

101
#define GTK_TYPE_TEXT_LAYOUT             (gtk_text_layout_get_type ())
102 103 104 105 106
#define GTK_TEXT_LAYOUT(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TEXT_LAYOUT, GtkTextLayout))
#define GTK_TEXT_LAYOUT_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_TEXT_LAYOUT, GtkTextLayoutClass))
#define GTK_IS_TEXT_LAYOUT(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_TEXT_LAYOUT))
#define GTK_IS_TEXT_LAYOUT_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_TEXT_LAYOUT))
#define GTK_TEXT_LAYOUT_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_TEXT_LAYOUT, GtkTextLayoutClass))
107

108 109 110
typedef struct _GtkTextLayout         GtkTextLayout;
typedef struct _GtkTextLayoutClass    GtkTextLayoutClass;
typedef struct _GtkTextLineDisplay    GtkTextLineDisplay;
111 112 113 114
typedef struct _GtkTextAttrAppearance GtkTextAttrAppearance;

struct _GtkTextLayout
{
115
  GObject parent_instance;
116

117 118 119
  /* width of the display area on-screen,
   * i.e. pixels we should wrap to fit inside. */
  gint screen_width;
120

121 122 123
  /* width/height of the total logical area being layed out */
  gint width;
  gint height;
124

125 126 127 128 129 130 131
  /* Pixel offsets from the left and from the top to be used when we
   * draw; these allow us to create left/top margins. We don't need
   * anything special for bottom/right margins, because those don't
   * affect drawing.
   */
  /* gint left_edge; */
  /* gint top_edge; */
132

133
  GtkTextBuffer *buffer;
134

135 136 137
  gint left_padding;
  gint right_padding;

138
  /* Default style used if no tags override it */
139
  GtkTextAttributes *default_style;
140

141 142 143
  /* Pango contexts used for creating layouts */
  PangoContext *ltr_context;
  PangoContext *rtl_context;
144

145 146 147
  /* A cache of one style; this is used to ensure
   * we don't constantly regenerate the style
   * over long runs with the same style. */
148
  GtkTextAttributes *one_style_cache;
149

150 151 152 153
  /* A cache of one line display. Getting the same line
   * many times in a row is the most common case.
   */
  GtkTextLineDisplay *one_display_cache;
154

155 156
  /* Whether we are allowed to wrap right now */
  gint wrap_loop_count;
157
  
158 159
  /* Whether to show the insertion cursor */
  guint cursor_visible : 1;
Owen Taylor's avatar
Owen Taylor committed
160

161 162 163
  /* For what GtkTextDirection to draw cursor GTK_TEXT_DIR_NONE -
   * means draw both cursors.
   */
164
  guint cursor_direction : 2;
165

166 167 168 169 170
  /* The keyboard direction is used to default the alignment when
     there are no strong characters.
  */
  guint keyboard_direction : 2;

Owen Taylor's avatar
Owen Taylor committed
171 172 173 174 175 176
  /* The preedit string and attributes, if any */

  gchar *preedit_string;
  PangoAttrList *preedit_attrs;
  gint preedit_len;
  gint preedit_cursor;
177 178

  guint overwrite_mode : 1;
179 180 181 182
};

struct _GtkTextLayoutClass
{
183
  GObjectClass parent_class;
184

185 186
  /* Some portion of the layout was invalidated
   */
187 188
  void  (*invalidated)  (GtkTextLayout *layout);

189 190
  /* A range of the layout changed appearance and possibly height
   */
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
  void  (*changed)              (GtkTextLayout     *layout,
                                 gint               y,
                                 gint               old_height,
                                 gint               new_height);
  GtkTextLineData* (*wrap)      (GtkTextLayout     *layout,
                                 GtkTextLine       *line,
                                 GtkTextLineData   *line_data); /* may be NULL */
  void  (*get_log_attrs)        (GtkTextLayout     *layout,
                                 GtkTextLine       *line,
                                 PangoLogAttr     **attrs,
                                 gint              *n_attrs);
  void  (*invalidate)           (GtkTextLayout     *layout,
                                 const GtkTextIter *start,
                                 const GtkTextIter *end);
  void  (*free_line_data)       (GtkTextLayout     *layout,
                                 GtkTextLine       *line,
                                 GtkTextLineData   *line_data);
208 209 210 211 212

  void (*allocate_child)        (GtkTextLayout     *layout,
                                 GtkWidget         *child,
                                 gint               x,
                                 gint               y);
213

214 215 216 217
  void (*invalidate_cursors)    (GtkTextLayout     *layout,
                                 const GtkTextIter *start,
                                 const GtkTextIter *end);

218 219 220 221
  /* Padding for future expansion */
  void (*_gtk_reserved1) (void);
  void (*_gtk_reserved2) (void);
  void (*_gtk_reserved3) (void);
222
};
223

224 225 226 227 228
struct _GtkTextAttrAppearance
{
  PangoAttribute attr;
  GtkTextAppearance appearance;
};
229

230 231 232
struct _GtkTextLineDisplay
{
  PangoLayout *layout;
233
  GArray *cursors;      /* indexes of cursors in the PangoLayout */
234

235
  GtkTextDirection direction;
236 237 238

  gint width;                   /* Width of layout */
  gint total_width;             /* width - margins, if no width set on layout, if width set on layout, -1 */
239
  gint height;
240 241 242 243
  /* Amount layout is shifted from left edge - this is the left margin
   * plus any other factors, such as alignment or indentation.
   */
  gint x_offset;
244 245 246 247
  gint left_margin;
  gint right_margin;
  gint top_margin;
  gint bottom_margin;
Owen Taylor's avatar
Owen Taylor committed
248
  gint insert_index;		/* Byte index of insert cursor within para or -1 */
249

250
  GtkTextLine *line;
251 252
  
  GdkColor *pg_bg_color;
253

254
  GdkRectangle block_cursor;
255
  guint cursors_invalid : 1;
256 257
  guint has_block_cursor : 1;
  guint cursor_at_line_end : 1;
258 259
  guint size_only : 1;

260
  GdkRGBA *pg_bg_rgba;
261 262
};

263
#ifdef GTK_COMPILATION
264
extern G_GNUC_INTERNAL PangoAttrType gtk_text_attr_appearance_type;
265
#endif
266

267
GDK_AVAILABLE_IN_ALL
268
GType         gtk_text_layout_get_type    (void) G_GNUC_CONST;
269

270
GDK_AVAILABLE_IN_ALL
271
GtkTextLayout*     gtk_text_layout_new                   (void);
272
GDK_AVAILABLE_IN_ALL
273 274
void               gtk_text_layout_set_buffer            (GtkTextLayout     *layout,
							  GtkTextBuffer     *buffer);
275
GDK_AVAILABLE_IN_ALL
276
GtkTextBuffer     *gtk_text_layout_get_buffer            (GtkTextLayout     *layout);
277
GDK_AVAILABLE_IN_ALL
278 279
void               gtk_text_layout_set_default_style     (GtkTextLayout     *layout,
							  GtkTextAttributes *values);
280
GDK_AVAILABLE_IN_ALL
281 282 283
void               gtk_text_layout_set_contexts          (GtkTextLayout     *layout,
							  PangoContext      *ltr_context,
							  PangoContext      *rtl_context);
284
GDK_AVAILABLE_IN_ALL
285
void               gtk_text_layout_set_cursor_direction  (GtkTextLayout     *layout,
286
                                                          GtkTextDirection   direction);
287
GDK_AVAILABLE_IN_ALL
288 289
void		   gtk_text_layout_set_overwrite_mode	 (GtkTextLayout     *layout,
							  gboolean           overwrite);
290
GDK_AVAILABLE_IN_ALL
291 292
void               gtk_text_layout_set_keyboard_direction (GtkTextLayout     *layout,
							   GtkTextDirection keyboard_dir);
293
GDK_AVAILABLE_IN_ALL
294 295
void               gtk_text_layout_default_style_changed (GtkTextLayout     *layout);

296
GDK_AVAILABLE_IN_ALL
297
void gtk_text_layout_set_screen_width       (GtkTextLayout     *layout,
298
                                             gint               width);
299
GDK_AVAILABLE_IN_ALL
Owen Taylor's avatar
Owen Taylor committed
300 301 302 303 304
void gtk_text_layout_set_preedit_string     (GtkTextLayout     *layout,
 					     const gchar       *preedit_string,
 					     PangoAttrList     *preedit_attrs,
 					     gint               cursor_pos);

305
GDK_AVAILABLE_IN_ALL
306
void     gtk_text_layout_set_cursor_visible (GtkTextLayout     *layout,
307
                                             gboolean           cursor_visible);
308
GDK_AVAILABLE_IN_ALL
309
gboolean gtk_text_layout_get_cursor_visible (GtkTextLayout     *layout);
310 311 312 313

/* Getting the size or the lines potentially results in a call to
 * recompute, which is pretty massively expensive. Thus it should
 * basically only be done in an idle handler.
314
 *
315 316 317
 * Long-term, we would really like to be able to do these without
 * a full recompute so they may get cheaper over time.
 */
318
GDK_AVAILABLE_IN_ALL
319
void    gtk_text_layout_get_size  (GtkTextLayout  *layout,
320 321
                                   gint           *width,
                                   gint           *height);
322
GDK_AVAILABLE_IN_ALL
323
GSList* gtk_text_layout_get_lines (GtkTextLayout  *layout,
324 325 326 327
                                   /* [top_y, bottom_y) */
                                   gint            top_y,
                                   gint            bottom_y,
                                   gint           *first_line_y);
328

329
GDK_AVAILABLE_IN_ALL
330
void gtk_text_layout_wrap_loop_start (GtkTextLayout *layout);
331
GDK_AVAILABLE_IN_ALL
332
void gtk_text_layout_wrap_loop_end   (GtkTextLayout *layout);
333

334
GDK_AVAILABLE_IN_ALL
335
GtkTextLineDisplay* gtk_text_layout_get_line_display  (GtkTextLayout      *layout,
336 337
                                                       GtkTextLine        *line,
                                                       gboolean            size_only);
338
GDK_AVAILABLE_IN_ALL
339
void                gtk_text_layout_free_line_display (GtkTextLayout      *layout,
340
                                                       GtkTextLineDisplay *display);
341

342
GDK_AVAILABLE_IN_ALL
343
void gtk_text_layout_get_line_at_y     (GtkTextLayout     *layout,
344 345 346
                                        GtkTextIter       *target_iter,
                                        gint               y,
                                        gint              *line_top);
347
GDK_AVAILABLE_IN_ALL
348 349 350 351
gboolean gtk_text_layout_get_iter_at_pixel (GtkTextLayout     *layout,
                                            GtkTextIter       *iter,
                                            gint               x,
                                            gint               y);
352
GDK_AVAILABLE_IN_ALL
353 354 355 356 357
gboolean gtk_text_layout_get_iter_at_position (GtkTextLayout     *layout,
                                               GtkTextIter       *iter,
                                               gint              *trailing,
                                               gint               x,
                                               gint               y);
358
GDK_AVAILABLE_IN_ALL
359
void gtk_text_layout_invalidate        (GtkTextLayout     *layout,
360 361
                                        const GtkTextIter *start,
                                        const GtkTextIter *end);
362
GDK_AVAILABLE_IN_ALL
363 364 365
void gtk_text_layout_invalidate_cursors(GtkTextLayout     *layout,
                                        const GtkTextIter *start,
                                        const GtkTextIter *end);
366
GDK_AVAILABLE_IN_ALL
367
void gtk_text_layout_free_line_data    (GtkTextLayout     *layout,
368 369
                                        GtkTextLine       *line,
                                        GtkTextLineData   *line_data);
370

371
GDK_AVAILABLE_IN_ALL
372
gboolean gtk_text_layout_is_valid        (GtkTextLayout *layout);
373
GDK_AVAILABLE_IN_ALL
374
void     gtk_text_layout_validate_yrange (GtkTextLayout *layout,
375
                                          GtkTextIter   *anchor_line,
376 377
                                          gint           y0_,
                                          gint           y1_);
378
GDK_AVAILABLE_IN_ALL
379
void     gtk_text_layout_validate        (GtkTextLayout *layout,
380
                                          gint           max_pixels);
381

382 383 384 385 386 387 388
/* This function should return the passed-in line data,
 * OR remove the existing line data from the line, and
 * return a NEW line data after adding it to the line.
 * That is, invariant after calling the callback is that
 * there should be exactly one line data for this view
 * stored on the btree line.
 */
389
GDK_AVAILABLE_IN_ALL
390
GtkTextLineData* gtk_text_layout_wrap  (GtkTextLayout   *layout,
391 392
                                        GtkTextLine     *line,
                                        GtkTextLineData *line_data); /* may be NULL */
393
GDK_AVAILABLE_IN_ALL
394
void     gtk_text_layout_changed              (GtkTextLayout     *layout,
395 396 397
                                               gint               y,
                                               gint               old_height,
                                               gint               new_height);
398
GDK_AVAILABLE_IN_ALL
399 400 401 402
void     gtk_text_layout_cursors_changed      (GtkTextLayout     *layout,
                                               gint               y,
                                               gint               old_height,
                                               gint               new_height);
403
GDK_AVAILABLE_IN_ALL
404
void     gtk_text_layout_get_iter_location    (GtkTextLayout     *layout,
405 406
                                               const GtkTextIter *iter,
                                               GdkRectangle      *rect);
407
GDK_AVAILABLE_IN_ALL
408
void     gtk_text_layout_get_line_yrange      (GtkTextLayout     *layout,
409 410 411
                                               const GtkTextIter *iter,
                                               gint              *y,
                                               gint              *height);
412
GDK_AVAILABLE_IN_ALL
413
void     gtk_text_layout_get_cursor_locations (GtkTextLayout     *layout,
414 415 416
                                               GtkTextIter       *iter,
                                               GdkRectangle      *strong_pos,
                                               GdkRectangle      *weak_pos);
417 418
gboolean _gtk_text_layout_get_block_cursor    (GtkTextLayout     *layout,
					       GdkRectangle      *pos);
419
GDK_AVAILABLE_IN_ALL
420
gboolean gtk_text_layout_clamp_iter_to_vrange (GtkTextLayout     *layout,
421 422 423
                                               GtkTextIter       *iter,
                                               gint               top,
                                               gint               bottom);
424

425
GDK_AVAILABLE_IN_ALL
426 427 428
gboolean gtk_text_layout_move_iter_to_line_end      (GtkTextLayout *layout,
                                                     GtkTextIter   *iter,
                                                     gint           direction);
429
GDK_AVAILABLE_IN_ALL
430 431
gboolean gtk_text_layout_move_iter_to_previous_line (GtkTextLayout *layout,
                                                     GtkTextIter   *iter);
432
GDK_AVAILABLE_IN_ALL
433 434
gboolean gtk_text_layout_move_iter_to_next_line     (GtkTextLayout *layout,
                                                     GtkTextIter   *iter);
435
GDK_AVAILABLE_IN_ALL
436 437 438
void     gtk_text_layout_move_iter_to_x             (GtkTextLayout *layout,
                                                     GtkTextIter   *iter,
                                                     gint           x);
439
GDK_AVAILABLE_IN_ALL
440 441 442 443
gboolean gtk_text_layout_move_iter_visually         (GtkTextLayout *layout,
                                                     GtkTextIter   *iter,
                                                     gint           count);

444
GDK_AVAILABLE_IN_ALL
445 446
gboolean gtk_text_layout_iter_starts_line           (GtkTextLayout       *layout,
                                                     const GtkTextIter   *iter);
447

448
GDK_AVAILABLE_IN_ALL
449 450 451 452 453
void     gtk_text_layout_get_iter_at_line           (GtkTextLayout *layout,
                                                     GtkTextIter    *iter,
                                                     GtkTextLine    *line,
                                                     gint            byte_offset);

454 455 456 457 458
/* Don't use these. Use gtk_text_view_add_child_at_anchor().
 * These functions are defined in gtktextchild.c, but here
 * since they are semi-public and require GtkTextLayout to
 * be declared.
 */
459
GDK_AVAILABLE_IN_ALL
460 461 462
void gtk_text_child_anchor_register_child   (GtkTextChildAnchor *anchor,
                                             GtkWidget          *child,
                                             GtkTextLayout      *layout);
463
GDK_AVAILABLE_IN_ALL
464 465 466
void gtk_text_child_anchor_unregister_child (GtkTextChildAnchor *anchor,
                                             GtkWidget          *child);

467
GDK_AVAILABLE_IN_ALL
468 469
void gtk_text_child_anchor_queue_resize     (GtkTextChildAnchor *anchor,
                                             GtkTextLayout      *layout);
470

471
GDK_AVAILABLE_IN_ALL
472 473 474
void gtk_text_anchored_child_set_layout     (GtkWidget          *child,
                                             GtkTextLayout      *layout);

475
GDK_AVAILABLE_IN_ALL
476
void gtk_text_layout_spew (GtkTextLayout *layout);
477

478
G_END_DECLS
479

480
#endif  /* __GTK_TEXT_LAYOUT_H__ */