libgnomecanvasmm
Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gnome::Canvas::Canvas Class Reference

Canvas functions usually operate in either World coordinates (units for the entire canvas), or Canvas coordinates (pixels starting at 0,0 in the top left). More...

#include <canvas.h>

Inheritance diagram for Gnome::Canvas::Canvas:
Gnome::Canvas::CanvasAA

Public Member Functions

virtual ~Canvas ()
 
GnomeCanvas * gobj ()
 Provides access to the underlying C GtkObject. More...
 
const GnomeCanvas * gobj () const
 Provides access to the underlying C GtkObject. More...
 
 Canvas ()
 
Grouproot () const
 Queries the root group of a canvas. More...
 
void set_scroll_region (double x1, double y1, double x2, double y2)
 Sets the scrolling region of a canvas to the specified rectangle. More...
 
void get_scroll_region (double &x1, double &y1, double &x2, double &y2) const
 Queries the scrolling region of a canvas. More...
 
void set_center_scroll_region (bool center)
 When the scrolling region of the canvas is smaller than the canvas window, e.g. the allocation of the canvas, it can be either centered on the window or simply made to be on the upper-left corner on the window. More...
 
bool get_center_scroll_region () const
 Returns whether the canvas is set to center the scrolling region in the window if the former is smaller than the canvas' allocation. More...
 
void set_pixels_per_unit (double n=1.0)
 Sets the zooming factor of a canvas by specifying the number of pixels that correspond to one canvas unit. More...
 
void scroll_to (int x, int y)
 Makes a canvas scroll to the specified offsets, given in canvas pixel units. More...
 
void get_scroll_offsets (int &cx, int &cy) const
 Queries the scrolling offsets of a canvas. More...
 
void update_now ()
 Forces an immediate update and redraw of a canvas. More...
 
Itemget_item_at (double x, double y) const
 Looks for the item that is under the specified position, which must be specified in world coordinates. More...
 
void request_redraw (int x1, int y1, int x2, int y2)
 Convenience function that informs a canvas that the specified rectangle needs to be repainted. More...
 
void request_redraw (ArtUta *uta)
 Informs a canvas that the specified area, given as a microtile array, needs to be repainted. More...
 
Art::AffineTrans w2c_affine () const
 
void w2c (double wx, double wy, int &cx, int &cy) const
 Converts world coordinates into canvas pixel coordinates. More...
 
void w2c (double wx, double wy, double &cx, double &cy) const
 Converts world coordinates into canvas pixel coordinates. More...
 
void c2w (int cx, int cy, double &wx, double &wy) const
 Converts canvas pixel coordinates to world coordinates. More...
 
void window_to_world (double winx, double winy, double &worldx, double &worldy) const
 Converts window-relative coordinates into world coordinates. More...
 
void world_to_window (double worldx, double worldy, double &winx, double &winy) const
 Converts world coordinates into window-relative coordinates. More...
 
bool get_color (const Glib::ustring &spec, Gdk::Color &color) const
 
gulong get_color_pixel (guint rgba) const
 Allocates a color from the RGBA value passed into this function. More...
 
void set_stipple_origin (const Glib::RefPtr< Gdk::GC > &gc)
 Sets the stipple origin of the specified GC as is appropriate for the canvas, so that it will be aligned with other stipple patterns used by canvas items. More...
 
void set_dither (Gdk::RgbDither dither)
 Controls dithered rendering for antialiased canvases. More...
 
Gdk::RgbDither get_dither () const
 Returns the type of dithering used to render an antialiased canvas. More...
 
void update_svp (ArtSVP **p_svp, ArtSVP *new_svp)
 Sets the svp to the new value, requesting repaint on what's changed. More...
 
void update_svp_clip (ArtSVP **p_svp, ArtSVP *new_svp, ArtSVP *clip_svp)
 Sets the svp to the new value, clipping if necessary, and requesting repaint on what's changed. More...
 
double get_pixels_per_unit () const
 
Glib::SignalProxy5< void,
const Glib::RefPtr
< Gdk::Drawable > &, int, int,
int, int > 
signal_draw_background ()
 
Glib::SignalProxy1< void,
GnomeCanvasBuf * > 
signal_render_background ()
 
virtual void request_update_vfunc ()
 
Glib::PropertyProxy_ReadOnly
< bool > 
property_aa () const
 The antialiasing mode of the canvas. More...
 

Protected Member Functions

virtual void on_draw_background (const Glib::RefPtr< Gdk::Drawable > &drawable, int x, int y, int width, int height)
 
virtual void on_render_background (GnomeCanvasBuf *buf)
 

Related Functions

(Note that these are not member functions.)

Gnome::Canvas::Canvaswrap (GnomeCanvas *object, bool take_copy=false)
 A Glib::wrap() method for this object. More...
 

Detailed Description

Canvas functions usually operate in either World coordinates (units for the entire canvas), or Canvas coordinates (pixels starting at 0,0 in the top left).

There are functions to transform from one to the other.

Constructor & Destructor Documentation

virtual Gnome::Canvas::Canvas::~Canvas ( )
virtual
Gnome::Canvas::Canvas::Canvas ( )

