libs/libgnomecanvasmm/libgnomecanvasmm/canvas.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _LIBGNOMECANVASMM_CANVAS_H
   4 #define _LIBGNOMECANVASMM_CANVAS_H
   5
   6 #include <glibmm.h>
   7
   8 // -*- C++ -*-
   9 /* $Id$ */
  10
  11 /* canvas.h
  12  *
  13  * Copyright (C) 1998 EMC Capital Management Inc.
  14  * Developed by Havoc Pennington <hp@pobox.com>
  15  *
  16  * Copyright (C) 1999 The Gtk-- Development Team
  17  *
  18  * This library is free software; you can redistribute it and/or
  19  * modify it under the terms of the GNU Library General Public
  20  * License as published by the Free Software Foundation; either
  21  * version 2 of the License, or (at your option) any later version.
  22  *
  23  * This library is distributed in the hope that it will be useful,
  24  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  25  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  26  * Library General Public License for more details.
  27  *
  28  * You should have received a copy of the GNU Library General Public
  29  * License along with this library; if not, write to the Free
  30  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  31  */
  32
  33 #include <libgnomecanvas/gnome-canvas.h>
  34 #include <libgnomecanvasmm/affinetrans.h>
  35 #include <gtkmm/layout.h>
  36 #include <gdkmm/color.h>
  37
  38
  39 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  40 typedef struct _GnomeCanvas GnomeCanvas;
  41 typedef struct _GnomeCanvasClass GnomeCanvasClass;
  42 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  43
  44
  45 namespace Gnome
  46 {
  47
  48 namespace Canvas
  49 { class Canvas_Class; } // namespace Canvas
  50
  51 } // namespace Gnome
  52 namespace Gnome
  53 {
  54
  55 namespace Canvas
  56 {
  57
  58 class Item;
  59 class Group;
  60
  61 /** Canvas functions usually operate in either World coordinates
  62  * (units for the entire canvas), or Canvas coordinates (pixels starting
  63  * at 0,0 in the top left).  There are functions to transform from
  64  * one to the other.
  65  */
  66
  67 class Canvas : public Gtk::Layout
  68 {
  69   public:
  70 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  71   typedef Canvas CppObjectType;
  72   typedef Canvas_Class CppClassType;
  73   typedef GnomeCanvas BaseObjectType;
  74   typedef GnomeCanvasClass BaseClassType;
  75 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  76
  77   virtual ~Canvas();
  78
  79 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  80
  81 protected:
  82   friend class Canvas_Class;
  83   static CppClassType canvas_class_;
  84
  85   // noncopyable
  86   Canvas(const Canvas&);
  87   Canvas& operator=(const Canvas&);
  88
  89 protected:
  90   explicit Canvas(const Glib::ConstructParams& construct_params);
  91   explicit Canvas(GnomeCanvas* castitem);
  92
  93 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  94
  95 public:
  96 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  97   static GType get_type()      G_GNUC_CONST;
  98   static GType get_base_type() G_GNUC_CONST;
  99 #endif
 100
 101   ///Provides access to the underlying C GtkObject.
 102   GnomeCanvas*       gobj()       { return reinterpret_cast<GnomeCanvas*>(gobject_); }
 103
 104   ///Provides access to the underlying C GtkObject.
 105   const GnomeCanvas* gobj() const { return reinterpret_cast<GnomeCanvas*>(gobject_); }
 106
 107
 108 public:
 109   //C++ methods used to invoke GTK+ virtual functions:
 110
 111 protected:
 112   //GTK+ Virtual Functions (override these to change behaviour):
 113
 114   //Default Signal Handlers::
 115   virtual void on_draw_background(const Glib::RefPtr<Gdk::Drawable>& drawable, int x, int y, int width, int height);
 116   virtual void on_render_background(GnomeCanvasBuf* buf);
 117
 118
 119 private:
 120 ;
 121 public:
 122   Canvas();
 123
 124   //Allow CanvasAA to access the canvas_class_ member.
 125
 126
 127   //: Get the root canvas item
 128
 129   /** Queries the root group of a canvas.
 130    * @return The root group of the specified canvas.
 131    */
 132   Group* root() const;
 133
 134   //: Limits of scroll region
 135
 136   /** Sets the scrolling region of a canvas to the specified rectangle.  The canvas
 137    * will then be able to scroll only within this region.  The view of the canvas
 138    * is adjusted as appropriate to display as much of the new region as possible.
 139    * @param x1 Leftmost limit of the scrolling region.
 140    * @param y1 Upper limit of the scrolling region.
 141    * @param x2 Rightmost limit of the scrolling region.
 142    * @param y2 Lower limit of the scrolling region.
 143    */
 144   void set_scroll_region(double x1, double y1, double x2, double y2);
 145
 146   //: Get limits of scroll region
 147
 148   /** Queries the scrolling region of a canvas.
 149    * @param x1 Leftmost limit of the scrolling region (return value).
 150    * @param y1 Upper limit of the scrolling region (return value).
 151    * @param x2 Rightmost limit of the scrolling region (return value).
 152    * @param y2 Lower limit of the scrolling region (return value).
 153    */
 154   void get_scroll_region(double& x1, double& y1, double& x2, double& y2) const;
 155
 156
 157   /** When the scrolling region of the canvas is smaller than the canvas window,
 158    * e.g.\  the allocation of the canvas, it can be either centered on the window
 159    * or simply made to be on the upper-left corner on the window.  This function
 160    * lets you configure this property.
 161    * @param center_scroll_region Whether to center the scrolling region in the canvas
 162    * window when it is smaller than the canvas' allocation.
 163    */
 164   void set_center_scroll_region(bool center);
 165
 166
 167   /** Returns whether the canvas is set to center the scrolling region in the window
 168    * if the former is smaller than the canvas' allocation.
 169    * @return Whether the scroll region is being centered in the canvas window.
 170    */
 171   bool get_center_scroll_region() const;
 172
 173   //: Set the pixels/world coordinates ratio
 174   //- With no arguments sets to default of 1.0.
 175
 176   /** Sets the zooming factor of a canvas by specifying the number of pixels that
 177    * correspond to one canvas unit.
 178    *
 179    * The anchor point for zooming, i.e. the point that stays fixed and all others
 180    * zoom inwards or outwards from it, depends on whether the canvas is set to
 181    * center the scrolling region or not.  You can control this using the
 182    * set_center_scroll_region() function.  If the canvas is set to
 183    * center the scroll region, then the center of the canvas window is used as the
 184    * anchor point for zooming.  Otherwise, the upper-left corner of the canvas
 185    * window is used as the anchor point.
 186    * @param n The number of pixels that correspond to one canvas unit.
 187    */
 188   void set_pixels_per_unit(double n = 1.0);
 189
 190   //: Shift window.
 191   //- Makes a canvas scroll to the specified offsets, given in canvas pixel
 192   //- units.
 193   //- The canvas will adjust the view so that it is not outside the scrolling
 194   //- region.  This function is typically not used, as it is better to hook
 195   //- scrollbars to the canvas layout's scrolling adjusments.
 196
 197   /** Makes a canvas scroll to the specified offsets, given in canvas pixel units.
 198    * The canvas will adjust the view so that it is not outside the scrolling
 199    * region.  This function is typically not used, as it is better to hook
 200    * scrollbars to the canvas layout's scrolling adjusments.
 201    * @param cx Horizontal scrolling offset in canvas pixel units.
 202    * @param cy Vertical scrolling offset in canvas pixel units.
 203    */
 204   void scroll_to(int x, int y);
 205
 206   //: Scroll offsets in canvas pixel coordinates.
 207
 208   /** Queries the scrolling offsets of a canvas.  The values are returned in canvas
 209    * pixel units.
 210    * @param cx Horizontal scrolling offset (return value).
 211    * @param cy Vertical scrolling offset (return value).
 212    */
 213   void get_scroll_offsets(int& cx, int& cy) const;
 214
 215   //: Repaint immediately, don't wait for idle loop
 216   //- normally the canvas queues repainting and does it in an
 217   //- idle loop
 218
 219   /** Forces an immediate update and redraw of a canvas.  If the canvas does not
 220    * have any pending update or redraw requests, then no action is taken.  This is
 221    * typically only used by applications that need explicit control of when the
 222    * display is updated, like games.  It is not needed by normal applications.
 223    */
 224   void update_now();
 225
 226   //: Find an item at a location.
 227   //- Looks for the item that is under the specified position, which must be
 228   //- specified in world coordinates.  Arguments are in world coordinates.
 229   //- Returns 0 if no item is at that
 230   //- location.
 231
 232   /** Looks for the item that is under the specified position, which must be
 233    * specified in world coordinates.
 234    * @param x X position in world coordinates.
 235    * @param y Y position in world coordinates.
 236    * @return The sought item, or <tt>0</tt> if no item is at the specified
 237    * coordinates.
 238    */
 239   Item* get_item_at(double x, double y) const;
 240
 241
 242   //: Repaint small area (internal)
 243   //- Used only by item implementations. Request an eventual redraw
 244   //- of the region, which includes x1,y1 but not x2,y2
 245
 246   /** Convenience function that informs a canvas that the specified rectangle needs
 247    * to be repainted.  This function converts the rectangle to a microtile array
 248    * and feeds it to request_redraw_uta().  The rectangle includes
 249    *  @a x1  and @a y1 , but not @a x2  and @a y2 .  To be used only by item implementations.
 250    * @param x1 Leftmost coordinate of the rectangle to be redrawn.
 251    * @param y1 Upper coordinate of the rectangle to be redrawn.
 252    * @param x2 Rightmost coordinate of the rectangle to be redrawn, plus 1.
 253    * @param y2 Lower coordinate of the rectangle to be redrawn, plus 1.
 254    */
 255   void request_redraw(int x1, int y1, int x2, int y2);
 256   //TODO: Investigate ArtUta.
 257
 258   /** Informs a canvas that the specified area, given as a microtile array, needs
 259    * to be repainted.  To be used only by item implementations.
 260    * @param uta Microtile array that specifies the area to be redrawn.  It will
 261    * be freed by this function, so the argument you pass will be invalid
 262    * after you call this function.
 263    */
 264   void request_redraw(ArtUta* uta);
 265
 266   Art::AffineTrans w2c_affine() const;
 267
 268
 269   //: Convert from World to canvas coordinates (units for the entire canvas)
 270   //: to Canvas coordinates (pixels starting at 0,0 in the top left
 271   //: of the visible area). The relationship depends on the current
 272   //: scroll position and the pixels_per_unit ratio (zoom factor)
 273
 274   /** Converts world coordinates into canvas pixel coordinates.
 275    * @param wx World X coordinate.
 276    * @param wy World Y coordinate.
 277    * @param cx X pixel coordinate (return value).
 278    * @param cy Y pixel coordinate (return value).
 279    */
 280   void w2c(double wx, double wy, int& cx, int& cy) const;
 281
 282   /** Converts world coordinates into canvas pixel coordinates.  This version
 283    * @param wx World X coordinate.
 284    * @param wy World Y coordinate.
 285    * @param cx X pixel coordinate (return value).
 286    * @param cy Y pixel coordinate (return value).
 287    * @return Coordinates in floating point coordinates, for greater precision.
 288    */
 289   void w2c(double wx, double wy, double& cx, double& cy) const;
 290
 291   //: From Canvas to World
 292
 293   /** Converts canvas pixel coordinates to world coordinates.
 294    * @param cx Canvas pixel X coordinate.
 295    * @param cy Canvas pixel Y coordinate.
 296    * @param wx X world coordinate (return value).
 297    * @param wy Y world coordinate (return value).
 298    */
 299   void c2w(int cx, int cy, double& wx, double& wy) const;
 300
 301   //: Convert from Window coordinates to world coordinates.
 302   //- Window coordinates are based of the widget's GdkWindow.
 303   //- This is fairly low-level and not generally useful.
 304
 305   /** Converts window-relative coordinates into world coordinates.  You can use
 306    * this when you need to convert mouse coordinates into world coordinates, for
 307    * example.
 308    * @param winx Window-relative X coordinate.
 309    * @param winy Window-relative Y coordinate.
 310    * @param worldx X world coordinate (return value).
 311    * @param worldy Y world coordinate (return value).
 312    */
 313   void window_to_world (double winx,double winy, double& worldx,double& worldy) const;
 314
 315   //: Convert from world coordinates to Window coordinates.
 316   //- Window coordinates are based of the widget's GdkWindow.
 317   //- This is fairly low-level and not generally useful.
 318
 319   /** Converts world coordinates into window-relative coordinates.
 320    * @param worldx World X coordinate.
 321    * @param worldy World Y coordinate.
 322    * @param winx X window-relative coordinate.
 323    * @param winy Y window-relative coordinate.
 324    */
 325   void world_to_window (double worldx, double worldy, double& winx, double& winy) const;
 326
 327   //: Parse color spec string and allocate it into the GdkColor.
 328   bool get_color(const Glib::ustring& spec, Gdk::Color& color) const;
 329
 330
 331 /* Allocates a color from the RGB value passed into this function. */
 332
 333   /** Allocates a color from the RGBA value passed into this function.  The alpha
 334    * opacity value is discarded, since normal X colors do not support it.
 335    * @param rgba RGBA color specification.
 336    * @return Allocated pixel value corresponding to the specified color.
 337    */
 338   gulong get_color_pixel(guint rgba) const;
 339
 340   /** Sets the stipple origin of the specified GC as is appropriate for the canvas,
 341    * so that it will be aligned with other stipple patterns used by canvas items.
 342    * This is typically only needed by item implementations.
 343    * @param gc GC on which to set the stipple origin.
 344    */
 345   void set_stipple_origin(const Glib::RefPtr<Gdk::GC>& gc);
 346
 347   /** Controls dithered rendering for antialiased canvases. The value of
 348    * dither should be Gdk::RGB_DITHER_NONE, Gdk::RGB_DITHER_NORMAL, or
 349    * Gdk::RGB_DITHER_MAX. The default canvas setting is
 350    * Gdk::RGB_DITHER_NORMAL.
 351    * @param dither Type of dithering used to render an antialiased canvas.
 352    */
 353   void set_dither(Gdk::RgbDither dither);
 354
 355   /** Returns the type of dithering used to render an antialiased canvas.
 356    * @return The dither setting.
 357    */
 358   Gdk::RgbDither get_dither() const;
 359
 360
 361   //TODO: Look at ArtSVP.
 362
 363   /** Sets the svp to the new value, requesting repaint on what's changed. This
 364    * function takes responsibility for freeing new_svp.
 365    * @param p_svp A pointer to the existing svp.
 366    * @param new_svp The new svp.
 367    */
 368   void update_svp(ArtSVP** p_svp, ArtSVP* new_svp);
 369
 370   /** Sets the svp to the new value, clipping if necessary, and requesting repaint
 371    * on what's changed. This function takes responsibility for freeing new_svp.
 372    * @param p_svp A pointer to the existing svp.
 373    * @param new_svp The new svp.
 374    * @param clip_svp A clip path, if non-null.
 375    */
 376   void update_svp_clip(ArtSVP** p_svp, ArtSVP* new_svp, ArtSVP* clip_svp);
 377
 378   // The following are simply accessed via the struct in C,
 379   //  but Federico reports that they are meant to be used.
 380   //: Get the pixels per unit.
 381   double get_pixels_per_unit() const;
 382
 383   //: Draw the background for the area given.
 384   //- This method is only used for non-antialiased canvases.
 385
 386
 387   Glib::SignalProxy5< void,const Glib::RefPtr<Gdk::Drawable>&,int,int,int,int > signal_draw_background();
 388
 389   // Render the background for the buffer given.
 390   //- The buf data structure contains both a pointer to a packed 24-bit
 391   //- RGB array, and the coordinates.
 392   //- This method is only used for antialiased canvases.
 393
 394
 395   Glib::SignalProxy1< void,GnomeCanvasBuf* > signal_render_background();
 396
 397   //: Private Virtual methods for groping the canvas inside bonobo.
 398     virtual void request_update_vfunc();
 399
 400   // Whether the canvas is in antialiased mode or not.
 401   /**
 402    *
 403    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 404    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 405    * the value of the property changes.
 406    */
 407   Glib::PropertyProxy<bool> property_aa() ;
 408
 409 /**
 410    *
 411    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 412    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 413    * the value of the property changes.
 414    */
 415   Glib::PropertyProxy_ReadOnly<bool> property_aa() const;
 416
 417
 418 };
 419
 420 //: Antialiased Canvas.
 421 //- Constructor takes care of push/pop actions of the colormap.
 422 class CanvasAA : public Canvas
 423 {
 424   public:
 425     CanvasAA();
 426     virtual ~CanvasAA();
 427 };
 428
 429 } /* namespace Canvas */
 430 } /* namespace Gnome */
 431
 432
 433 namespace Glib
 434 {
 435   /** @relates Gnome::Canvas::Canvas
 436    * @param object The C instance
 437    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 438    * @result A C++ instance that wraps this C instance.
 439    */
 440   Gnome::Canvas::Canvas* wrap(GnomeCanvas* object, bool take_copy = false);
 441 }
 442 #endif /* _LIBGNOMECANVASMM_CANVAS_H */
 443