libfoocanvas/foo-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 /* FooCanvas widget - Tk-like canvas widget for Gnome
  27  *
  28  * FooCanvas 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 FOO_CANVAS_H
  38 #define FOO_CANVAS_H
  39
  40 #include <gtk/gtklayout.h>
  41 #include <gdk/gdkevents.h>
  42 #include <stdarg.h>
  43
  44 G_BEGIN_DECLS
  45
  46
  47 /* "Small" value used by canvas stuff */
  48 #define FOO_CANVAS_EPSILON 1e-10
  49
  50
  51 /* Macros for building colors that fit in a 32-bit integer.  The values are in
  52  * [0, 255].
  53  */
  54
  55 #define FOO_CANVAS_COLOR(r, g, b) ((((int) (r) & 0xff) << 24)   \
  56                                      | (((int) (g) & 0xff) << 16)       \
  57                                      | (((int) (b) & 0xff) << 8)        \
  58                                      | 0xff)
  59
  60 #define FOO_CANVAS_COLOR_A(r, g, b, a) ((((int) (r) & 0xff) << 24)      \
  61                                           | (((int) (g) & 0xff) << 16)  \
  62                                           | (((int) (b) & 0xff) << 8)   \
  63                                           | ((int) (a) & 0xff))
  64
  65
  66 typedef struct _FooCanvas           FooCanvas;
  67 typedef struct _FooCanvasClass      FooCanvasClass;
  68 typedef struct _FooCanvasItem       FooCanvasItem;
  69 typedef struct _FooCanvasItemClass  FooCanvasItemClass;
  70 typedef struct _FooCanvasGroup      FooCanvasGroup;
  71 typedef struct _FooCanvasGroupClass FooCanvasGroupClass;
  72
  73
  74 /* FooCanvasItem - base item class for canvas items
  75  *
  76  * All canvas items are derived from FooCanvasItem.  The only information a
  77  * FooCanvasItem contains is its parent canvas, its parent canvas item group,
  78  * and its bounding box in world coordinates.
  79  *
  80  * Items inside a canvas are organized in a tree of FooCanvasItemGroup nodes
  81  * and FooCanvasItem leaves.  Each canvas has a single root group, which can
  82  * be obtained with the foo_canvas_get_root() function.
  83  *
  84  * The abstract FooCanvasItem class does not have any configurable or
  85  * queryable attributes.
  86  */
  87
  88 /* Object flags for items */
  89 enum {
  90         FOO_CANVAS_ITEM_REALIZED         = 1 << 4,
  91         FOO_CANVAS_ITEM_MAPPED           = 1 << 5,
  92         FOO_CANVAS_ITEM_ALWAYS_REDRAW    = 1 << 6,
  93         FOO_CANVAS_ITEM_VISIBLE          = 1 << 7,
  94         FOO_CANVAS_ITEM_NEED_UPDATE      = 1 << 8,
  95         FOO_CANVAS_ITEM_NEED_DEEP_UPDATE = 1 << 9
  96 };
  97
  98 /* Update flags for items */
  99 enum {
 100         FOO_CANVAS_UPDATE_REQUESTED  = 1 << 0,
 101         FOO_CANVAS_UPDATE_DEEP       = 1 << 1
 102 };
 103
 104 #define FOO_TYPE_CANVAS_ITEM            (foo_canvas_item_get_type ())
 105 #define FOO_CANVAS_ITEM(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), FOO_TYPE_CANVAS_ITEM, FooCanvasItem))
 106 #define FOO_CANVAS_ITEM_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), FOO_TYPE_CANVAS_ITEM, FooCanvasItemClass))
 107 #define FOO_IS_CANVAS_ITEM(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), FOO_TYPE_CANVAS_ITEM))
 108 #define FOO_IS_CANVAS_ITEM_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), FOO_TYPE_CANVAS_ITEM))
 109 #define FOO_CANVAS_ITEM_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), FOO_TYPE_CANVAS_ITEM, FooCanvasItemClass))
 110
 111
 112 struct _FooCanvasItem {
 113         GtkObject object;
 114
 115         /* Parent canvas for this item */
 116         FooCanvas *canvas;
 117
 118         /* Parent canvas group for this item (a FooCanvasGroup) */
 119         FooCanvasItem *parent;
 120
 121         /* Bounding box for this item (in canvas coordinates) */
 122         double x1, y1, x2, y2;
 123 };
 124
 125 struct _FooCanvasItemClass {
 126         GtkObjectClass parent_class;
 127
 128         /* Tell the item to update itself.  The flags are from the update flags
 129          * defined above.  The item should update its internal state from its
 130          * queued state, and recompute and request its repaint area. The
 131          * update method also recomputes the bounding box of the item.
 132          */
 133         void (* update) (FooCanvasItem *item, double i2w_dx, double i2w_dy, int flags);
 134
 135         /* Realize an item -- create GCs, etc. */
 136         void (* realize) (FooCanvasItem *item);
 137
 138         /* Unrealize an item */
 139         void (* unrealize) (FooCanvasItem *item);
 140
 141         /* Map an item - normally only need by items with their own GdkWindows */
 142         void (* map) (FooCanvasItem *item);
 143
 144         /* Unmap an item */
 145         void (* unmap) (FooCanvasItem *item);
 146
 147         /* Draw an item of this type.  (x, y) are the upper-left canvas pixel
 148          * coordinates of the drawable, a temporary pixmap, where things get
 149          * drawn.  (width, height) are the dimensions of the drawable.
 150          */
 151         void (* draw) (FooCanvasItem *item, GdkDrawable *drawable, GdkEventExpose *expose);
 152
 153         /* Calculate the distance from an item to the specified point.  It also
 154          * returns a canvas item which is the item itself in the case of the
 155          * object being an actual leaf item, or a child in case of the object
 156          * being a canvas group.  (cx, cy) are the canvas pixel coordinates that
 157          * correspond to the item-relative coordinates (x, y).
 158          */
 159         double (* point) (FooCanvasItem *item, double x, double y, int cx, int cy,
 160                           FooCanvasItem **actual_item);
 161
 162         void (* translate) (FooCanvasItem *item, double dx, double dy);
 163
 164         /* Fetch the item's bounding box (need not be exactly tight).  This
 165          * should be in item-relative coordinates.
 166          */
 167         void (* bounds) (FooCanvasItem *item, double *x1, double *y1, double *x2, double *y2);
 168
 169         /* Signal: an event ocurred for an item of this type.  The (x, y)
 170          * coordinates are in the canvas world coordinate system.
 171          */
 172         gboolean (* event)                (FooCanvasItem *item, GdkEvent *event);
 173
 174         /* Reserved for future expansion */
 175         gpointer spare_vmethods [4];
 176 };
 177
 178
 179 /* Standard Gtk function */
 180 GType foo_canvas_item_get_type (void) G_GNUC_CONST;
 181
 182 /* Create a canvas item using the standard Gtk argument mechanism.  The item is
 183  * automatically inserted at the top of the specified canvas group.  The last
 184  * argument must be a NULL pointer.
 185  */
 186 FooCanvasItem *foo_canvas_item_new (FooCanvasGroup *parent, GType type,
 187                                     const gchar *first_arg_name, ...);
 188
 189 /* Constructors for use in derived classes and language wrappers */
 190 void foo_canvas_item_construct (FooCanvasItem *item, FooCanvasGroup *parent,
 191                                 const gchar *first_arg_name, va_list args);
 192
 193 /* Configure an item using the standard Gtk argument mechanism.  The last
 194  * argument must be a NULL pointer.
 195  */
 196 void foo_canvas_item_set (FooCanvasItem *item, const gchar *first_arg_name, ...);
 197
 198 /* Used only for language wrappers and the like */
 199 void foo_canvas_item_set_valist (FooCanvasItem *item,
 200                                  const gchar *first_arg_name, va_list args);
 201
 202 /* Move an item by the specified amount */
 203 void foo_canvas_item_move (FooCanvasItem *item, double dx, double dy);
 204
 205 /* Raise an item in the z-order of its parent group by the specified number of
 206  * positions.
 207  */
 208 void foo_canvas_item_raise (FooCanvasItem *item, int positions);
 209
 210 /* Lower an item in the z-order of its parent group by the specified number of
 211  * positions.
 212  */
 213 void foo_canvas_item_lower (FooCanvasItem *item, int positions);
 214
 215 /* Raise an item to the top of its parent group's z-order. */
 216 void foo_canvas_item_raise_to_top (FooCanvasItem *item);
 217
 218 /* Lower an item to the bottom of its parent group's z-order */
 219 void foo_canvas_item_lower_to_bottom (FooCanvasItem *item);
 220
 221 /* Send an item behind another item */
 222 void foo_canvas_item_send_behind (FooCanvasItem *item,
 223                                   FooCanvasItem *behind_item);
 224
 225
 226 /* Show an item (make it visible).  If the item is already shown, it has no
 227  * effect.
 228  */
 229 void foo_canvas_item_show (FooCanvasItem *item);
 230
 231 /* Hide an item (make it invisible).  If the item is already invisible, it has
 232  * no effect.
 233  */
 234 void foo_canvas_item_hide (FooCanvasItem *item);
 235
 236 /* Grab the mouse for the specified item.  Only the events in event_mask will be
 237  * reported.  If cursor is non-NULL, it will be used during the duration of the
 238  * grab.  Time is a proper X event time parameter.  Returns the same values as
 239  * XGrabPointer().
 240  */
 241 int foo_canvas_item_grab (FooCanvasItem *item, unsigned int event_mask,
 242                           GdkCursor *cursor, guint32 etime);
 243
 244 /* Ungrabs the mouse -- the specified item must be the same that was passed to
 245  * foo_canvas_item_grab().  Time is a proper X event time parameter.
 246  */
 247 void foo_canvas_item_ungrab (FooCanvasItem *item, guint32 etime);
 248
 249 /* These functions convert from a coordinate system to another.  "w" is world
 250  * coordinates and "i" is item coordinates.
 251  */
 252 void foo_canvas_item_w2i (FooCanvasItem *item, double *x, double *y);
 253 void foo_canvas_item_i2w (FooCanvasItem *item, double *x, double *y);
 254
 255 /* Remove the item from its parent group and make the new group its parent.  The
 256  * item will be put on top of all the items in the new group.  The item's
 257  * coordinates relative to its new parent to *not* change -- this means that the
 258  * item could potentially move on the screen.
 259  *
 260  * The item and the group must be in the same canvas.  An item cannot be
 261  * reparented to a group that is the item itself or that is an inferior of the
 262  * item.
 263  */
 264 void foo_canvas_item_reparent (FooCanvasItem *item, FooCanvasGroup *new_group);
 265
 266 /* Used to send all of the keystroke events to a specific item as well as
 267  * GDK_FOCUS_CHANGE events.
 268  */
 269 void foo_canvas_item_grab_focus (FooCanvasItem *item);
 270
 271 /* Fetch the bounding box of the item.  The bounding box may not be exactly
 272  * tight, but the canvas items will do the best they can.  The returned bounding
 273  * box is in the coordinate system of the item's parent.
 274  */
 275 void foo_canvas_item_get_bounds (FooCanvasItem *item,
 276                                  double *x1, double *y1, double *x2, double *y2);
 277
 278 /* Request that the update method eventually get called.  This should be used
 279  * only by item implementations.
 280  */
 281 void foo_canvas_item_request_update (FooCanvasItem *item);
 282
 283 /* Request a redraw of the bounding box of the canvas item */
 284 void foo_canvas_item_request_redraw (FooCanvasItem *item);
 285
 286 /* FooCanvasGroup - a group of canvas items
 287  *
 288  * A group is a node in the hierarchical tree of groups/items inside a canvas.
 289  * Groups serve to give a logical structure to the items.
 290  *
 291  * Consider a circuit editor application that uses the canvas for its schematic
 292  * display.  Hierarchically, there would be canvas groups that contain all the
 293  * components needed for an "adder", for example -- this includes some logic
 294  * gates as well as wires.  You can move stuff around in a convenient way by
 295  * doing a foo_canvas_item_move() of the hierarchical groups -- to move an
 296  * adder, simply move the group that represents the adder.
 297  *
 298  * The following arguments are available:
 299  *
 300  * name         type            read/write      description
 301  * --------------------------------------------------------------------------------
 302  * x            double          RW              X coordinate of group's origin
 303  * y            double          RW              Y coordinate of group's origin
 304  */
 305
 306
 307 #define FOO_TYPE_CANVAS_GROUP            (foo_canvas_group_get_type ())
 308 #define FOO_CANVAS_GROUP(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), FOO_TYPE_CANVAS_GROUP, FooCanvasGroup))
 309 #define FOO_CANVAS_GROUP_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), FOO_TYPE_CANVAS_GROUP, FooCanvasGroupClass))
 310 #define FOO_IS_CANVAS_GROUP(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), FOO_TYPE_CANVAS_GROUP))
 311 #define FOO_IS_CANVAS_GROUP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), FOO_TYPE_CANVAS_GROUP))
 312 #define FOO_CANVAS_GROUP_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), FOO_TYPE_CANVAS_GROUP, FooCanvasGroupClass))
 313
 314
 315 struct _FooCanvasGroup {
 316         FooCanvasItem item;
 317
 318         double xpos, ypos;
 319
 320         /* Children of the group */
 321         GList *item_list;
 322         GList *item_list_end;
 323 };
 324
 325 struct _FooCanvasGroupClass {
 326         FooCanvasItemClass parent_class;
 327 };
 328
 329
 330 /* Standard Gtk function */
 331 GType foo_canvas_group_get_type (void) G_GNUC_CONST;
 332
 333
 334 /*** FooCanvas ***/
 335
 336
 337 #define FOO_TYPE_CANVAS            (foo_canvas_get_type ())
 338 #define FOO_CANVAS(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), FOO_TYPE_CANVAS, FooCanvas))
 339 #define FOO_CANVAS_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), FOO_TYPE_CANVAS, FooCanvasClass))
 340 #define FOO_IS_CANVAS(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), FOO_TYPE_CANVAS))
 341 #define FOO_IS_CANVAS_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), FOO_TYPE_CANVAS))
 342 #define FOO_CANVAS_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), FOO_TYPE_CANVAS, FooCanvasClass))
 343
 344
 345 struct _FooCanvas {
 346         GtkLayout layout;
 347
 348         /* Root canvas group */
 349         FooCanvasItem *root;
 350
 351         /* The item containing the mouse pointer, or NULL if none */
 352         FooCanvasItem *current_item;
 353
 354         /* Item that is about to become current (used to track deletions and such) */
 355         FooCanvasItem *new_current_item;
 356
 357         /* Item that holds a pointer grab, or NULL if none */
 358         FooCanvasItem *grabbed_item;
 359
 360         /* If non-NULL, the currently focused item */
 361         FooCanvasItem *focused_item;
 362
 363         /* Event on which selection of current item is based */
 364         GdkEvent pick_event;
 365
 366         /* Scrolling region */
 367         double scroll_x1, scroll_y1;
 368         double scroll_x2, scroll_y2;
 369
 370         /* Scaling factor to be used for display */
 371         double pixels_per_unit;
 372
 373         /* Idle handler ID */
 374         guint idle_id;
 375
 376         /* Signal handler ID for destruction of the root item */
 377         guint root_destroy_id;
 378
 379         /* Internal pixel offsets when zoomed out */
 380         int zoom_xofs, zoom_yofs;
 381
 382         /* Last known modifier state, for deferred repick when a button is down */
 383         int state;
 384
 385         /* Event mask specified when grabbing an item */
 386         guint grabbed_event_mask;
 387
 388         /* Tolerance distance for picking items */
 389         int close_enough;
 390
 391         /* Whether the canvas should center the canvas in the middle of
 392          * the window if the scroll region is smaller than the window */
 393         unsigned int center_scroll_region : 1;
 394
 395         /* Whether items need update at next idle loop iteration */
 396         unsigned int need_update : 1;
 397
 398         /* Are we in the midst of an update */
 399         unsigned int doing_update : 1;
 400
 401         /* Whether the canvas needs redrawing at the next idle loop iteration */
 402         unsigned int need_redraw : 1;
 403
 404         /* Whether current item will be repicked at next idle loop iteration */
 405         unsigned int need_repick : 1;
 406
 407         /* For use by internal pick_current_item() function */
 408         unsigned int left_grabbed_item : 1;
 409
 410         /* For use by internal pick_current_item() function */
 411         unsigned int in_repick : 1;
 412 };
 413
 414 struct _FooCanvasClass {
 415         GtkLayoutClass parent_class;
 416
 417         /* Draw the background for the area given.
 418          */
 419         void (* draw_background) (FooCanvas *canvas,
 420                                   int x, int y, int width, int height);
 421
 422         /* Private Virtual methods for groping the canvas inside bonobo */
 423         void (* request_update) (FooCanvas *canvas);
 424
 425         /* Reserved for future expansion */
 426         gpointer spare_vmethods [4];
 427 };
 428
 429
 430 /* Standard Gtk function */
 431 GType foo_canvas_get_type (void) G_GNUC_CONST;
 432
 433 /* Creates a new canvas.  You should check that the canvas is created with the
 434  * proper visual and colormap.  Any visual will do unless you intend to insert
 435  * gdk_imlib images into it, in which case you should use the gdk_imlib visual.
 436  *
 437  * You should call foo_canvas_set_scroll_region() soon after calling this
 438  * function to set the desired scrolling limits for the canvas.
 439  */
 440 GtkWidget *foo_canvas_new (void);
 441
 442 /* Returns the root canvas item group of the canvas */
 443 FooCanvasGroup *foo_canvas_root (FooCanvas *canvas);
 444
 445 /* Sets the limits of the scrolling region, in world coordinates */
 446 void foo_canvas_set_scroll_region (FooCanvas *canvas,
 447                                    double x1, double y1, double x2, double y2);
 448
 449 /* Gets the limits of the scrolling region, in world coordinates */
 450 void foo_canvas_get_scroll_region (FooCanvas *canvas,
 451                                    double *x1, double *y1, double *x2, double *y2);
 452
 453 /* Sets the number of pixels that correspond to one unit in world coordinates */
 454 void foo_canvas_set_pixels_per_unit (FooCanvas *canvas, double n);
 455
 456 /* Wether the canvas centers the scroll region if it is smaller than the window  */
 457 void foo_canvas_set_center_scroll_region (FooCanvas *canvas, gboolean center_scroll_region);
 458
 459 /* Scrolls the canvas to the specified offsets, given in canvas pixel coordinates */
 460 void foo_canvas_scroll_to (FooCanvas *canvas, int cx, int cy);
 461
 462 /* Returns the scroll offsets of the canvas in canvas pixel coordinates.  You
 463  * can specify NULL for any of the values, in which case that value will not be
 464  * queried.
 465  */
 466 void foo_canvas_get_scroll_offsets (FooCanvas *canvas, int *cx, int *cy);
 467
 468 /* Requests that the canvas be repainted immediately instead of in the idle
 469  * loop.
 470  */
 471 void foo_canvas_update_now (FooCanvas *canvas);
 472
 473 /* Returns the item that is at the specified position in world coordinates, or
 474  * NULL if no item is there.
 475  */
 476 FooCanvasItem *foo_canvas_get_item_at (FooCanvas *canvas, double x, double y);
 477
 478 /* For use only by item type implementations.  Request that the canvas
 479  * eventually redraw the specified region, specified in canvas pixel
 480  * coordinates.  The region contains (x1, y1) but not (x2, y2).
 481  */
 482 void foo_canvas_request_redraw (FooCanvas *canvas, int x1, int y1, int x2, int y2);
 483
 484 /* These functions convert from a coordinate system to another.  "w" is world
 485  * coordinates, "c" is canvas pixel coordinates (pixel coordinates that are
 486  * (0,0) for the upper-left scrolling limit and something else for the
 487  * lower-left scrolling limit).
 488  */
 489 void foo_canvas_w2c_rect_d (FooCanvas *canvas,
 490                             double *x1, double *y1,
 491                             double *x2, double *y2);
 492 void foo_canvas_w2c (FooCanvas *canvas, double wx, double wy, int *cx, int *cy);
 493 void foo_canvas_w2c_d (FooCanvas *canvas, double wx, double wy, double *cx, double *cy);
 494 void foo_canvas_c2w (FooCanvas *canvas, int cx, int cy, double *wx, double *wy);
 495
 496 /* This function takes in coordinates relative to the GTK_LAYOUT
 497  * (canvas)->bin_window and converts them to world coordinates.
 498  * These days canvas coordinates and window coordinates are the same, but
 499  * these are left for backwards compat reasons.
 500  */
 501 void foo_canvas_window_to_world (FooCanvas *canvas,
 502                                  double winx, double winy, double *worldx, double *worldy);
 503
 504 /* This is the inverse of foo_canvas_window_to_world() */
 505 void foo_canvas_world_to_window (FooCanvas *canvas,
 506                                  double worldx, double worldy, double *winx, double *winy);
 507
 508 /* Takes a string specification for a color and allocates it into the specified
 509  * GdkColor.  If the string is null, then it returns FALSE. Otherwise, it
 510  * returns TRUE.
 511  */
 512 int foo_canvas_get_color (FooCanvas *canvas, const char *spec, GdkColor *color);
 513
 514 /* Allocates a color from the RGB value passed into this function. */
 515 gulong foo_canvas_get_color_pixel (FooCanvas *canvas,
 516                                    guint        rgba);
 517
 518 G_END_DECLS
 519
 520 #endif