Member Function Documentation

void Gnome::Canvas::Canvas::c2w ( int  cx,
int  cy,
double &  wx,
double &  wy 
) const

Converts canvas pixel coordinates to world coordinates.

Parameters
cxCanvas pixel X coordinate.
cyCanvas pixel Y coordinate.
wxX world coordinate (return value).
wyY world coordinate (return value).
bool Gnome::Canvas::Canvas::get_center_scroll_region ( ) const

Returns whether the canvas is set to center the scrolling region in the window if the former is smaller than the canvas' allocation.

Returns
Whether the scroll region is being centered in the canvas window.
bool Gnome::Canvas::Canvas::get_color ( const Glib::ustring &  spec,
Gdk::Color &  color 
) const
gulong Gnome::Canvas::Canvas::get_color_pixel ( guint  rgba) const

Allocates a color from the RGBA value passed into this function.

The alpha opacity value is discarded, since normal X colors do not support it.

Parameters
rgbaRGBA color specification.
Returns
Allocated pixel value corresponding to the specified color.
Gdk::RgbDither Gnome::Canvas::Canvas::get_dither ( ) const

Returns the type of dithering used to render an antialiased canvas.

Returns
The dither setting.
Item* Gnome::Canvas::Canvas::get_item_at ( double  x,
double  y 
) const

Looks for the item that is under the specified position, which must be specified in world coordinates.

Parameters
xX position in world coordinates.
yY position in world coordinates.
Returns
The sought item, or 0 if no item is at the specified coordinates.
double Gnome::Canvas::Canvas::get_pixels_per_unit ( ) const
void Gnome::Canvas::Canvas::get_scroll_offsets ( int &  cx,
int &  cy 
) const

Queries the scrolling offsets of a canvas.

The values are returned in canvas pixel units.

Parameters
cxHorizontal scrolling offset (return value).
cyVertical scrolling offset (return value).
void Gnome::Canvas::Canvas::get_scroll_region ( double &  x1,
double &  y1,
double &  x2,
double &  y2 
) const

Queries the scrolling region of a canvas.

Parameters
x1Leftmost limit of the scrolling region (return value).
y1Upper limit of the scrolling region (return value).
x2Rightmost limit of the scrolling region (return value).
y2Lower limit of the scrolling region (return value).
GnomeCanvas* Gnome::Canvas::Canvas::gobj ( )
inline

Provides access to the underlying C GtkObject.

const GnomeCanvas* Gnome::Canvas::Canvas::gobj ( ) const
inline

Provides access to the underlying C GtkObject.

virtual void Gnome::Canvas::Canvas::on_draw_background ( const Glib::RefPtr< Gdk::Drawable > &  drawable,
int  x,
int  y,
int  width,
int  height 
)
protectedvirtual
virtual void Gnome::Canvas::Canvas::on_render_background ( GnomeCanvasBuf *  buf)
protectedvirtual
Glib::PropertyProxy_ReadOnly<bool> Gnome::Canvas::Canvas::property_aa ( ) const

The antialiasing mode of the canvas.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.
void Gnome::Canvas::Canvas::request_redraw ( int  x1,
int  y1,
int  x2,
int  y2 
)

Convenience function that informs a canvas that the specified rectangle needs to be repainted.

This function converts the rectangle to a microtile array and feeds it to request_redraw_uta(). The rectangle includes x1 and y1, but not x2 and y2. To be used only by item implementations.

Parameters
x1Leftmost coordinate of the rectangle to be redrawn.
y1Upper coordinate of the rectangle to be redrawn.
x2Rightmost coordinate of the rectangle to be redrawn, plus 1.
y2Lower coordinate of the rectangle to be redrawn, plus 1.
void Gnome::Canvas::Canvas::request_redraw ( ArtUta *  uta)

Informs a canvas that the specified area, given as a microtile array, needs to be repainted.

To be used only by item implementations.

Parameters
utaMicrotile array that specifies the area to be redrawn. It will be freed by this function, so the argument you pass will be invalid after you call this function.
virtual void Gnome::Canvas::Canvas::request_update_vfunc ( )
virtual
Group* Gnome::Canvas::Canvas::root ( ) const

Queries the root group of a canvas.

Returns
The root group of the specified canvas.
void Gnome::Canvas::Canvas::scroll_to ( int  x,
int  y 
)

Makes a canvas scroll to the specified offsets, given in canvas pixel units.

The canvas will adjust the view so that it is not outside the scrolling region. This function is typically not used, as it is better to hook scrollbars to the canvas layout's scrolling adjusments.

Parameters
cxHorizontal scrolling offset in canvas pixel units.
cyVertical scrolling offset in canvas pixel units.
void Gnome::Canvas::Canvas::set_center_scroll_region ( bool  center)

When the scrolling region of the canvas is smaller than the canvas window, e.g. the allocation of the canvas, it can be either centered on the window or simply made to be on the upper-left corner on the window.

This function lets you configure this property.

Parameters
center_scroll_regionWhether to center the scrolling region in the canvas window when it is smaller than the canvas' allocation.
void Gnome::Canvas::Canvas::set_dither ( Gdk::RgbDither  dither)

