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
47 sophisticated, antialiased, alpha-compositing engine. This widget can
48 be used for flexible display of graphics and for creating interactive
49 user 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
60 scaling, 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
80 manually handling GDK events (such as drag and drop) which are
81 specified in window coordinates (the events processed by the canvas are
82 already 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
87 transform matrix for converting from world coordinates to canvas
88 coordinates call "$canvas->w2c_affine". "$canvas->window_to_world"
89 converts from window to world coordinates and
90 "$canvas->world_to_window" converts in the other direction. There are
91 no methods for converting between canvas and window coordinates, since
92 this is just a matter of subtracting the canvas scrolling offset. To
93 convert to/from item coordinates use the methods defined for
94 Gnome2::CanvasItem objects.
95 To set the canvas zoom factor (canvas pixels per world unit, the
97 scaling factor) call "$canvas->set_pixels_per_unit"; setting this to
98 1.0 will cause the two coordinate systems to correspond (e.g., [5, 6]
99 in pixel units would be [5.0, 6.0] in world units).
100 Defining the scrollable area of a canvas widget is done by calling
102 "$canvas->set_scroll_region" and to get the current region
103 "$canvas->get_scroll_region" can be used. If the window is larger than
104 the canvas scrolling region it can optionally be centered in the
105 window. Use "$canvas->set_center_scroll_region" to enable or disable
106 this behavior. To scroll to a particular canvas pixel coordinate use
107 "$canvas->scroll_to" (typically not used since scrollbars are usually
108 set up to handle the scrolling), and to get the current canvas pixel
109 scroll offset call "$canvas->get_scroll_offsets".
110
112 Glib::Object
113 +----Glib::InitiallyUnowned
114 +----Gtk2::Object
115 +----Gtk2::Widget
116 +----Gtk2::Container
117 +----Gtk2::Layout
118 +----Gnome2::Canvas
119
121 Glib::Object::_Unregistered::AtkImplementorIface
122 Gtk2::Buildable
123
125 widget = Gnome2::Canvas->new
126 Create a new empty canvas in non-antialiased mode.
127 widget = Gnome2::Canvas->new_aa
129 Create a new empty canvas in antialiased mode.
130 boolean = $canvas->aa
132 Returns true if $canvas was created in anti-aliased mode.
133 ($bx1, $by1, $bx2, $by2) = Gnome2::Canvas->get_butt_points ($x1, $y1, $x2,
135 $y2, $width, $project)
136 · $x1 (double)
137 · $y1 (double)
139 · $x2 (double)
141 · $y2 (double)
143 · $width (double)
145 · $project (integer)
147 (wx, wy) = $canvas->c2w ($cx, $cy)
149 · $cx (integer)
150 · $cy (integer)
152 boolean = $canvas->get_center_scroll_region
154 $canvas->set_center_scroll_region ($center_scroll_region)
155 · $center_scroll_region (boolean)
156 list = $canvas->get_color ($spec)
158 · $spec (string)
159 Returns an integer indicating the success of the color allocation and a
161 GdkColor.
162 unsigned = $canvas->get_color_pixel ($rgba)
164 · $rgba (integer)
165 rgbdither = $canvas->get_dither
167 $canvas->set_dither ($dither)
168 · $dither (Gtk2::Gdk::RgbDither)
169 item = $canvas->get_item_at ($x, $y)
171 · $x (double)
172 · $y (double)
174 ($mx1, $my1, $mx2, $my2) = Gnome2::Canvas->get_miter_points ($x1, $y1, $x2,
176 $y2, $x3, $y3, $width)
177 · $x1 (double)
178 · $y1 (double)
180 · $x2 (double)
182 · $y2 (double)
184 · $x3 (double)
186 · $y3 (double)
188 · $width (double)
190 double = $canvas->get_pixels_per_unit
192 Fetch $canvas' scale factor.
193 $canvas->set_pixels_per_unit ($n)
195 · $n (double)
196 Set the zooming factor of $canvas by specifying the number of screen
198 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
202 · $x (double)
204 · $y (double)
206 Return the distance from the point $x,$y to the polygon described by
208 the vertices in $poly_ref, or zero if the point is inside the polygon.
209 $canvas->request_redraw ($x1, $y1, $x2, $y2)
211 · $x1 (integer)
212 · $y1 (integer)
214 · $x2 (integer)
216 · $y2 (integer)
218 group = $canvas->root
220 (cx, cy) = $canvas->get_scroll_offsets
221 (x1, y1, x2, y2) = $canvas->get_scroll_region
222 $canvas->set_scroll_region ($x1, $y1, $x2, $y2)
223 · $x1 (double)
224 · $y1 (double)
226 · $x2 (double)
228 · $y2 (double)
230 $canvas->scroll_to ($cx, $cy)
232 · $cx (integer)
233 · $cy (integer)
235 $canvas->set_stipple_origin ($gc)
237 · $gc (Gtk2::Gdk::GC)
238 $canvas->update_now
240 (cx, cy) = $canvas->w2c ($wx, $wy)
241 · $wx (double)
242 · $wy (double)
244 $affine = $canvas->w2c_affine
246 Fetch the affine transform that converts from world coordinates to
247 canvas pixel coordinates.
248 Note: This method was completely broken for all
250 $Gnome2::Canvas::VERSION < 1.002.
251 (cx, cy) = $canvas->w2c_d ($wx, $wy)
253 · $wx (double)
254 · $wy (double)
256 (worldx, worldy) = $canvas->window_to_world ($winx, $winy)
258 · $winx (double)
259 · $winy (double)
261 (winx, winy) = $canvas->world_to_window ($worldx, $worldy)
263 · $worldx (double)
264 · $worldy (double)
266
268 'aa' (boolean : default false : readable / writable / construct-only)
269 The antialiasing mode of the canvas.
270 'focused-item' (Gnome2::Canvas::Item : default undef : readable /
272 writable)
273
275 draw-background (Gnome2::Canvas, Gtk2::Gdk::Drawable, integer, integer,
276 integer, integer)
277 render-background (Gnome2::Canvas, gpointer)
278
280 enum Gtk2::Gdk::RgbDither
281 · 'none' / 'GDK_RGB_DITHER_NONE'
282 · 'normal' / 'GDK_RGB_DITHER_NORMAL'
284 · 'max' / 'GDK_RGB_DITHER_MAX'
286
288 Gnome2::Canvas::index(3pm) lists the generated Perl API reference PODs.
289 Frederico Mena Quintero's whitepaper on the GNOME Canvas:
291 http://developer.gnome.org/doc/whitepapers/canvas/canvas.html
292 The real GnomeCanvas is implemented in a C library; the Gnome2::Canvas
294 module allows a Perl developer to use the canvas like a normal
295 gtk2-perl object. Like the Gtk2 module on which it depends,
296 Gnome2::Canvas follows the C API of libgnomecanvas-2.0 as closely as
297 possible while still being perlish. Thus, the C API reference remains
298 the canonical documentation; the Perl reference documentation lists
299 call signatures and argument types, and is meant to be used in
300 conjunction with the C API reference.
301 GNOME Canvas Library Reference Manual
303 http://developer.gnome.org/doc/API/2.0/libgnomecanvas/index.html
304 perl(1), Glib(3pm), Gtk2(3pm).
306 To discuss gtk2-perl, ask questions and flame/praise the authors, join
308 gtk-perl-list@gnome.org at lists.gnome.org.
309
311 muppet <scott at asofyet dot org>, with patches from Torsten Schoenfeld
312 <kaffetisch at web dot de>.
313 The DESCRIPTION section of this page is adapted from the documentation
315 of libgnomecanvas.
316
318 Copyright 2003-2004 by the gtk2-perl team.
319 This library is free software; you can redistribute it and/or modify it
321 under the terms of the GNU Library General Public License as published
322 by the Free Software Foundation; either version 2 of the License, or
323 (at your option) any later version.
324 This library is distributed in the hope that it will be useful, but
326 WITHOUT ANY WARRANTY; without even the implied warranty of
327 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
328 Library General Public License for more details.
329 You should have received a copy of the GNU Library General Public
331 License along with this library; if not, write to the Free Software
332 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
333 USA.
334perl v5.28.1 2019-02-02 Gnome2::Canvas(3)