libs/gnomecanvas/libgnomecanvas/gnome-canvas.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: 8; c-basic-offset: 8 -*- */
   2 /*
   3  * Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation
   4  * All rights reserved.
   5  *
   6  * This file is part of the Gnome Library.
   7  *
   8  * The Gnome Library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public License as
  10  * published by the Free Software Foundation; either version 2 of the
  11  * License, or (at your option) any later version.
  12  *
  13  * The Gnome Library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with the Gnome Library; see the file COPYING.LIB.  If not,
  20  * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23 /*
  24   @NOTATION@
  25  */
  26 /* GnomeCanvas widget - Tk-like canvas widget for Gnome
  27  *
  28  * GnomeCanvas is basically a port of the Tk toolkit's most excellent canvas
  29  * widget.  Tk is copyrighted by the Regents of the University of California,
  30  * Sun Microsystems, and other parties.
  31  *
  32  *
  33  * Authors: Federico Mena <federico@nuclecu.unam.mx>
  34  *          Raph Levien <raph@gimp.org>
  35  */
  36
  37 #ifndef GNOME_CANVAS_H
  38 #define GNOME_CANVAS_H
  39
  40 #include <gtk/gtk.h>
  41 #include <stdarg.h>
  42 #include <libart_lgpl/art_misc.h>
  43 #include <libart_lgpl/art_rect.h>
  44 #include <libart_lgpl/art_svp.h>
  45 #include <libart_lgpl/art_uta.h>
  46 #include <libart_lgpl/art_affine.h>
  47
  48 G_BEGIN_DECLS
  49
  50
  51 /* "Small" value used by canvas stuff */
  52 #define GNOME_CANVAS_EPSILON 1e-10
  53
  54
  55 /* Macros for building colors that fit in a 32-bit integer.  The values are in
  56  * [0, 255].
  57  */
  58
  59 #define GNOME_CANVAS_COLOR(r, g, b) ((((unsigned int) (r) & 0xff) << 24)        \
  60                                      | (((unsigned int) (g) & 0xff) << 16)      \
  61                                      | (((unsigned int) (b) & 0xff) << 8)       \
  62                                      | 0xff)
  63
  64 #define GNOME_CANVAS_COLOR_A(r, g, b, a) ((((unsigned int) (r) & 0xff) << 24)   \
  65                                           | (((unsigned int) (g) & 0xff) << 16) \
  66                                           | (((unsigned int) (b) & 0xff) << 8)  \
  67                                           | ((unsigned int) (a) & 0xff))
  68
  69
  70 typedef struct _GnomeCanvas           GnomeCanvas;
  71 typedef struct _GnomeCanvasClass      GnomeCanvasClass;
  72 typedef struct _GnomeCanvasItem       GnomeCanvasItem;
  73 typedef struct _GnomeCanvasItemClass  GnomeCanvasItemClass;
  74 typedef struct _GnomeCanvasGroup      GnomeCanvasGroup;
  75 typedef struct _GnomeCanvasGroupClass GnomeCanvasGroupClass;
  76
  77
  78 /* GnomeCanvasItem - base item class for canvas items
  79  *
  80  * All canvas items are derived from GnomeCanvasItem.  The only information a
  81  * GnomeCanvasItem contains is its parent canvas, its parent canvas item group,
  82  * its bounding box in world coordinates, and its current affine transformation.
  83  *
  84  * Items inside a canvas are organized in a tree of GnomeCanvasItemGroup nodes
  85  * and GnomeCanvasItem leaves.  Each canvas has a single root group, which can
  86  * be obtained with the gnome_canvas_get_root() function.
  87  *
  88  * The abstract GnomeCanvasItem class does not have any configurable or
  89  * queryable attributes.
  90  */
  91
  92 /* Object flags for items */
  93 enum {
  94         GNOME_CANVAS_ITEM_REALIZED      = 1 << 4,
  95         GNOME_CANVAS_ITEM_MAPPED        = 1 << 5,
  96         GNOME_CANVAS_ITEM_ALWAYS_REDRAW = 1 << 6,
  97         GNOME_CANVAS_ITEM_VISIBLE       = 1 << 7,
  98         GNOME_CANVAS_ITEM_NEED_UPDATE   = 1 << 8,
  99         GNOME_CANVAS_ITEM_NEED_AFFINE   = 1 << 9,
 100         GNOME_CANVAS_ITEM_NEED_CLIP     = 1 << 10,
 101         GNOME_CANVAS_ITEM_NEED_VIS      = 1 << 11,
 102         GNOME_CANVAS_ITEM_AFFINE_FULL   = 1 << 12
 103 };
 104
 105 /* Update flags for items */
 106 enum {
 107         GNOME_CANVAS_UPDATE_REQUESTED  = 1 << 0,
 108         GNOME_CANVAS_UPDATE_AFFINE     = 1 << 1,
 109         GNOME_CANVAS_UPDATE_CLIP       = 1 << 2,
 110         GNOME_CANVAS_UPDATE_VISIBILITY = 1 << 3,
 111         GNOME_CANVAS_UPDATE_IS_VISIBLE = 1 << 4         /* Deprecated.  FIXME: remove this */
 112 };
 113
 114 /* Data for rendering in antialiased mode */
 115 typedef struct {
 116         /* 24-bit RGB buffer for rendering */
 117         guchar *buf;
 118
 119         /* Rectangle describing the rendering area */
 120         ArtIRect rect;
 121
 122         /* Rowstride for the buffer */
 123         int buf_rowstride;
 124
 125         /* Background color, given as 0xrrggbb */
 126         guint32 bg_color;
 127
 128         /* Invariant: at least one of the following flags is true. */
 129
 130         /* Set when the render rectangle area is the solid color bg_color */
 131         unsigned int is_bg : 1;
 132
 133         /* Set when the render rectangle area is represented by the buf */
 134         unsigned int is_buf : 1;
 135 } GnomeCanvasBuf;
 136
 137
 138 #define GNOME_TYPE_CANVAS_ITEM            (gnome_canvas_item_get_type ())
 139 #define GNOME_CANVAS_ITEM(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GNOME_TYPE_CANVAS_ITEM, GnomeCanvasItem))
 140 #define GNOME_CANVAS_ITEM_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GNOME_TYPE_CANVAS_ITEM, GnomeCanvasItemClass))
 141 #define GNOME_IS_CANVAS_ITEM(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GNOME_TYPE_CANVAS_ITEM))
 142 #define GNOME_IS_CANVAS_ITEM_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GNOME_TYPE_CANVAS_ITEM))
 143 #define GNOME_CANVAS_ITEM_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GNOME_TYPE_CANVAS_ITEM, GnomeCanvasItemClass))
 144
 145
 146 struct _GnomeCanvasItem {
 147         GtkObject object;
 148
 149         /* Parent canvas for this item */
 150         GnomeCanvas *canvas;
 151
 152         /* Parent canvas group for this item (a GnomeCanvasGroup) */
 153         GnomeCanvasItem *parent;
 154
 155         /* If NULL, assumed to be the identity tranform.  If flags does not have
 156          * AFFINE_FULL, then a two-element array containing a translation.  If
 157          * flags contains AFFINE_FULL, a six-element array containing an affine
 158          * transformation.
 159          */
 160         double *xform;
 161
 162         /* Bounding box for this item (in canvas coordinates) */
 163         double x1, y1, x2, y2;
 164 };
 165
 166 struct _GnomeCanvasItemClass {
 167         GtkObjectClass parent_class;
 168
 169         /* Tell the item to update itself.  The flags are from the update flags
 170          * defined above.  The item should update its internal state from its
 171          * queued state, and recompute and request its repaint area.  The
 172          * affine, if used, is a pointer to a 6-element array of doubles.  The
 173          * update method also recomputes the bounding box of the item.
 174          */
 175         void (* update) (GnomeCanvasItem *item, double *affine, ArtSVP *clip_path, int flags);
 176
 177         /* Realize an item -- create GCs, etc. */
 178         void (* realize) (GnomeCanvasItem *item);
 179
 180         /* Unrealize an item */
 181         void (* unrealize) (GnomeCanvasItem *item);
 182
 183         /* Map an item - normally only need by items with their own GdkWindows */
 184         void (* map) (GnomeCanvasItem *item);
 185
 186         /* Unmap an item */
 187         void (* unmap) (GnomeCanvasItem *item);
 188
 189         /* Return the microtile coverage of the item */
 190         ArtUta *(* coverage) (GnomeCanvasItem *item);
 191
 192         /* Draw an item of this type.  (x, y) are the upper-left canvas pixel
 193          * coordinates of the drawable, a temporary pixmap, where things get
 194          * drawn.  (width, height) are the dimensions of the drawable.
 195          */
 196         void (* draw) (GnomeCanvasItem *item, GdkDrawable *drawable,
 197                        int x, int y, int width, int height);
 198
 199         /* Render the item over the buffer given.  The buf data structure
 200          * contains both a pointer to a packed 24-bit RGB array, and the
 201          * coordinates.  This method is only used for antialiased canvases.
 202          *
 203          * TODO: figure out where clip paths fit into the rendering framework.
 204          */
 205         void (* render) (GnomeCanvasItem *item, GnomeCanvasBuf *buf);
 206
 207         /* Calculate the distance from an item to the specified point.  It also
 208          * returns a canvas item which is the item itself in the case of the
 209          * object being an actual leaf item, or a child in case of the object
 210          * being a canvas group.  (cx, cy) are the canvas pixel coordinates that
 211          * correspond to the item-relative coordinates (x, y).
 212          */
 213         double (* point) (GnomeCanvasItem *item, double x, double y, int cx, int cy,
 214                           GnomeCanvasItem **actual_item);
 215
 216         /* Fetch the item's bounding box (need not be exactly tight).  This
 217          * should be in item-relative coordinates.
 218          */
 219         void (* bounds) (GnomeCanvasItem *item, double *x1, double *y1, double *x2, double *y2);
 220
 221         /* Signal: an event occurred for an item of this type.  The (x, y)
 222          * coordinates are in the canvas world coordinate system.
 223          */
 224         gboolean (* event)                (GnomeCanvasItem *item, GdkEvent *event);
 225
 226         /* Reserved for future expansion */
 227         gpointer spare_vmethods [4];
 228 };
 229
 230
 231 GType gnome_canvas_item_get_type (void) G_GNUC_CONST;
 232
 233 /* Create a canvas item using the standard Gtk argument mechanism.  The item is
 234  * automatically inserted at the top of the specified canvas group.  The last
 235  * argument must be a NULL pointer.
 236  */
 237 GnomeCanvasItem *gnome_canvas_item_new (GnomeCanvasGroup *parent, GType type,
 238                                         const gchar *first_arg_name, ...);
 239
 240 /* Constructors for use in derived classes and language wrappers */
 241 void gnome_canvas_item_construct (GnomeCanvasItem *item, GnomeCanvasGroup *parent,
 242                                   const gchar *first_arg_name, va_list args);
 243
 244 /* Configure an item using the standard Gtk argument mechanism.  The last
 245  * argument must be a NULL pointer.
 246  */
 247 void gnome_canvas_item_set (GnomeCanvasItem *item, const gchar *first_arg_name, ...);
 248
 249 /* Used only for language wrappers and the like */
 250 void gnome_canvas_item_set_valist (GnomeCanvasItem *item,
 251                                    const gchar *first_arg_name, va_list args);
 252
 253 /* Move an item by the specified amount */
 254 void gnome_canvas_item_move (GnomeCanvasItem *item, double dx, double dy);
 255
 256 /* Apply a relative affine transformation to the item. */
 257 void gnome_canvas_item_affine_relative (GnomeCanvasItem *item, const double affine[6]);
 258
 259 /* Apply an absolute affine transformation to the item. */
 260 void gnome_canvas_item_affine_absolute (GnomeCanvasItem *item, const double affine[6]);
 261
 262 /* Raise an item in the z-order of its parent group by the specified number of
 263  * positions.
 264  */
 265 void gnome_canvas_item_raise (GnomeCanvasItem *item, int positions);
 266
 267 /* Lower an item in the z-order of its parent group by the specified number of
 268  * positions.
 269  */
 270 void gnome_canvas_item_lower (GnomeCanvasItem *item, int positions);
 271
 272 /* Raise an item to the top of its parent group's z-order. */
 273 void gnome_canvas_item_raise_to_top (GnomeCanvasItem *item);
 274
 275 /* Lower an item to the bottom of its parent group's z-order */
 276 void gnome_canvas_item_lower_to_bottom (GnomeCanvasItem *item);
 277
 278 /* Show an item (make it visible).  If the item is already shown, it has no
 279  * effect.
 280  */
 281 void gnome_canvas_item_show (GnomeCanvasItem *item);
 282
 283 /* Hide an item (make it invisible).  If the item is already invisible, it has
 284  * no effect.
 285  */
 286 void gnome_canvas_item_hide (GnomeCanvasItem *item);
 287
 288 /* Grab the mouse for the specified item.  Only the events in event_mask will be
 289  * reported.  If cursor is non-NULL, it will be used during the duration of the
 290  * grab.  Time is a proper X event time parameter.  Returns the same values as
 291  * XGrabPointer().
 292  */
 293 int gnome_canvas_item_grab (GnomeCanvasItem *item, unsigned int event_mask,
 294                             GdkCursor *cursor, guint32 etime);
 295
 296 /* Ungrabs the mouse -- the specified item must be the same that was passed to
 297  * gnome_canvas_item_grab().  Time is a proper X event time parameter.
 298  */
 299 void gnome_canvas_item_ungrab (GnomeCanvasItem *item, guint32 etime);
 300
 301 /* These functions convert from a coordinate system to another.  "w" is world
 302  * coordinates and "i" is item coordinates.
 303  */
 304 void gnome_canvas_item_w2i (GnomeCanvasItem *item, double *x, double *y);
 305 void gnome_canvas_item_i2w (GnomeCanvasItem *item, double *x, double *y);
 306
 307 /* Gets the affine transform that converts from item-relative coordinates to
 308  * world coordinates.
 309  */
 310 void gnome_canvas_item_i2w_affine (GnomeCanvasItem *item, double affine[6]);
 311
 312 /* Gets the affine transform that converts from item-relative coordinates to
 313  * canvas pixel coordinates.
 314  */
 315 void gnome_canvas_item_i2c_affine (GnomeCanvasItem *item, double affine[6]);
 316
 317 /* Remove the item from its parent group and make the new group its parent.  The
 318  * item will be put on top of all the items in the new group.  The item's
 319  * coordinates relative to its new parent to *not* change -- this means that the
 320  * item could potentially move on the screen.
 321  *
 322  * The item and the group must be in the same canvas.  An item cannot be
 323  * reparented to a group that is the item itself or that is an inferior of the
 324  * item.
 325  */
 326 void gnome_canvas_item_reparent (GnomeCanvasItem *item, GnomeCanvasGroup *new_group);
 327
 328 /* Used to send all of the keystroke events to a specific item as well as
 329  * GDK_FOCUS_CHANGE events.
 330  */
 331 void gnome_canvas_item_grab_focus (GnomeCanvasItem *item);
 332
 333 /* Fetch the bounding box of the item.  The bounding box may not be exactly
 334  * tight, but the canvas items will do the best they can.  The returned bounding
 335  * box is in the coordinate system of the item's parent.
 336  */
 337 void gnome_canvas_item_get_bounds (GnomeCanvasItem *item,
 338                                    double *x1, double *y1, double *x2, double *y2);
 339
 340 /* Request that the update method eventually get called.  This should be used
 341  * only by item implementations.
 342  */
 343 void gnome_canvas_item_request_update (GnomeCanvasItem *item);
 344
 345
 346 /* GnomeCanvasGroup - a group of canvas items
 347  *
 348  * A group is a node in the hierarchical tree of groups/items inside a canvas.
 349  * Groups serve to give a logical structure to the items.
 350  *
 351  * Consider a circuit editor application that uses the canvas for its schematic
 352  * display.  Hierarchically, there would be canvas groups that contain all the
 353  * components needed for an "adder", for example -- this includes some logic
 354  * gates as well as wires.  You can move stuff around in a convenient way by
 355  * doing a gnome_canvas_item_move() of the hierarchical groups -- to move an
 356  * adder, simply move the group that represents the adder.
 357  *
 358  * The following arguments are available:
 359  *
 360  * name         type            read/write      description
 361  * --------------------------------------------------------------------------------
 362  * x            double          RW              X coordinate of group's origin
 363  * y            double          RW              Y coordinate of group's origin
 364  */
 365
 366
 367 #define GNOME_TYPE_CANVAS_GROUP            (gnome_canvas_group_get_type ())
 368 #define GNOME_CANVAS_GROUP(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GNOME_TYPE_CANVAS_GROUP, GnomeCanvasGroup))
 369 #define GNOME_CANVAS_GROUP_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GNOME_TYPE_CANVAS_GROUP, GnomeCanvasGroupClass))
 370 #define GNOME_IS_CANVAS_GROUP(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GNOME_TYPE_CANVAS_GROUP))
 371 #define GNOME_IS_CANVAS_GROUP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GNOME_TYPE_CANVAS_GROUP))
 372 #define GNOME_CANVAS_GROUP_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GNOME_TYPE_CANVAS_GROUP, GnomeCanvasGroupClass))
 373
 374
 375 struct _GnomeCanvasGroup {
 376         GnomeCanvasItem item;
 377
 378         /* Children of the group */
 379         GList *item_list;
 380         GList *item_list_end;
 381 };
 382
 383 struct _GnomeCanvasGroupClass {
 384         GnomeCanvasItemClass parent_class;
 385 };
 386
 387
 388 GType gnome_canvas_group_get_type (void) G_GNUC_CONST;
 389
 390
 391 /*** GnomeCanvas ***/
 392
 393
 394 #define GNOME_TYPE_CANVAS            (gnome_canvas_get_type ())
 395 #define GNOME_CANVAS(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GNOME_TYPE_CANVAS, GnomeCanvas))
 396 #define GNOME_CANVAS_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GNOME_TYPE_CANVAS, GnomeCanvasClass))
 397 #define GNOME_IS_CANVAS(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GNOME_TYPE_CANVAS))
 398 #define GNOME_IS_CANVAS_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GNOME_TYPE_CANVAS))
 399 #define GNOME_CANVAS_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GNOME_TYPE_CANVAS, GnomeCanvasClass))
 400
 401
 402 struct _GnomeCanvas {
 403         GtkLayout layout;
 404
 405         /* Root canvas group */
 406         GnomeCanvasItem *root;
 407
 408         /* Area that needs redrawing, stored as a microtile array */
 409         ArtUta *redraw_area;
 410
 411         /* The item containing the mouse pointer, or NULL if none */
 412         GnomeCanvasItem *current_item;
 413
 414         /* Item that is about to become current (used to track deletions and such) */
 415         GnomeCanvasItem *new_current_item;
 416
 417         /* Item that holds a pointer grab, or NULL if none */
 418         GnomeCanvasItem *grabbed_item;
 419
 420         /* If non-NULL, the currently focused item */
 421         GnomeCanvasItem *focused_item;
 422
 423         /* GC for temporary draw pixmap */
 424         GdkGC *pixmap_gc;
 425
 426         /* Event on which selection of current item is based */
 427         GdkEvent pick_event;
 428
 429         /* Scrolling region */
 430         double scroll_x1, scroll_y1;
 431         double scroll_x2, scroll_y2;
 432
 433         /* Scaling factor to be used for display */
 434         double pixels_per_unit;
 435
 436         /* Idle handler ID */
 437         guint idle_id;
 438
 439         /* Signal handler ID for destruction of the root item */
 440         guint root_destroy_id;
 441
 442         /* Area that is being redrawn.  Contains (x1, y1) but not (x2, y2).
 443          * Specified in canvas pixel coordinates.
 444          */
 445         int redraw_x1, redraw_y1;
 446         int redraw_x2, redraw_y2;
 447
 448         /* Offsets of the temprary drawing pixmap */
 449         int draw_xofs, draw_yofs;
 450
 451         /* Internal pixel offsets when zoomed out */
 452         int zoom_xofs, zoom_yofs;
 453
 454         /* Last known modifier state, for deferred repick when a button is down */
 455         int state;
 456
 457         /* Event mask specified when grabbing an item */
 458         guint grabbed_event_mask;
 459
 460         /* Tolerance distance for picking items */
 461         int close_enough;
 462
 463         /* Whether the canvas should center the scroll region in the middle of
 464          * the window if the scroll region is smaller than the window.
 465          */
 466         unsigned int center_scroll_region : 1;
 467
 468         /* Whether items need update at next idle loop iteration */
 469         unsigned int need_update : 1;
 470
 471         /* Whether the canvas needs redrawing at the next idle loop iteration */
 472         unsigned int need_redraw : 1;
 473
 474         /* Whether current item will be repicked at next idle loop iteration */
 475         unsigned int need_repick : 1;
 476
 477         /* For use by internal pick_current_item() function */
 478         unsigned int left_grabbed_item : 1;
 479
 480         /* For use by internal pick_current_item() function */
 481         unsigned int in_repick : 1;
 482
 483         /* Whether the canvas is in antialiased mode or not */
 484         unsigned int aa : 1;
 485
 486         /* Which dither mode to use for antialiased mode drawing */
 487         GdkRgbDither dither;
 488 };
 489
 490 struct _GnomeCanvasClass {
 491         GtkLayoutClass parent_class;
 492
 493         /* Draw the background for the area given. This method is only used
 494          * for non-antialiased canvases.
 495          */
 496         void (* draw_background) (GnomeCanvas *canvas, GdkDrawable *drawable,
 497                                   int x, int y, int width, int height);
 498
 499         /* Render the background for the buffer given. The buf data structure
 500          * contains both a pointer to a packed 24-bit RGB array, and the
 501          * coordinates. This method is only used for antialiased canvases.
 502          */
 503         void (* render_background) (GnomeCanvas *canvas, GnomeCanvasBuf *buf);
 504
 505         /* Private Virtual methods for groping the canvas inside bonobo */
 506         void (* request_update) (GnomeCanvas *canvas);
 507
 508         /* Reserved for future expansion */
 509         gpointer spare_vmethods [4];
 510 };
 511
 512
 513 GType gnome_canvas_get_type (void) G_GNUC_CONST;
 514
 515 /* Creates a new canvas.  You should check that the canvas is created with the
 516  * proper visual and colormap.  Any visual will do unless you intend to insert
 517  * gdk_imlib images into it, in which case you should use the gdk_imlib visual.
 518  *
 519  * You should call gnome_canvas_set_scroll_region() soon after calling this
 520  * function to set the desired scrolling limits for the canvas.
 521  */
 522 GtkWidget *gnome_canvas_new (void);
 523
 524 /* Creates a new antialiased empty canvas.  You should push the GdkRgb colormap
 525  * and visual for this.
 526  */
 527 #ifndef GNOME_EXCLUDE_EXPERIMENTAL
 528 GtkWidget *gnome_canvas_new_aa (void);
 529 #endif
 530
 531 /* Returns the root canvas item group of the canvas */
 532 GnomeCanvasGroup *gnome_canvas_root (GnomeCanvas *canvas);
 533
 534 /* Sets the limits of the scrolling region, in world coordinates */
 535 void gnome_canvas_set_scroll_region (GnomeCanvas *canvas,
 536                                      double x1, double y1, double x2, double y2);
 537
 538 /* Gets the limits of the scrolling region, in world coordinates */
 539 void gnome_canvas_get_scroll_region (GnomeCanvas *canvas,
 540                                      double *x1, double *y1, double *x2, double *y2);
 541
 542 /* Whether the canvas centers the scroll region if it is smaller than the window */
 543 void gnome_canvas_set_center_scroll_region (GnomeCanvas *canvas, gboolean center_scroll_region);
 544
 545 /* Returns whether the canvas is set to center the scroll region if it is smaller than the window */
 546 gboolean gnome_canvas_get_center_scroll_region (GnomeCanvas *canvas);
 547
 548 /* Sets the number of pixels that correspond to one unit in world coordinates */
 549 void gnome_canvas_set_pixels_per_unit (GnomeCanvas *canvas, double n);
 550
 551 /* Scrolls the canvas to the specified offsets, given in canvas pixel coordinates */
 552 void gnome_canvas_scroll_to (GnomeCanvas *canvas, int cx, int cy);
 553
 554 /* Returns the scroll offsets of the canvas in canvas pixel coordinates.  You
 555  * can specify NULL for any of the values, in which case that value will not be
 556  * queried.
 557  */
 558 void gnome_canvas_get_scroll_offsets (GnomeCanvas *canvas, int *cx, int *cy);
 559
 560 /* Requests that the canvas be repainted immediately instead of in the idle
 561  * loop.
 562  */
 563 void gnome_canvas_update_now (GnomeCanvas *canvas);
 564
 565 /* Returns the item that is at the specified position in world coordinates, or
 566  * NULL if no item is there.
 567  */
 568 GnomeCanvasItem *gnome_canvas_get_item_at (GnomeCanvas *canvas, double x, double y);
 569
 570 /* For use only by item type implementations. Request that the canvas eventually
 571  * redraw the specified region. The region is specified as a microtile
 572  * array. This function takes over responsibility for freeing the uta argument.
 573  */
 574 void gnome_canvas_request_redraw_uta (GnomeCanvas *canvas, ArtUta *uta);
 575
 576 /* For use only by item type implementations.  Request that the canvas
 577  * eventually redraw the specified region, specified in canvas pixel
 578  * coordinates.  The region contains (x1, y1) but not (x2, y2).
 579  */
 580 void gnome_canvas_request_redraw (GnomeCanvas *canvas, int x1, int y1, int x2, int y2);
 581
 582 /* Gets the affine transform that converts world coordinates into canvas pixel
 583  * coordinates.
 584  */
 585 void gnome_canvas_w2c_affine (GnomeCanvas *canvas, double affine[6]);
 586
 587 /* These functions convert from a coordinate system to another.  "w" is world
 588  * coordinates, "c" is canvas pixel coordinates (pixel coordinates that are
 589  * (0,0) for the upper-left scrolling limit and something else for the
 590  * lower-left scrolling limit).
 591  */
 592 void gnome_canvas_w2c (GnomeCanvas *canvas, double wx, double wy, int *cx, int *cy);
 593 void gnome_canvas_w2c_d (GnomeCanvas *canvas, double wx, double wy, double *cx, double *cy);
 594 void gnome_canvas_c2w (GnomeCanvas *canvas, int cx, int cy, double *wx, double *wy);
 595
 596 /* This function takes in coordinates relative to the GTK_LAYOUT
 597  * (canvas)->bin_window and converts them to world coordinates.
 598  */
 599 void gnome_canvas_window_to_world (GnomeCanvas *canvas,
 600                                    double winx, double winy, double *worldx, double *worldy);
 601
 602 /* This is the inverse of gnome_canvas_window_to_world() */
 603 void gnome_canvas_world_to_window (GnomeCanvas *canvas,
 604                                    double worldx, double worldy, double *winx, double *winy);
 605
 606 /* Takes a string specification for a color and allocates it into the specified
 607  * GdkColor.  If the string is null, then it returns FALSE. Otherwise, it
 608  * returns TRUE.
 609  */
 610 int gnome_canvas_get_color (GnomeCanvas *canvas, const char *spec, GdkColor *color);
 611
 612 /* Allocates a color from the RGB value passed into this function. */
 613 gulong gnome_canvas_get_color_pixel (GnomeCanvas *canvas,
 614                                      guint        rgba);
 615
 616
 617 /* Sets the stipple origin of the specified gc so that it will be aligned with
 618  * all the stipples used in the specified canvas.  This is intended for use only
 619  * by canvas item implementations.
 620  */
 621 void gnome_canvas_set_stipple_origin (GnomeCanvas *canvas, GdkGC *gc);
 622
 623 /* Controls the dithering used when the canvas renders.
 624  * Only applicable to antialiased canvases - ignored by non-antialiased canvases.
 625  */
 626 void gnome_canvas_set_dither (GnomeCanvas *canvas, GdkRgbDither dither);
 627
 628 /* Returns the dither mode of an antialiased canvas.
 629  * Only applicable to antialiased canvases - ignored by non-antialiased canvases.
 630  */
 631 GdkRgbDither gnome_canvas_get_dither (GnomeCanvas *canvas);
 632
 633 G_END_DECLS
 634
 635 #endif