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, see <http://www.gnu.org/licenses/>.
  27  *
  28  * Original Tk license:
  29  *
  30  * This software is copyrighted by the Regents of the University of
  31  * California, Sun Microsystems, Inc., and other parties.  The
  32  * following terms apply to all files associated with the software
  33  * unless explicitly disclaimed in individual files.
  34  *
  35  * The authors hereby grant permission to use, copy, modify,
  36  * distribute, and license this software and its documentation for any
  37  * purpose, provided that existing copyright notices are retained in
  38  * all copies and that this notice is included verbatim in any
  39  * distributions. No written agreement, license, or royalty fee is
  40  * required for any of the authorized uses.  Modifications to this
  41  * software may be copyrighted by their authors and need not follow
  42  * the licensing terms described here, provided that the new terms are
  43  * clearly indicated on the first page of each file where they apply.
  44  *
  45  * IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY
  46  * PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
  47  * DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION,
  48  * OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED
  49  * OF THE POSSIBILITY OF SUCH DAMAGE.
  50  *
  51  * THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
  52  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  53  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
  54  * NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS,
  55  * AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
  56  * MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  57  *
  58  * GOVERNMENT USE: If you are acquiring this software on behalf of the
  59  * U.S. government, the Government shall have only "Restricted Rights"
  60  * in the software and related documentation as defined in the Federal
  61  * Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
  62  * are acquiring the software on behalf of the Department of Defense,
  63  * the software shall be classified as "Commercial Computer Software"
  64  * and the Government shall have only "Restricted Rights" as defined
  65  * in Clause 252.227-7013 (c) (1) of DFARs.  Notwithstanding the
  66  * foregoing, the authors grant the U.S. Government and others acting
  67  * in its behalf permission to use and distribute the software in
  68  * accordance with the terms specified in this license.
  69  *
  70  */
  71 /*
  72  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  73  * file for a list of people on the GTK+ Team.  See the ChangeLog
  74  * files for a list of changes.  These files are distributed with
  75  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  76  */
  77
  78 #ifndef __GTK_TEXT_LAYOUT_H__
  79 #define __GTK_TEXT_LAYOUT_H__
  80
  81 /* This is a "semi-private" header; it is intended for
  82  * 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 #ifndef GTK_TEXT_USE_INTERNAL_UNSUPPORTED_API
  88 #error "You are not supposed to be including this file; the equivalent public API is in gtktextview.h"
  89 #endif
  90
  91 #include <gtk/gtk.h>
  92
  93 G_BEGIN_DECLS
  94
  95 /* forward declarations that have to be here to avoid including
  96  * gtktextbtree.h
  97  */
  98 typedef struct _GtkTextLine     GtkTextLine;
  99 typedef struct _GtkTextLineData GtkTextLineData;
 100
 101 #define GTK_TYPE_TEXT_LAYOUT             (gtk_text_layout_get_type ())
 102 #define GTK_TEXT_LAYOUT(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TEXT_LAYOUT, GtkTextLayout))
 103 #define GTK_TEXT_LAYOUT_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_TEXT_LAYOUT, GtkTextLayoutClass))
 104 #define GTK_IS_TEXT_LAYOUT(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_TEXT_LAYOUT))
 105 #define GTK_IS_TEXT_LAYOUT_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_TEXT_LAYOUT))
 106 #define GTK_TEXT_LAYOUT_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_TEXT_LAYOUT, GtkTextLayoutClass))
 107
 108 typedef struct _GtkTextLayout         GtkTextLayout;
 109 typedef struct _GtkTextLayoutClass    GtkTextLayoutClass;
 110 typedef struct _GtkTextLineDisplay    GtkTextLineDisplay;
 111 typedef struct _GtkTextAttrAppearance GtkTextAttrAppearance;
 112
 113 struct _GtkTextLayout
 114 {
 115   GObject parent_instance;
 116
 117   /* width of the display area on-screen,
 118    * i.e. pixels we should wrap to fit inside. */
 119   gint screen_width;
 120
 121   /* width/height of the total logical area being layed out */
 122   gint width;
 123   gint height;
 124
 125   /* Pixel offsets from the left and from the top to be used when we
 126    * draw; these allow us to create left/top margins. We don't need
 127    * anything special for bottom/right margins, because those don't
 128    * affect drawing.
 129    */
 130   /* gint left_edge; */
 131   /* gint top_edge; */
 132
 133   GtkTextBuffer *buffer;
 134
 135   /* Default style used if no tags override it */
 136   GtkTextAttributes *default_style;
 137
 138   /* Pango contexts used for creating layouts */
 139   PangoContext *ltr_context;
 140   PangoContext *rtl_context;
 141
 142   /* A cache of one style; this is used to ensure
 143    * we don't constantly regenerate the style
 144    * over long runs with the same style. */
 145   GtkTextAttributes *one_style_cache;
 146
 147   /* A cache of one line display. Getting the same line
 148    * many times in a row is the most common case.
 149    */
 150   GtkTextLineDisplay *one_display_cache;
 151
 152   /* Whether we are allowed to wrap right now */
 153   gint wrap_loop_count;
 154
 155   /* Whether to show the insertion cursor */
 156   guint cursor_visible : 1;
 157
 158   /* For what GtkTextDirection to draw cursor GTK_TEXT_DIR_NONE -
 159    * means draw both cursors.
 160    */
 161   guint cursor_direction : 2;
 162
 163   /* The keyboard direction is used to default the alignment when
 164      there are no strong characters.
 165   */
 166   guint keyboard_direction : 2;
 167
 168   /* The preedit string and attributes, if any */
 169
 170   gchar *preedit_string;
 171   PangoAttrList *preedit_attrs;
 172   gint preedit_len;
 173   gint preedit_cursor;
 174
 175   guint overwrite_mode : 1;
 176 };
 177
 178 struct _GtkTextLayoutClass
 179 {
 180   GObjectClass parent_class;
 181
 182   /* Some portion of the layout was invalidated
 183    */
 184   void  (*invalidated)  (GtkTextLayout *layout);
 185
 186   /* A range of the layout changed appearance and possibly height
 187    */
 188   void  (*changed)              (GtkTextLayout     *layout,
 189                                  gint               y,
 190                                  gint               old_height,
 191                                  gint               new_height);
 192   GtkTextLineData* (*wrap)      (GtkTextLayout     *layout,
 193                                  GtkTextLine       *line,
 194                                  GtkTextLineData   *line_data); /* may be NULL */
 195   void  (*get_log_attrs)        (GtkTextLayout     *layout,
 196                                  GtkTextLine       *line,
 197                                  PangoLogAttr     **attrs,
 198                                  gint              *n_attrs);
 199   void  (*invalidate)           (GtkTextLayout     *layout,
 200                                  const GtkTextIter *start,
 201                                  const GtkTextIter *end);
 202   void  (*free_line_data)       (GtkTextLayout     *layout,
 203                                  GtkTextLine       *line,
 204                                  GtkTextLineData   *line_data);
 205
 206   void (*allocate_child)        (GtkTextLayout     *layout,
 207                                  GtkWidget         *child,
 208                                  gint               x,
 209                                  gint               y);
 210
 211   void (*invalidate_cursors)    (GtkTextLayout     *layout,
 212                                  const GtkTextIter *start,
 213                                  const GtkTextIter *end);
 214
 215   /* Padding for future expansion */
 216   void (*_gtk_reserved1) (void);
 217   void (*_gtk_reserved2) (void);
 218   void (*_gtk_reserved3) (void);
 219 };
 220
 221 struct _GtkTextAttrAppearance
 222 {
 223   PangoAttribute attr;
 224   GtkTextAppearance appearance;
 225 };
 226
 227 struct _GtkTextLineDisplay
 228 {
 229   PangoLayout *layout;
 230   GArray *cursors;      /* indexes of cursors in the PangoLayout */
 231
 232   GtkTextDirection direction;
 233
 234   gint width;                   /* Width of layout */
 235   gint total_width;             /* width - margins, if no width set on layout, if width set on layout, -1 */
 236   gint height;
 237   /* Amount layout is shifted from left edge - this is the left margin
 238    * plus any other factors, such as alignment or indentation.
 239    */
 240   gint x_offset;
 241   gint left_margin;
 242   gint right_margin;
 243   gint top_margin;
 244   gint bottom_margin;
 245   gint insert_index;            /* Byte index of insert cursor within para or -1 */
 246
 247   GtkTextLine *line;
 248
 249   GdkColor *pg_bg_color;
 250
 251   GdkRectangle block_cursor;
 252   guint cursors_invalid : 1;
 253   guint has_block_cursor : 1;
 254   guint cursor_at_line_end : 1;
 255   guint size_only : 1;
 256
 257   GdkRGBA *pg_bg_rgba;
 258 };
 259
 260 #ifdef GTK_COMPILATION
 261 extern G_GNUC_INTERNAL PangoAttrType gtk_text_attr_appearance_type;
 262 #endif
 263
 264 GType         gtk_text_layout_get_type    (void) G_GNUC_CONST;
 265
 266 GtkTextLayout*     gtk_text_layout_new                   (void);
 267 void               gtk_text_layout_set_buffer            (GtkTextLayout     *layout,
 268                                                           GtkTextBuffer     *buffer);
 269 GtkTextBuffer     *gtk_text_layout_get_buffer            (GtkTextLayout     *layout);
 270 void               gtk_text_layout_set_default_style     (GtkTextLayout     *layout,
 271                                                           GtkTextAttributes *values);
 272 void               gtk_text_layout_set_contexts          (GtkTextLayout     *layout,
 273                                                           PangoContext      *ltr_context,
 274                                                           PangoContext      *rtl_context);
 275 void               gtk_text_layout_set_cursor_direction  (GtkTextLayout     *layout,
 276                                                           GtkTextDirection   direction);
 277 void               gtk_text_layout_set_overwrite_mode    (GtkTextLayout     *layout,
 278                                                           gboolean           overwrite);
 279 void               gtk_text_layout_set_keyboard_direction (GtkTextLayout     *layout,
 280                                                            GtkTextDirection keyboard_dir);
 281 void               gtk_text_layout_default_style_changed (GtkTextLayout     *layout);
 282
 283 void gtk_text_layout_set_screen_width       (GtkTextLayout     *layout,
 284                                              gint               width);
 285 void gtk_text_layout_set_preedit_string     (GtkTextLayout     *layout,
 286                                              const gchar       *preedit_string,
 287                                              PangoAttrList     *preedit_attrs,
 288                                              gint               cursor_pos);
 289
 290 void     gtk_text_layout_set_cursor_visible (GtkTextLayout     *layout,
 291                                              gboolean           cursor_visible);
 292 gboolean gtk_text_layout_get_cursor_visible (GtkTextLayout     *layout);
 293
 294 /* Getting the size or the lines potentially results in a call to
 295  * recompute, which is pretty massively expensive. Thus it should
 296  * basically only be done in an idle handler.
 297  *
 298  * Long-term, we would really like to be able to do these without
 299  * a full recompute so they may get cheaper over time.
 300  */
 301 void    gtk_text_layout_get_size  (GtkTextLayout  *layout,
 302                                    gint           *width,
 303                                    gint           *height);
 304 GSList* gtk_text_layout_get_lines (GtkTextLayout  *layout,
 305                                    /* [top_y, bottom_y) */
 306                                    gint            top_y,
 307                                    gint            bottom_y,
 308                                    gint           *first_line_y);
 309
 310 void gtk_text_layout_wrap_loop_start (GtkTextLayout *layout);
 311 void gtk_text_layout_wrap_loop_end   (GtkTextLayout *layout);
 312
 313 GtkTextLineDisplay* gtk_text_layout_get_line_display  (GtkTextLayout      *layout,
 314                                                        GtkTextLine        *line,
 315                                                        gboolean            size_only);
 316 void                gtk_text_layout_free_line_display (GtkTextLayout      *layout,
 317                                                        GtkTextLineDisplay *display);
 318
 319 void gtk_text_layout_get_line_at_y     (GtkTextLayout     *layout,
 320                                         GtkTextIter       *target_iter,
 321                                         gint               y,
 322                                         gint              *line_top);
 323 void gtk_text_layout_get_iter_at_pixel (GtkTextLayout     *layout,
 324                                         GtkTextIter       *iter,
 325                                         gint               x,
 326                                         gint               y);
 327 void gtk_text_layout_get_iter_at_position (GtkTextLayout     *layout,
 328                                            GtkTextIter       *iter,
 329                                            gint              *trailing,
 330                                            gint               x,
 331                                            gint               y);
 332 void gtk_text_layout_invalidate        (GtkTextLayout     *layout,
 333                                         const GtkTextIter *start,
 334                                         const GtkTextIter *end);
 335 void gtk_text_layout_invalidate_cursors(GtkTextLayout     *layout,
 336                                         const GtkTextIter *start,
 337                                         const GtkTextIter *end);
 338 void gtk_text_layout_free_line_data    (GtkTextLayout     *layout,
 339                                         GtkTextLine       *line,
 340                                         GtkTextLineData   *line_data);
 341
 342 gboolean gtk_text_layout_is_valid        (GtkTextLayout *layout);
 343 void     gtk_text_layout_validate_yrange (GtkTextLayout *layout,
 344                                           GtkTextIter   *anchor_line,
 345                                           gint           y0_,
 346                                           gint           y1_);
 347 void     gtk_text_layout_validate        (GtkTextLayout *layout,
 348                                           gint           max_pixels);
 349
 350 /* This function should return the passed-in line data,
 351  * OR remove the existing line data from the line, and
 352  * return a NEW line data after adding it to the line.
 353  * That is, invariant after calling the callback is that
 354  * there should be exactly one line data for this view
 355  * stored on the btree line.
 356  */
 357 GtkTextLineData* gtk_text_layout_wrap  (GtkTextLayout   *layout,
 358                                         GtkTextLine     *line,
 359                                         GtkTextLineData *line_data); /* may be NULL */
 360 void     gtk_text_layout_changed              (GtkTextLayout     *layout,
 361                                                gint               y,
 362                                                gint               old_height,
 363                                                gint               new_height);
 364 void     gtk_text_layout_cursors_changed      (GtkTextLayout     *layout,
 365                                                gint               y,
 366                                                gint               old_height,
 367                                                gint               new_height);
 368 void     gtk_text_layout_get_iter_location    (GtkTextLayout     *layout,
 369                                                const GtkTextIter *iter,
 370                                                GdkRectangle      *rect);
 371 void     gtk_text_layout_get_line_yrange      (GtkTextLayout     *layout,
 372                                                const GtkTextIter *iter,
 373                                                gint              *y,
 374                                                gint              *height);
 375 void     _gtk_text_layout_get_line_xrange     (GtkTextLayout     *layout,
 376                                                const GtkTextIter *iter,
 377                                                gint              *x,
 378                                                gint              *width);
 379 void     gtk_text_layout_get_cursor_locations (GtkTextLayout     *layout,
 380                                                GtkTextIter       *iter,
 381                                                GdkRectangle      *strong_pos,
 382                                                GdkRectangle      *weak_pos);
 383 gboolean _gtk_text_layout_get_block_cursor    (GtkTextLayout     *layout,
 384                                                GdkRectangle      *pos);
 385 gboolean gtk_text_layout_clamp_iter_to_vrange (GtkTextLayout     *layout,
 386                                                GtkTextIter       *iter,
 387                                                gint               top,
 388                                                gint               bottom);
 389
 390 gboolean gtk_text_layout_move_iter_to_line_end      (GtkTextLayout *layout,
 391                                                      GtkTextIter   *iter,
 392                                                      gint           direction);
 393 gboolean gtk_text_layout_move_iter_to_previous_line (GtkTextLayout *layout,
 394                                                      GtkTextIter   *iter);
 395 gboolean gtk_text_layout_move_iter_to_next_line     (GtkTextLayout *layout,
 396                                                      GtkTextIter   *iter);
 397 void     gtk_text_layout_move_iter_to_x             (GtkTextLayout *layout,
 398                                                      GtkTextIter   *iter,
 399                                                      gint           x);
 400 gboolean gtk_text_layout_move_iter_visually         (GtkTextLayout *layout,
 401                                                      GtkTextIter   *iter,
 402                                                      gint           count);
 403
 404 gboolean gtk_text_layout_iter_starts_line           (GtkTextLayout       *layout,
 405                                                      const GtkTextIter   *iter);
 406
 407 void     gtk_text_layout_get_iter_at_line           (GtkTextLayout *layout,
 408                                                      GtkTextIter    *iter,
 409                                                      GtkTextLine    *line,
 410                                                      gint            byte_offset);
 411
 412 /* Don't use these. Use gtk_text_view_add_child_at_anchor().
 413  * These functions are defined in gtktextchild.c, but here
 414  * since they are semi-public and require GtkTextLayout to
 415  * be declared.
 416  */
 417 void gtk_text_child_anchor_register_child   (GtkTextChildAnchor *anchor,
 418                                              GtkWidget          *child,
 419                                              GtkTextLayout      *layout);
 420 void gtk_text_child_anchor_unregister_child (GtkTextChildAnchor *anchor,
 421                                              GtkWidget          *child);
 422
 423 void gtk_text_child_anchor_queue_resize     (GtkTextChildAnchor *anchor,
 424                                              GtkTextLayout      *layout);
 425
 426 void gtk_text_anchored_child_set_layout     (GtkWidget          *child,
 427                                              GtkTextLayout      *layout);
 428
 429 void gtk_text_layout_spew (GtkTextLayout *layout);
 430
 431 G_END_DECLS
 432
 433 #endif  /* __GTK_TEXT_LAYOUT_H__ */