NAME¶
Gnome2::Canvas - A structured graphics canvas
SYNOPSIS¶
use strict;
use Gtk2 -init;
use Gnome2::Canvas;
my $window = Gtk2::Window->new;
my $scroller = Gtk2::ScrolledWindow->new;
my $canvas = Gnome2::Canvas->new;
$scroller->add ($canvas);
$window->add ($scroller);
$window->set_default_size (150, 150);
$canvas->set_scroll_region (0, 0, 200, 200);
$window->show_all;
my $root = $canvas->root;
Gnome2::Canvas::Item->new ($root, 'Gnome2::Canvas::Text',
x => 20,
y => 15,
fill_color => 'black',
font => 'Sans 14',
anchor => 'GTK_ANCHOR_NW',
text => 'Hello, World!');
my $box = Gnome2::Canvas::Item->new ($root, 'Gnome2::Canvas::Rect',
x1 => 10, y1 => 5,
x2 => 150, y2 => 135,
fill_color => 'red',
outline_color => 'black');
$box->lower_to_bottom;
$box->signal_connect (event => sub {
my ($item, $event) = @_;
warn "event ".$event->type."\n";
});
Gtk2->main;
DESCRIPTION¶
The Gnome Canvas is an engine for structured graphics that offers a rich imaging
model, high-performance rendering, and a powerful, high level API. It offers a
choice of two rendering back-ends, one based on GDK for extremely fast
display, and another based on Libart, a sophisticated, antialiased,
alpha-compositing engine. This widget can be used for flexible display of
graphics and for creating interactive user interface elements.
To create a new Gnome2::Canvas widget call "Gnome2::Canvas->new" or
"Gnome2::Canvas->new_aa" for an anti-aliased mode canvas.
A Gnome2::Canvas contains one or more Gnome2::CanvasItem objects. Items consist
of graphing elements like lines, ellipses, polygons, images, text, and curves.
These items are organized using Gnome2::CanvasGroup objects, which are
themselves derived from Gnome2::CanvasItem. Since a group is an item it can be
contained within other groups, forming a tree of canvas items. Certain
operations, like translating and scaling, can be performed on all items in a
group.
There is a special root group created by a Gnome2::Canvas. This is the top level
group under which all items in a canvas are contained. The root group is
available as "$canvas->root".
There are several different coordinate systems used by Gnome2::Canvas widgets.
The primary system is a logical, abstract coordinate space called world
coordinates. World coordinates are expressed as unbounded double floating
point numbers. When it comes to rendering to a screen the canvas pixel
coordinate system (also referred to as just canvas coordinates) is used. This
system uses integers to specify screen pixel positions. A user defined scaling
factor and offset are used to convert between world coordinates and canvas
coordinates. Each item in a canvas has its own coordinate system called item
coordinates. This system is specified in world coordinates but they are
relative to an item (0.0, 0.0 would be the top left corner of the item). The
final coordinate system of interest is window coordinates. These are like
canvas coordinates but are offsets from within a window a canvas is displayed
in. This last system is rarely used, but is useful when manually handling GDK
events (such as drag and drop) which are specified in window coordinates (the
events processed by the canvas are already converted for you).
Along with different coordinate systems come methods to convert between them.
"$canvas->w2c" converts world to canvas pixel coordinates and
"canvas->c2w" converts from canvas to world. To get the affine
transform matrix for converting from world coordinates to canvas coordinates
call "$canvas->w2c_affine".
"$canvas->window_to_world" converts from window to world
coordinates and "$canvas->world_to_window" converts in the other
direction. There are no methods for converting between canvas and window
coordinates, since this is just a matter of subtracting the canvas scrolling
offset. To convert to/from item coordinates use the methods defined for
Gnome2::CanvasItem objects.
To set the canvas zoom factor (canvas pixels per world unit, the scaling factor)
call "$canvas->set_pixels_per_unit"; setting this to 1.0 will
cause the two coordinate systems to correspond (e.g., [5, 6] in pixel units
would be [5.0, 6.0] in world units).
Defining the scrollable area of a canvas widget is done by calling
"$canvas->set_scroll_region" and to get the current region
"$canvas->get_scroll_region" can be used. If the window is larger
than the canvas scrolling region it can optionally be centered in the window.
Use "$canvas->set_center_scroll_region" to enable or disable this
behavior. To scroll to a particular canvas pixel coordinate use
"$canvas->scroll_to" (typically not used since scrollbars are
usually set up to handle the scrolling), and to get the current canvas pixel
scroll offset call "$canvas->get_scroll_offsets".
HIERARCHY¶
Glib::Object
+----Glib::InitiallyUnowned
+----Gtk2::Object
+----Gtk2::Widget
+----Gtk2::Container
+----Gtk2::Layout
+----Gnome2::Canvas
INTERFACES¶
Glib::Object::_Unregistered::AtkImplementorIface
Gtk2::Buildable
METHODS¶
Create a new empty canvas in non-antialiased mode.
Create a new empty canvas in antialiased mode.
boolean = $canvas-> aa¶
Returns true if
$canvas was created in anti-aliased mode.
($bx1, $by1, $bx2, $by2) = Gnome2::Canvas-> get_butt_points ($x1, $y1, $x2, $y2, $width, $project)¶
- •
- $x1 (double)
- •
- $y1 (double)
- •
- $x2 (double)
- •
- $y2 (double)
- •
- $width (double)
- •
- $project (integer)
(wx, wy) = $canvas-> c2w ($cx, $cy)¶
- •
- $cx (integer)
- •
- $cy (integer)
- •
- $center_scroll_region (boolean)
list = $canvas-> get_color ($spec)¶
- •
- $spec (string)
Returns an integer indicating the success of the color allocation and a
GdkColor.
unsigned = $canvas-> get_color_pixel ($rgba)¶
- •
- $rgba (integer)
rgbdither = $canvas-> get_dither¶
$canvas->set_dither ($dither)¶
- •
- $dither (Gtk2::Gdk::RgbDither)
item = $canvas-> get_item_at ($x, $y)¶
- •
- $x (double)
- •
- $y (double)
($mx1, $my1, $mx2, $my2) = Gnome2::Canvas-> get_miter_points ($x1, $y1, $x2, $y2, $x3, $y3, $width)¶
- •
- $x1 (double)
- •
- $y1 (double)
- •
- $x2 (double)
- •
- $y2 (double)
- •
- $x3 (double)
- •
- $y3 (double)
- •
- $width (double)
double = $canvas-> get_pixels_per_unit¶
Fetch
$canvas' scale factor.
$canvas->set_pixels_per_unit ($n)¶
- •
- $n (double)
Set the zooming factor of
$canvas by specifying the number
of screen pixels that correspond to one canvas unit.
double = Gnome2::Canvas-> polygon_to_point ($poly_ref, $x, $y)¶
- •
- $poly_ref (arrayref) coordinate pairs that make up the polygon
- •
- $x (double)
- •
- $y (double)
Return the distance from the point
$x,
$y to the polygon described by
the vertices in
$poly_ref, or zero if the point is inside
the polygon.
$canvas->request_redraw ($x1, $y1, $x2, $y2)¶
- •
- $x1 (integer)
- •
- $y1 (integer)
- •
- $x2 (integer)
- •
- $y2 (integer)
group = $canvas-> root¶
- •
- $x1 (double)
- •
- $y1 (double)
- •
- $x2 (double)
- •
- $y2 (double)
- •
- $cx (integer)
- •
- $cy (integer)
$canvas->set_stipple_origin ($gc)¶
- •
- $gc (Gtk2::Gdk::GC)
$canvas->update_now¶
(cx, cy) = $canvas-> w2c ($wx, $wy)¶
- •
- $wx (double)
- •
- $wy (double)
$affine = $canvas-> w2c_affine¶
Fetch the affine transform that converts from world coordinates to canvas pixel
coordinates.
Note: This method was completely broken for all $Gnome2::Canvas::VERSION <
1.002.
(cx, cy) = $canvas-> w2c_d ($wx, $wy)¶
- •
- $wx (double)
- •
- $wy (double)
(worldx, worldy) = $canvas-> window_to_world ($winx, $winy)¶
- •
- $winx (double)
- •
- $winy (double)
(winx, winy) = $canvas-> world_to_window ($worldx, $worldy)¶
- •
- $worldx (double)
- •
- $worldy (double)
PROPERTIES¶
- 'aa' (boolean : default false : readable / writable / construct-only)
- The antialiasing mode of the canvas.
- 'focused-item' (Gnome2::Canvas::Item : default undef : readable /
writable)
SIGNALS¶
- draw-background (Gnome2::Canvas, Gtk2::Gdk::Drawable, integer,
integer, integer, integer)
- render-background (Gnome2::Canvas, gpointer)
ENUMS AND FLAGS¶
enum Gtk2::Gdk::RgbDither¶
- •
- 'none' / 'GDK_RGB_DITHER_NONE'
- •
- 'normal' / 'GDK_RGB_DITHER_NORMAL'
- •
- 'max' / 'GDK_RGB_DITHER_MAX'
SEE ALSO¶
Gnome2::Canvas::index(3pm) lists the generated Perl API reference PODs.
Frederico Mena Quintero's whitepaper on the GNOME Canvas:
http://developer.gnome.org/doc/whitepapers/canvas/canvas.html
The real GnomeCanvas is implemented in a C library; the Gnome2::Canvas module
allows a Perl developer to use the canvas like a normal gtk2-perl object. Like
the Gtk2 module on which it depends, Gnome2::Canvas follows the C API of
libgnomecanvas-2.0 as closely as possible while still being perlish. Thus, the
C API reference remains the canonical documentation; the Perl reference
documentation lists call signatures and argument types, and is meant to be
used in conjunction with the C API reference.
GNOME Canvas Library Reference Manual
http://developer.gnome.org/doc/API/2.0/libgnomecanvas/index.html
perl(1),
Glib(3pm),
Gtk2(3pm).
To discuss gtk2-perl, ask questions and flame/praise the authors, join
gtk-perl-list@gnome.org at lists.gnome.org.
AUTHOR¶
muppet <scott at asofyet dot org>, with patches from Torsten Schoenfeld
<kaffetisch at web dot de>.
The DESCRIPTION section of this page is adapted from the documentation of
libgnomecanvas.
COPYRIGHT AND LICENSE¶
Copyright 2003-2004 by the gtk2-perl team.
This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Library General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU Library General Public License for more
details.
You should have received a copy of the GNU Library General Public License along
with this library; if not, write to the Free Software Foundation, Inc., 59
Temple Place - Suite 330, Boston, MA 02111-1307 USA.