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