Pileus Git - ~andy/gtk/blob - gtk/gtktextlayout.h

   1 /* GTK - The GIMP Toolkit
   2  * gtktextlayout.h
   3  *
   4  * Copyright (c) 1992-1994 The Regents of the University of California.
   5  * Copyright (c) 1994-1997 Sun Microsystems, Inc.
   6  * Copyright (c) 2000 Red Hat, Inc.
   7  * Tk->Gtk port by Havoc Pennington
   8  * Pango support by Owen Taylor
   9  *
  10  * This file can be used under your choice of two licenses, the LGPL
  11  * and the original Tk license.
  12  *
  13  * LGPL:
  14  *
  15  * This library is free software; you can redistribute it and/or
  16  * modify it under the terms of the GNU Lesser General Public
  17  * License as published by the Free Software Foundation; either
  18  * version 2 of the License, or (at your option) any later version.
  19  *
  20  * This library is distributed in the hope that it will be useful,
  21  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  22  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  23  * Lesser General Public License for more details.
  24  *
  25  * You should have received a copy of the GNU Lesser General Public
  26  * License along with this library; if not, write to the Free
  27  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  28  *
  29  * Original Tk license:
  30  *
  31  * This software is copyrighted by the Regents of the University of
  32  * California, Sun Microsystems, Inc., and other parties.  The
  33  * following terms apply to all files associated with the software
  34  * unless explicitly disclaimed in individual files.
  35  *
  36  * The authors hereby grant permission to use, copy, modify,
  37  * distribute, and license this software and its documentation for any
  38  * purpose, provided that existing copyright notices are retained in
  39  * all copies and that this notice is included verbatim in any
  40  * distributions. No written agreement, license, or royalty fee is
  41  * required for any of the authorized uses.  Modifications to this
  42  * software may be copyrighted by their authors and need not follow
  43  * the licensing terms described here, provided that the new terms are
  44  * clearly indicated on the first page of each file where they apply.
  45  *
  46  * IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY
  47  * PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
  48  * DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION,
  49  * OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED
  50  * OF THE POSSIBILITY OF SUCH DAMAGE.
  51  *
  52  * THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
  53  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  54  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
  55  * NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS,
  56  * AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
  57  * MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  58  *
  59  * GOVERNMENT USE: If you are acquiring this software on behalf of the
  60  * U.S. government, the Government shall have only "Restricted Rights"
  61  * in the software and related documentation as defined in the Federal
  62  * Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
  63  * are acquiring the software on behalf of the Department of Defense,
  64  * the software shall be classified as "Commercial Computer Software"
  65  * and the Government shall have only "Restricted Rights" as defined
  66  * in Clause 252.227-7013 (c) (1) of DFARs.  Notwithstanding the
  67  * foregoing, the authors grant the U.S. Government and others acting
  68  * in its behalf permission to use and distribute the software in
  69  * accordance with the terms specified in this license.
  70  *
  71  */
  72 /*
  73  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  74  * file for a list of people on the GTK+ Team.  See the ChangeLog
  75  * files for a list of changes.  These files are distributed with
  76  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  77  */
  78
  79 #ifndef GTK_TEXT_LAYOUT_H
  80 #define GTK_TEXT_LAYOUT_H
  81
  82 #ifdef __cplusplus
  83 extern "C" {
  84 #endif /* __cplusplus */
  85
  86 /* This is a "semi-private" header; it is intended for
  87  * use by the text widget, and the text canvas item,
  88  * but that's all. We may have to install it so the
  89  * canvas item can use it, but users are not supposed
  90  * to use it.
  91  */
  92
  93 #include <gtk/gtktextbuffer.h>
  94 #include <gtk/gtktextiter.h>
  95
  96 /* forward declarations that have to be here to avoid including
  97  * gtktextbtree.h
  98  */
  99 typedef struct _GtkTextLine     GtkTextLine;
 100 typedef struct _GtkTextLineData GtkTextLineData;
 101
 102 #define GTK_TYPE_TEXT_LAYOUT             (gtk_text_layout_get_type ())
 103 #define GTK_TEXT_LAYOUT(obj)             (GTK_CHECK_CAST ((obj), GTK_TYPE_TEXT_LAYOUT, GtkTextLayout))
 104 #define GTK_TEXT_LAYOUT_CLASS(klass)     (GTK_CHECK_CLASS_CAST ((klass), GTK_TYPE_TEXT_LAYOUT, GtkTextLayoutClass))
 105 #define GTK_IS_TEXT_LAYOUT(obj)          (GTK_CHECK_TYPE ((obj), GTK_TYPE_TEXT_LAYOUT))
 106 #define GTK_IS_TEXT_LAYOUT_CLASS(klass)  (GTK_CHECK_CLASS_TYPE ((klass), GTK_TYPE_TEXT_LAYOUT))
 107 #define GTK_TEXT_LAYOUT_GET_CLASS(obj)   (GTK_CHECK_GET_CLASS ((obj), GTK_TYPE_TEXT_LAYOUT, GtkTextLayoutClass))
 108
 109 typedef struct _GtkTextLayout         GtkTextLayout;
 110 typedef struct _GtkTextLayoutClass    GtkTextLayoutClass;
 111 typedef struct _GtkTextLineDisplay    GtkTextLineDisplay;
 112 typedef struct _GtkTextCursorDisplay  GtkTextCursorDisplay;
 113 typedef struct _GtkTextAttrAppearance GtkTextAttrAppearance;
 114
 115 struct _GtkTextLayout
 116 {
 117   GtkObject parent_instance;
 118
 119   /* width of the display area on-screen,
 120    * i.e. pixels we should wrap to fit inside. */
 121   gint screen_width;
 122
 123   /* width/height of the total logical area being layed out */
 124   gint width;
 125   gint height;
 126
 127   /* Pixel offsets from the left and from the top to be used when we
 128    * draw; these allow us to create left/top margins. We don't need
 129    * anything special for bottom/right margins, because those don't
 130    * affect drawing.
 131    */
 132   /* gint left_edge; */
 133   /* gint top_edge; */
 134
 135   GtkTextBuffer *buffer;
 136
 137   /* Default style used if no tags override it */
 138   GtkTextAttributes *default_style;
 139
 140   /* Pango contexts used for creating layouts */
 141   PangoContext *ltr_context;
 142   PangoContext *rtl_context;
 143
 144   /* A cache of one style; this is used to ensure
 145    * we don't constantly regenerate the style
 146    * over long runs with the same style. */
 147   GtkTextAttributes *one_style_cache;
 148
 149   /* A cache of one line display. Getting the same line
 150    * many times in a row is the most common case.
 151    */
 152   GtkTextLineDisplay *one_display_cache;
 153
 154   /* Whether we are allowed to wrap right now */
 155   gint wrap_loop_count;
 156
 157   /* Whether to show the insertion cursor */
 158   guint cursor_visible : 1;
 159
 160   /* The preedit string and attributes, if any */
 161
 162   gchar *preedit_string;
 163   PangoAttrList *preedit_attrs;
 164   gint preedit_len;
 165   gint preedit_cursor;
 166 };
 167
 168 struct _GtkTextLayoutClass
 169 {
 170   GtkObjectClass parent_class;
 171
 172   /* Some portion of the layout was invalidated
 173    */
 174   void  (*invalidated)  (GtkTextLayout *layout);
 175
 176   /* A range of the layout changed appearance and possibly height
 177    */
 178   void  (*changed)              (GtkTextLayout     *layout,
 179                                  gint               y,
 180                                  gint               old_height,
 181                                  gint               new_height);
 182   GtkTextLineData* (*wrap)      (GtkTextLayout     *layout,
 183                                  GtkTextLine       *line,
 184                                  GtkTextLineData   *line_data); /* may be NULL */
 185   void  (*get_log_attrs)        (GtkTextLayout     *layout,
 186                                  GtkTextLine       *line,
 187                                  PangoLogAttr     **attrs,
 188                                  gint              *n_attrs);
 189   void  (*invalidate)           (GtkTextLayout     *layout,
 190                                  const GtkTextIter *start,
 191                                  const GtkTextIter *end);
 192   void  (*free_line_data)       (GtkTextLayout     *layout,
 193                                  GtkTextLine       *line,
 194                                  GtkTextLineData   *line_data);
 195
 196   void (*allocate_child)        (GtkTextLayout     *layout,
 197                                  GtkWidget         *child,
 198                                  gint               x,
 199                                  gint               y);
 200 };
 201
 202 struct _GtkTextAttrAppearance
 203 {
 204   PangoAttribute attr;
 205   GtkTextAppearance appearance;
 206 };
 207 struct _GtkTextCursorDisplay
 208 {
 209   gint x;
 210   gint y;
 211   gint height;
 212   guint is_strong : 1;
 213   guint is_weak : 1;
 214 };
 215 struct _GtkTextLineDisplay
 216 {
 217   PangoLayout *layout;
 218   GSList *cursors;
 219   GSList *shaped_objects;
 220
 221   GtkTextDirection direction;
 222
 223   gint width;                   /* Width of layout */
 224   gint total_width;             /* width - margins, if no width set on layout, if width set on layout, -1 */
 225   gint height;
 226   gint x_offset;                /* Amount layout is shifted from left edge */
 227   gint left_margin;
 228   gint right_margin;
 229   gint top_margin;
 230   gint bottom_margin;
 231   gint insert_index;            /* Byte index of insert cursor within para or -1 */
 232
 233   gboolean size_only;
 234   GtkTextLine *line;
 235 };
 236
 237 extern PangoAttrType gtk_text_attr_appearance_type;
 238
 239 GtkType         gtk_text_layout_get_type    (void) G_GNUC_CONST;
 240 GtkTextLayout*  gtk_text_layout_new         (void);
 241 void gtk_text_layout_set_buffer             (GtkTextLayout     *layout,
 242                                              GtkTextBuffer     *buffer);
 243 void gtk_text_layout_set_default_style      (GtkTextLayout     *layout,
 244                                              GtkTextAttributes *values);
 245 void gtk_text_layout_set_contexts           (GtkTextLayout     *layout,
 246                                              PangoContext      *ltr_context,
 247                                              PangoContext      *rtl_context);
 248 void gtk_text_layout_default_style_changed  (GtkTextLayout     *layout);
 249
 250 void gtk_text_layout_set_screen_width       (GtkTextLayout     *layout,
 251                                              gint               width);
 252 void gtk_text_layout_set_preedit_string     (GtkTextLayout     *layout,
 253                                              const gchar       *preedit_string,
 254                                              PangoAttrList     *preedit_attrs,
 255                                              gint               cursor_pos);
 256
 257 void     gtk_text_layout_set_cursor_visible (GtkTextLayout     *layout,
 258                                              gboolean           cursor_visible);
 259 gboolean gtk_text_layout_get_cursor_visible (GtkTextLayout     *layout);
 260
 261 /* Getting the size or the lines potentially results in a call to
 262  * recompute, which is pretty massively expensive. Thus it should
 263  * basically only be done in an idle handler.
 264  *
 265  * Long-term, we would really like to be able to do these without
 266  * a full recompute so they may get cheaper over time.
 267  */
 268 void    gtk_text_layout_get_size  (GtkTextLayout  *layout,
 269                                    gint           *width,
 270                                    gint           *height);
 271 GSList* gtk_text_layout_get_lines (GtkTextLayout  *layout,
 272                                    /* [top_y, bottom_y) */
 273                                    gint            top_y,
 274                                    gint            bottom_y,
 275                                    gint           *first_line_y);
 276
 277 void gtk_text_layout_wrap_loop_start (GtkTextLayout *layout);
 278 void gtk_text_layout_wrap_loop_end   (GtkTextLayout *layout);
 279
 280 GtkTextLineDisplay* gtk_text_layout_get_line_display  (GtkTextLayout      *layout,
 281                                                        GtkTextLine        *line,
 282                                                        gboolean            size_only);
 283 void                gtk_text_layout_free_line_display (GtkTextLayout      *layout,
 284                                                        GtkTextLineDisplay *display);
 285
 286 void gtk_text_layout_get_line_at_y     (GtkTextLayout     *layout,
 287                                         GtkTextIter       *target_iter,
 288                                         gint               y,
 289                                         gint              *line_top);
 290 void gtk_text_layout_get_iter_at_pixel (GtkTextLayout     *layout,
 291                                         GtkTextIter       *iter,
 292                                         gint               x,
 293                                         gint               y);
 294 void gtk_text_layout_invalidate        (GtkTextLayout     *layout,
 295                                         const GtkTextIter *start,
 296                                         const GtkTextIter *end);
 297 void gtk_text_layout_free_line_data    (GtkTextLayout     *layout,
 298                                         GtkTextLine       *line,
 299                                         GtkTextLineData   *line_data);
 300
 301 gboolean gtk_text_layout_is_valid        (GtkTextLayout *layout);
 302 void     gtk_text_layout_validate_yrange (GtkTextLayout *layout,
 303                                           GtkTextIter   *anchor_line,
 304                                           gint           y0,
 305                                           gint           y1);
 306 void     gtk_text_layout_validate        (GtkTextLayout *layout,
 307                                           gint           max_pixels);
 308
 309 /* This function should return the passed-in line data,
 310  * OR remove the existing line data from the line, and
 311  * return a NEW line data after adding it to the line.
 312  * That is, invariant after calling the callback is that
 313  * there should be exactly one line data for this view
 314  * stored on the btree line.
 315  */
 316 GtkTextLineData* gtk_text_layout_wrap  (GtkTextLayout   *layout,
 317                                         GtkTextLine     *line,
 318                                         GtkTextLineData *line_data); /* may be NULL */
 319 void     gtk_text_layout_changed              (GtkTextLayout     *layout,
 320                                                gint               y,
 321                                                gint               old_height,
 322                                                gint               new_height);
 323 void     gtk_text_layout_get_iter_location    (GtkTextLayout     *layout,
 324                                                const GtkTextIter *iter,
 325                                                GdkRectangle      *rect);
 326 void     gtk_text_layout_get_line_yrange      (GtkTextLayout     *layout,
 327                                                const GtkTextIter *iter,
 328                                                gint              *y,
 329                                                gint              *height);
 330 void     gtk_text_layout_get_cursor_locations (GtkTextLayout     *layout,
 331                                                GtkTextIter       *iter,
 332                                                GdkRectangle      *strong_pos,
 333                                                GdkRectangle      *weak_pos);
 334 gboolean gtk_text_layout_clamp_iter_to_vrange (GtkTextLayout     *layout,
 335                                                GtkTextIter       *iter,
 336                                                gint               top,
 337                                                gint               bottom);
 338
 339 void gtk_text_layout_move_iter_to_line_end      (GtkTextLayout *layout,
 340                                                  GtkTextIter   *iter,
 341                                                  gint           direction);
 342 void gtk_text_layout_move_iter_to_previous_line (GtkTextLayout *layout,
 343                                                  GtkTextIter   *iter);
 344 void gtk_text_layout_move_iter_to_next_line     (GtkTextLayout *layout,
 345                                                  GtkTextIter   *iter);
 346 void gtk_text_layout_move_iter_to_x             (GtkTextLayout *layout,
 347                                                  GtkTextIter   *iter,
 348                                                  gint           x);
 349 void gtk_text_layout_move_iter_visually         (GtkTextLayout *layout,
 350                                                  GtkTextIter   *iter,
 351                                                  gint           count);
 352
 353
 354 /* Don't use these. Use gtk_text_view_add_child_at_anchor().
 355  * These functions are defined in gtktextchild.c, but here
 356  * since they are semi-public and require GtkTextLayout to
 357  * be declared.
 358  */
 359 void gtk_text_child_anchor_register_child   (GtkTextChildAnchor *anchor,
 360                                              GtkWidget          *child,
 361                                              GtkTextLayout      *layout);
 362 void gtk_text_child_anchor_unregister_child (GtkTextChildAnchor *anchor,
 363                                              GtkWidget          *child);
 364
 365 void gtk_text_child_anchor_queue_resize     (GtkTextChildAnchor *anchor,
 366                                              GtkTextLayout      *layout);
 367
 368 void gtk_text_layout_spew (GtkTextLayout *layout);
 369
 370 #ifdef __cplusplus
 371 }
 372 #endif /* __cplusplus */
 373
 374 #endif  /* GTK_TEXT_LAYOUT_H */