gtktextlayout.h 19.2 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 26 27
 * 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
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
28 29 30 31 32 33 34
 *
 * 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.
35
 *
36 37 38 39 40 41 42 43 44
 * 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.
45
 *
46 47 48 49 50
 * 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.
51
 *
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
 * 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.
 *
71 72 73 74 75 76 77 78
 */
/*
 * 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/.
 */

79 80
#ifndef __GTK_TEXT_LAYOUT_H__
#define __GTK_TEXT_LAYOUT_H__
81 82 83 84 85

/* This is a "semi-private" header; it is intended for
 * use by the text widget, and the text canvas item,
 * but that's all. We may have to install it so the
 * canvas item can use it, but users are not supposed
86
 * to use it.
87
 */
88 89 90
#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
91

92
#include <gtk/gtk.h>
93

94 95
G_BEGIN_DECLS

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

102
#define GTK_TYPE_TEXT_LAYOUT             (gtk_text_layout_get_type ())
103 104 105 106 107
#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))
108

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

struct _GtkTextLayout
{
116
  GObject parent_instance;
117

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

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

126 127 128 129 130 131 132
  /* 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; */
133

134
  GtkTextBuffer *buffer;
135

136
  /* Default style used if no tags override it */
137
  GtkTextAttributes *default_style;
138

139 140 141
  /* Pango contexts used for creating layouts */
  PangoContext *ltr_context;
  PangoContext *rtl_context;
142

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

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

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

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

164 165 166 167 168
  /* 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
169 170 171 172 173 174
  /* The preedit string and attributes, if any */

  gchar *preedit_string;
  PangoAttrList *preedit_attrs;
  gint preedit_len;
  gint preedit_cursor;
175 176

  guint overwrite_mode : 1;
177 178 179 180
};

struct _GtkTextLayoutClass
{
181
  GObjectClass parent_class;
182

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

187 188
  /* A range of the layout changed appearance and possibly height
   */
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
  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);
206 207 208 209 210

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

212 213 214 215
  void (*invalidate_cursors)    (GtkTextLayout     *layout,
                                 const GtkTextIter *start,
                                 const GtkTextIter *end);

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

222 223 224 225 226
struct _GtkTextAttrAppearance
{
  PangoAttribute attr;
  GtkTextAppearance appearance;
};
227

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

233
  GtkTextDirection direction;
234 235 236

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

248
  GtkTextLine *line;
249 250
  
  GdkColor *pg_bg_color;
251

252
  GdkRectangle block_cursor;
253
  guint cursors_invalid : 1;
254 255
  guint has_block_cursor : 1;
  guint cursor_at_line_end : 1;
256 257
  guint size_only : 1;

258
  GdkRGBA *pg_bg_rgba;
259 260
};

261
#ifdef GTK_COMPILATION
262
extern G_GNUC_INTERNAL PangoAttrType gtk_text_attr_appearance_type;
263
#endif
264

265
GType         gtk_text_layout_get_type    (void) G_GNUC_CONST;
266 267 268 269 270 271 272 273 274 275 276

GtkTextLayout*     gtk_text_layout_new                   (void);
void               gtk_text_layout_set_buffer            (GtkTextLayout     *layout,
							  GtkTextBuffer     *buffer);
GtkTextBuffer     *gtk_text_layout_get_buffer            (GtkTextLayout     *layout);
void               gtk_text_layout_set_default_style     (GtkTextLayout     *layout,
							  GtkTextAttributes *values);
void               gtk_text_layout_set_contexts          (GtkTextLayout     *layout,
							  PangoContext      *ltr_context,
							  PangoContext      *rtl_context);
void               gtk_text_layout_set_cursor_direction  (GtkTextLayout     *layout,
277
                                                          GtkTextDirection   direction);
278 279
void		   gtk_text_layout_set_overwrite_mode	 (GtkTextLayout     *layout,
							  gboolean           overwrite);
280 281
void               gtk_text_layout_set_keyboard_direction (GtkTextLayout     *layout,
							   GtkTextDirection keyboard_dir);
282 283
void               gtk_text_layout_default_style_changed (GtkTextLayout     *layout);

284
void gtk_text_layout_set_screen_width       (GtkTextLayout     *layout,
285
                                             gint               width);
Owen Taylor's avatar
Owen Taylor committed
286 287 288 289 290
void gtk_text_layout_set_preedit_string     (GtkTextLayout     *layout,
 					     const gchar       *preedit_string,
 					     PangoAttrList     *preedit_attrs,
 					     gint               cursor_pos);

291
void     gtk_text_layout_set_cursor_visible (GtkTextLayout     *layout,
292
                                             gboolean           cursor_visible);
293
gboolean gtk_text_layout_get_cursor_visible (GtkTextLayout     *layout);
294 295 296 297

/* 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.
298
 *
299 300 301
 * Long-term, we would really like to be able to do these without
 * a full recompute so they may get cheaper over time.
 */
302
void    gtk_text_layout_get_size  (GtkTextLayout  *layout,
303 304
                                   gint           *width,
                                   gint           *height);
305
GSList* gtk_text_layout_get_lines (GtkTextLayout  *layout,
306 307 308 309
                                   /* [top_y, bottom_y) */
                                   gint            top_y,
                                   gint            bottom_y,
                                   gint           *first_line_y);
310

311 312
void gtk_text_layout_wrap_loop_start (GtkTextLayout *layout);
void gtk_text_layout_wrap_loop_end   (GtkTextLayout *layout);
313

314
GtkTextLineDisplay* gtk_text_layout_get_line_display  (GtkTextLayout      *layout,
315 316
                                                       GtkTextLine        *line,
                                                       gboolean            size_only);
317
void                gtk_text_layout_free_line_display (GtkTextLayout      *layout,
318
                                                       GtkTextLineDisplay *display);
319 320

void gtk_text_layout_get_line_at_y     (GtkTextLayout     *layout,
321 322 323
                                        GtkTextIter       *target_iter,
                                        gint               y,
                                        gint              *line_top);
324
void gtk_text_layout_get_iter_at_pixel (GtkTextLayout     *layout,
325 326 327
                                        GtkTextIter       *iter,
                                        gint               x,
                                        gint               y);
328 329 330 331 332
void gtk_text_layout_get_iter_at_position (GtkTextLayout     *layout,
					   GtkTextIter       *iter,
					   gint              *trailing,
					   gint               x,
					   gint               y);
333
void gtk_text_layout_invalidate        (GtkTextLayout     *layout,
334 335
                                        const GtkTextIter *start,
                                        const GtkTextIter *end);
336 337 338
void gtk_text_layout_invalidate_cursors(GtkTextLayout     *layout,
                                        const GtkTextIter *start,
                                        const GtkTextIter *end);
339
void gtk_text_layout_free_line_data    (GtkTextLayout     *layout,
340 341
                                        GtkTextLine       *line,
                                        GtkTextLineData   *line_data);
342 343 344

gboolean gtk_text_layout_is_valid        (GtkTextLayout *layout);
void     gtk_text_layout_validate_yrange (GtkTextLayout *layout,
345
                                          GtkTextIter   *anchor_line,
346 347
                                          gint           y0_,
                                          gint           y1_);
348
void     gtk_text_layout_validate        (GtkTextLayout *layout,
349
                                          gint           max_pixels);
350

351 352 353 354 355 356 357 358
/* 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.
 */
GtkTextLineData* gtk_text_layout_wrap  (GtkTextLayout   *layout,
359 360
                                        GtkTextLine     *line,
                                        GtkTextLineData *line_data); /* may be NULL */
361
void     gtk_text_layout_changed              (GtkTextLayout     *layout,
362 363 364
                                               gint               y,
                                               gint               old_height,
                                               gint               new_height);
365 366 367 368
void     gtk_text_layout_cursors_changed      (GtkTextLayout     *layout,
                                               gint               y,
                                               gint               old_height,
                                               gint               new_height);
369
void     gtk_text_layout_get_iter_location    (GtkTextLayout     *layout,
370 371
                                               const GtkTextIter *iter,
                                               GdkRectangle      *rect);
372
void     gtk_text_layout_get_line_yrange      (GtkTextLayout     *layout,
373 374 375
                                               const GtkTextIter *iter,
                                               gint              *y,
                                               gint              *height);
376 377 378 379
void     _gtk_text_layout_get_line_xrange     (GtkTextLayout     *layout,
                                               const GtkTextIter *iter,
                                               gint              *x,
                                               gint              *width);
380
void     gtk_text_layout_get_cursor_locations (GtkTextLayout     *layout,
381 382 383
                                               GtkTextIter       *iter,
                                               GdkRectangle      *strong_pos,
                                               GdkRectangle      *weak_pos);
384 385
gboolean _gtk_text_layout_get_block_cursor    (GtkTextLayout     *layout,
					       GdkRectangle      *pos);
386
gboolean gtk_text_layout_clamp_iter_to_vrange (GtkTextLayout     *layout,
387 388 389
                                               GtkTextIter       *iter,
                                               gint               top,
                                               gint               bottom);
390

391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406
gboolean gtk_text_layout_move_iter_to_line_end      (GtkTextLayout *layout,
                                                     GtkTextIter   *iter,
                                                     gint           direction);
gboolean gtk_text_layout_move_iter_to_previous_line (GtkTextLayout *layout,
                                                     GtkTextIter   *iter);
gboolean gtk_text_layout_move_iter_to_next_line     (GtkTextLayout *layout,
                                                     GtkTextIter   *iter);
void     gtk_text_layout_move_iter_to_x             (GtkTextLayout *layout,
                                                     GtkTextIter   *iter,
                                                     gint           x);
gboolean gtk_text_layout_move_iter_visually         (GtkTextLayout *layout,
                                                     GtkTextIter   *iter,
                                                     gint           count);

gboolean gtk_text_layout_iter_starts_line           (GtkTextLayout       *layout,
                                                     const GtkTextIter   *iter);
407

408 409 410 411 412
void     gtk_text_layout_get_iter_at_line           (GtkTextLayout *layout,
                                                     GtkTextIter    *iter,
                                                     GtkTextLine    *line,
                                                     gint            byte_offset);

413 414 415 416 417 418 419 420 421 422 423 424 425
/* 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.
 */
void gtk_text_child_anchor_register_child   (GtkTextChildAnchor *anchor,
                                             GtkWidget          *child,
                                             GtkTextLayout      *layout);
void gtk_text_child_anchor_unregister_child (GtkTextChildAnchor *anchor,
                                             GtkWidget          *child);

void gtk_text_child_anchor_queue_resize     (GtkTextChildAnchor *anchor,
                                             GtkTextLayout      *layout);
426

427 428 429
void gtk_text_anchored_child_set_layout     (GtkWidget          *child,
                                             GtkTextLayout      *layout);

430
void gtk_text_layout_spew (GtkTextLayout *layout);
431

432
G_END_DECLS
433

434
#endif  /* __GTK_TEXT_LAYOUT_H__ */