1Gnome2::Canvas(3) User Contributed Perl Documentation Gnome2::Canvas(3)
2
6 Gnome2::Canvas - A structured graphics canvas
7
9 use strict;
10 use Gtk2 -init;
11 use Gnome2::Canvas;
12 my $window = Gtk2::Window->new;
13 my $scroller = Gtk2::ScrolledWindow->new;
14 my $canvas = Gnome2::Canvas->new;
15 $scroller->add ($canvas);
16 $window->add ($scroller);
17 $window->set_default_size (150, 150);
18 $canvas->set_scroll_region (0, 0, 200, 200);
19 $window->show_all;
20 my $root = $canvas->root;
22 Gnome2::Canvas::Item->new ($root, 'Gnome2::Canvas::Text',
23 x => 20,
24 y => 15,
25 fill_color => 'black',
26 font => 'Sans 14',
27 anchor => 'GTK_ANCHOR_NW',
28 text => 'Hello, World!');
29 my $box = Gnome2::Canvas::Item->new ($root, 'Gnome2::Canvas::Rect',
30 x1 => 10, y1 => 5,
31 x2 => 150, y2 => 135,
32 fill_color => 'red',
33 outline_color => 'black');
34 $box->lower_to_bottom;
35 $box->signal_connect (event => sub {
36 my ($item, $event) = @_;
37 warn "event ".$event->type."\n";
38 });
39 Gtk2->main;
41
43 The Gnome Canvas is an engine for structured graphics that offers a
44 rich imaging model, high-performance rendering, and a powerful, high
45 level API. It offers a choice of two rendering back-ends, one based on
46 GDK for extremely fast display, and another based on Libart, a sophis‐
47 ticated, antialiased, alpha-compositing engine. This widget can be
48 used for flexible display of graphics and for creating interactive user
49 interface elements.
50 To create a new Gnome2::Canvas widget call "Gnome2::Canvas->new" or
52 "Gnome2::Canvas->new_aa" for an anti-aliased mode canvas.
53 A Gnome2::Canvas contains one or more Gnome2::CanvasItem objects. Items
55 consist of graphing elements like lines, ellipses, polygons, images,
56 text, and curves. These items are organized using Gnome2::CanvasGroup
57 objects, which are themselves derived from Gnome2::CanvasItem. Since a
58 group is an item it can be contained within other groups, forming a
59 tree of canvas items. Certain operations, like translating and scal‐
60 ing, can be performed on all items in a group.
61 There is a special root group created by a Gnome2::Canvas. This is the
63 top level group under which all items in a canvas are contained. The
64 root group is available as "$canvas->root".
65 There are several different coordinate systems used by Gnome2::Canvas
67 widgets. The primary system is a logical, abstract coordinate space
68 called world coordinates. World coordinates are expressed as unbounded
69 double floating point numbers. When it comes to rendering to a screen
70 the canvas pixel coordinate system (also referred to as just canvas
71 coordinates) is used. This system uses integers to specify screen
72 pixel positions. A user defined scaling factor and offset are used to
73 convert between world coordinates and canvas coordinates. Each item in
74 a canvas has its own coordinate system called item coordinates. This
75 system is specified in world coordinates but they are relative to an
76 item (0.0, 0.0 would be the top left corner of the item). The final
77 coordinate system of interest is window coordinates. These are like
78 canvas coordinates but are offsets from within a window a canvas is
79 displayed in. This last system is rarely used, but is useful when man‐
80 ually handling GDK events (such as drag and drop) which are specified
81 in window coordinates (the events processed by the canvas are already
82 converted for you).
83 Along with different coordinate systems come methods to convert between
85 them. "$canvas->w2c" converts world to canvas pixel coordinates and
86 "canvas->c2w" converts from canvas to world. To get the affine trans‐
87 form matrix for converting from world coordinates to canvas coordinates
88 call "$canvas->w2c_affine". "$canvas->window_to_world" converts from
89 window to world coordinates and "$canvas->world_to_window" converts in
90 the other direction. There are no methods for converting between can‐
91 vas and window coordinates, since this is just a matter of subtracting
92 the canvas scrolling offset. To convert to/from item coordinates use
93 the methods defined for Gnome2::CanvasItem objects.
94 To set the canvas zoom factor (canvas pixels per world unit, the scal‐
96 ing factor) call "$canvas->set_pixels_per_unit"; setting this to 1.0
97 will cause the two coordinate systems to correspond (e.g., [5, 6] in
98 pixel units would be [5.0, 6.0] in world units).
99 Defining the scrollable area of a canvas widget is done by calling
101 "$canvas->set_scroll_region" and to get the current region "$can‐
102 vas->get_scroll_region" can be used. If the window is larger than the
103 canvas scrolling region it can optionally be centered in the window.
104 Use "$canvas->set_center_scroll_region" to enable or disable this
105 behavior. To scroll to a particular canvas pixel coordinate use "$can‐
106 vas->scroll_to" (typically not used since scrollbars are usually set up
107 to handle the scrolling), and to get the current canvas pixel scroll
108 offset call "$canvas->get_scroll_offsets".
109
111 Glib::Object
112 +----Glib::InitiallyUnowned
113 +----Gtk2::Object
114 +----Gtk2::Widget
115 +----Gtk2::Container
116 +----Gtk2::Layout
117 +----Gnome2::Canvas
118
120 Glib::Object::_Unregistered::AtkImplementorIface
121
123 widget = Gnome2::Canvas->new
124 Create a new empty canvas in non-antialiased mode.
126 widget = Gnome2::Canvas->new_aa
128 Create a new empty canvas in antialiased mode.
130 boolean = $canvas->aa
132 Returns true if $canvas was created in anti-aliased mode.
134 ($bx1, $by1, $bx2, $by2) = Gnome2::Canvas->get_butt_points ($x1, $y1,
136 $x2, $y2, $width, $project)
137 * $x1 (double)
139 * $y1 (double)
140 * $x2 (double)
141 * $y2 (double)
142 * $width (double)
143 * $project (integer)
144 (wx, wy) = $canvas->c2w ($cx, $cy)
146 * $cx (integer)
148 * $cy (integer)
149 boolean = $canvas->get_center_scroll_region
151 $canvas->set_center_scroll_region ($center_scroll_region)
153 * $center_scroll_region (boolean)
155 list = $canvas->get_color ($spec)
157 * $spec (string)
159 Returns an integer indicating the success of the color allocation
161 and a GdkColor.
162 unsigned = $canvas->get_color_pixel ($rgba)
164 * $rgba (integer)
166 rgbdither = $canvas->get_dither
168 $canvas->set_dither ($dither)
170 * $dither (Gtk2::Gdk::RgbDither)
172 item = $canvas->get_item_at ($x, $y)
174 * $x (double)
176 * $y (double)
177 ($mx1, $my1, $mx2, $my2) = Gnome2::Canvas->get_miter_points ($x1, $y1,
179 $x2, $y2, $x3, $y3, $width)
180 * $x1 (double)
182 * $y1 (double)
183 * $x2 (double)
184 * $y2 (double)
185 * $x3 (double)
186 * $y3 (double)
187 * $width (double)
188 double = $canvas->get_pixels_per_unit
190 Fetch $canvas' scale factor.
192 $canvas->set_pixels_per_unit ($n)
194 * $n (double)
196 Set the zooming factor of $canvas by specifying the number of
198 screen pixels that correspond to one canvas unit.
199 double = Gnome2::Canvas->polygon_to_point ($poly_ref, $x, $y)
201 * $poly_ref (arrayref) coordinate pairs that make up the polygon
203 * $x (double)
204 * $y (double)
205 Return the distance from the point $x,$y to the polygon described
207 by the vertices in $poly_ref, or zero if the point is inside the
208 polygon.
209 $canvas->request_redraw ($x1, $y1, $x2, $y2)
211 * $x1 (integer)
213 * $y1 (integer)
214 * $x2 (integer)
215 * $y2 (integer)
216 group = $canvas->root
218 (cx, cy) = $canvas->get_scroll_offsets
220 (x1, y1, x2, y2) = $canvas->get_scroll_region
222 $canvas->set_scroll_region ($x1, $y1, $x2, $y2)
224 * $x1 (double)
226 * $y1 (double)
227 * $x2 (double)
228 * $y2 (double)
229 $canvas->scroll_to ($cx, $cy)
231 * $cx (integer)
233 * $cy (integer)
234 $canvas->set_stipple_origin ($gc)
236 * $gc (Gtk2::Gdk::GC)
238 $canvas->update_now
240 (cx, cy) = $canvas->w2c ($wx, $wy)
242 * $wx (double)
244 * $wy (double)
245 $affine = $canvas->w2c_affine
247 Fetch the affine transform that converts from world coordinates to
249 canvas pixel coordinates.
250 Note: This method was completely broken for all $Gnome2::Can‐
252 vas::VERSION < 1.002.
253 (cx, cy) = $canvas->w2c_d ($wx, $wy)
255 * $wx (double)
257 * $wy (double)
258 (worldx, worldy) = $canvas->window_to_world ($winx, $winy)
260 * $winx (double)
262 * $winy (double)
263 (winx, winy) = $canvas->world_to_window ($worldx, $worldy)
265 * $worldx (double)
267 * $worldy (double)
268
270 'aa' (boolean : readable / writable / construct-only)
271 The antialiasing mode of the canvas.
272
274 draw-background (Gnome2::Canvas, Gtk2::Gdk::Drawable, integer, integer,
275 integer, integer)
276 render-background (Gnome2::Canvas, gpointer)
277
279 enum Gtk2::Gdk::RgbDither
280 * 'none' / 'GDK_RGB_DITHER_NONE'
282 * 'normal' / 'GDK_RGB_DITHER_NORMAL'
283 * 'max' / 'GDK_RGB_DITHER_MAX'
284
286 Gnome2::Canvas::index(3pm) lists the generated Perl API reference PODs.
287 Frederico Mena Quintero's whitepaper on the GNOME Canvas: http://devel‐
289 oper.gnome.org/doc/whitepapers/canvas/canvas.html
290 The real GnomeCanvas is implemented in a C library; the Gnome2::Canvas
292 module allows a Perl developer to use the canvas like a normal
293 gtk2-perl object. Like the Gtk2 module on which it depends,
294 Gnome2::Canvas follows the C API of libgnomecanvas-2.0 as closely as
295 possible while still being perlish. Thus, the C API reference remains
296 the canonical documentation; the Perl reference documentation lists
297 call signatures and argument types, and is meant to be used in conjunc‐
298 tion with the C API reference.
299 GNOME Canvas Library Reference Manual http://devel‐
301 oper.gnome.org/doc/API/2.0/libgnomecanvas/index.html
302 perl(1), Glib(3pm), Gtk2(3pm).
304 To discuss gtk2-perl, ask questions and flame/praise the authors, join
306 gtk-perl-list@gnome.org at lists.gnome.org.
307
309 muppet <scott at asofyet dot org>, with patches from Torsten Schoenfeld
310 <kaffetisch at web dot de>.
311 The DESCRIPTION section of this page is adapted from the documentation
313 of libgnomecanvas.
314
316 Copyright 2003-2004 by the gtk2-perl team.
317 This library is free software; you can redistribute it and/or modify it
319 under the terms of the GNU Library General Public License as published
320 by the Free Software Foundation; either version 2 of the License, or
321 (at your option) any later version.
322 This library is distributed in the hope that it will be useful, but
324 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
325 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
326 General Public License for more details.
327 You should have received a copy of the GNU Library General Public
329 License along with this library; if not, write to the Free Software
330 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
331 USA.
332perl v5.8.8 2006-10-04 Gnome2::Canvas(3)