Controls dithered rendering for antialiased canvases.

The value of dither should be Gdk::RGB_DITHER_NONE, Gdk::RGB_DITHER_NORMAL, or Gdk::RGB_DITHER_MAX. The default canvas setting is Gdk::RGB_DITHER_NORMAL.

Parameters
ditherType of dithering used to render an antialiased canvas.
void Gnome::Canvas::Canvas::set_pixels_per_unit ( double  n = 1.0)

Sets the zooming factor of a canvas by specifying the number of pixels that correspond to one canvas unit.

The anchor point for zooming, i.e. the point that stays fixed and all others zoom inwards or outwards from it, depends on whether the canvas is set to center the scrolling region or not. You can control this using the set_center_scroll_region() function. If the canvas is set to center the scroll region, then the center of the canvas window is used as the anchor point for zooming. Otherwise, the upper-left corner of the canvas window is used as the anchor point.

Parameters
nThe number of pixels that correspond to one canvas unit.
void Gnome::Canvas::Canvas::set_scroll_region ( double  x1,
double  y1,
double  x2,
double  y2 
)

Sets the scrolling region of a canvas to the specified rectangle.

The canvas will then be able to scroll only within this region. The view of the canvas is adjusted as appropriate to display as much of the new region as possible.

Parameters
x1Leftmost limit of the scrolling region.
y1Upper limit of the scrolling region.
x2Rightmost limit of the scrolling region.
y2Lower limit of the scrolling region.
void Gnome::Canvas::Canvas::set_stipple_origin ( const Glib::RefPtr< Gdk::GC > &  gc)

Sets the stipple origin of the specified GC as is appropriate for the canvas, so that it will be aligned with other stipple patterns used by canvas items.

This is typically only needed by item implementations.

Parameters
gcGC on which to set the stipple origin.
Glib::SignalProxy5< void,const Glib::RefPtr<Gdk::Drawable>&,int,int,int,int > Gnome::Canvas::Canvas::signal_draw_background ( )
Prototype:
void on_my_draw_background(const Glib::RefPtr<Gdk::Drawable>& drawable, int x, int y, int width, int height)
Glib::SignalProxy1< void,GnomeCanvasBuf* > Gnome::Canvas::Canvas::signal_render_background ( )
Prototype:
void on_my_render_background(GnomeCanvasBuf* buf)
void Gnome::Canvas::Canvas::update_now ( )

Forces an immediate update and redraw of a canvas.

If the canvas does not have any pending update or redraw requests, then no action is taken. This is typically only used by applications that need explicit control of when the display is updated, like games. It is not needed by normal applications.

void Gnome::Canvas::Canvas::update_svp ( ArtSVP **  p_svp,
ArtSVP *  new_svp 
)

Sets the svp to the new value, requesting repaint on what's changed.

This function takes responsibility for freeing new_svp.

Parameters
p_svpA pointer to the existing svp.
new_svpThe new svp.
void Gnome::Canvas::Canvas::update_svp_clip ( ArtSVP **  p_svp,
ArtSVP *  new_svp,
ArtSVP *  clip_svp 
)

Sets the svp to the new value, clipping if necessary, and requesting repaint on what's changed.

This function takes responsibility for freeing new_svp.

Parameters
p_svpA pointer to the existing svp.
new_svpThe new svp.
clip_svpA clip path, if non-null.
void Gnome::Canvas::Canvas::w2c ( double  wx,
double  wy,
int &  cx,
int &  cy 
) const

Converts world coordinates into canvas pixel coordinates.

Parameters
wxWorld X coordinate.
wyWorld Y coordinate.
cxX pixel coordinate (return value).
cyY pixel coordinate (return value).
void Gnome::Canvas::Canvas::w2c ( double  wx,
double  wy,
double &  cx,
double &  cy 
) const

Converts world coordinates into canvas pixel coordinates.

This version

Parameters
wxWorld X coordinate.
wyWorld Y coordinate.
cxX pixel coordinate (return value).
cyY pixel coordinate (return value).
Returns
Coordinates in floating point coordinates, for greater precision.
Art::AffineTrans Gnome::Canvas::Canvas::w2c_affine ( ) const
void Gnome::Canvas::Canvas::window_to_world ( double  winx,
double  winy,
double &  worldx,
double &  worldy 
) const

Converts window-relative coordinates into world coordinates.

You can use this when you need to convert mouse coordinates into world coordinates, for example.

Parameters
winxWindow-relative X coordinate.
winyWindow-relative Y coordinate.
worldxX world coordinate (return value).
worldyY world coordinate (return value).
void Gnome::Canvas::Canvas::world_to_window ( double  worldx,
double  worldy,
double &  winx,
double &  winy 
) const

Converts world coordinates into window-relative coordinates.

Parameters
worldxWorld X coordinate.
worldyWorld Y coordinate.
winxX window-relative coordinate.
winyY window-relative coordinate.

Friends And Related Function Documentation

Gnome::Canvas::Canvas * wrap ( GnomeCanvas *  object,
bool  take_copy = false 
)
related

A Glib::wrap() method for this object.

Parameters
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns
A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file: