1Gnome2::Canvas(3)     User Contributed Perl Documentation    Gnome2::Canvas(3)
2
3
4

NAME

6       Gnome2::Canvas -  A structured graphics canvas
7

SYNOPSIS

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
21         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
40         Gtk2->main;
41

DESCRIPTION

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
51       To create a new Gnome2::Canvas widget call "Gnome2::Canvas->new" or
52       "Gnome2::Canvas->new_aa" for an anti-aliased mode canvas.
53
54       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
62       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
66       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
84       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
96       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
101       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

HIERARCHY

112         Glib::Object
113         +----Glib::InitiallyUnowned
114              +----Gtk2::Object
115                   +----Gtk2::Widget
116                        +----Gtk2::Container
117                             +----Gtk2::Layout
118                                  +----Gnome2::Canvas
119

INTERFACES

121         Glib::Object::_Unregistered::AtkImplementorIface
122         Gtk2::Buildable
123

METHODS

125   widget = Gnome2::Canvas->new
126       Create a new empty canvas in non-antialiased mode.
127
128   widget = Gnome2::Canvas->new_aa
129       Create a new empty canvas in antialiased mode.
130
131   boolean = $canvas->aa
132       Returns true if $canvas was created in anti-aliased mode.
133
134   ($bx1, $by1, $bx2, $by2) = Gnome2::Canvas->get_butt_points ($x1, $y1, $x2,
135       $y2, $width, $project)
136       ·   $x1 (double)
137
138       ·   $y1 (double)
139
140       ·   $x2 (double)
141
142       ·   $y2 (double)
143
144       ·   $width (double)
145
146       ·   $project (integer)
147
148   (wx, wy) = $canvas->c2w ($cx, $cy)
149       ·   $cx (integer)
150
151       ·   $cy (integer)
152
153   boolean = $canvas->get_center_scroll_region
154   $canvas->set_center_scroll_region ($center_scroll_region)
155       ·   $center_scroll_region (boolean)
156
157   list = $canvas->get_color ($spec)
158       ·   $spec (string)
159
160       Returns an integer indicating the success of the color allocation and a
161       GdkColor.
162
163   unsigned = $canvas->get_color_pixel ($rgba)
164       ·   $rgba (integer)
165
166   rgbdither = $canvas->get_dither
167   $canvas->set_dither ($dither)
168       ·   $dither (Gtk2::Gdk::RgbDither)
169
170   item = $canvas->get_item_at ($x, $y)
171       ·   $x (double)
172
173       ·   $y (double)
174
175   ($mx1, $my1, $mx2, $my2) = Gnome2::Canvas->get_miter_points ($x1, $y1, $x2,
176       $y2, $x3, $y3, $width)
177       ·   $x1 (double)
178
179       ·   $y1 (double)
180
181       ·   $x2 (double)
182
183       ·   $y2 (double)
184
185       ·   $x3 (double)
186
187       ·   $y3 (double)
188
189       ·   $width (double)
190
191   double = $canvas->get_pixels_per_unit
192       Fetch $canvas' scale factor.
193
194   $canvas->set_pixels_per_unit ($n)
195       ·   $n (double)
196
197       Set the zooming factor of $canvas by specifying the number of screen
198       pixels that correspond to one canvas unit.
199
200   double = Gnome2::Canvas->polygon_to_point ($poly_ref, $x, $y)
201       ·   $poly_ref (arrayref) coordinate pairs that make up the polygon
202
203       ·   $x (double)
204
205       ·   $y (double)
206
207       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
210   $canvas->request_redraw ($x1, $y1, $x2, $y2)
211       ·   $x1 (integer)
212
213       ·   $y1 (integer)
214
215       ·   $x2 (integer)
216
217       ·   $y2 (integer)
218
219   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
225       ·   $y1 (double)
226
227       ·   $x2 (double)
228
229       ·   $y2 (double)
230
231   $canvas->scroll_to ($cx, $cy)
232       ·   $cx (integer)
233
234       ·   $cy (integer)
235
236   $canvas->set_stipple_origin ($gc)
237       ·   $gc (Gtk2::Gdk::GC)
238
239   $canvas->update_now
240   (cx, cy) = $canvas->w2c ($wx, $wy)
241       ·   $wx (double)
242
243       ·   $wy (double)
244
245   $affine = $canvas->w2c_affine
246       Fetch the affine transform that converts from world coordinates to
247       canvas pixel coordinates.
248
249       Note: This method was completely broken for all
250       $Gnome2::Canvas::VERSION < 1.002.
251
252   (cx, cy) = $canvas->w2c_d ($wx, $wy)
253       ·   $wx (double)
254
255       ·   $wy (double)
256
257   (worldx, worldy) = $canvas->window_to_world ($winx, $winy)
258       ·   $winx (double)
259
260       ·   $winy (double)
261
262   (winx, winy) = $canvas->world_to_window ($worldx, $worldy)
263       ·   $worldx (double)
264
265       ·   $worldy (double)
266

PROPERTIES

268       'aa' (boolean : default false : readable / writable / construct-only)
269           The antialiasing mode of the canvas.
270
271       'focused-item' (Gnome2::Canvas::Item : default undef : readable /
272       writable)
273

SIGNALS

275       draw-background (Gnome2::Canvas, Gtk2::Gdk::Drawable, integer, integer,
276       integer, integer)
277       render-background (Gnome2::Canvas, gpointer)
278

ENUMS AND FLAGS

280   enum Gtk2::Gdk::RgbDither
281       ·   'none' / 'GDK_RGB_DITHER_NONE'
282
283       ·   'normal' / 'GDK_RGB_DITHER_NORMAL'
284
285       ·   'max' / 'GDK_RGB_DITHER_MAX'
286

SEE ALSO

288       Gnome2::Canvas::index(3pm) lists the generated Perl API reference PODs.
289
290       Frederico Mena Quintero's whitepaper on the GNOME Canvas:
291       http://developer.gnome.org/doc/whitepapers/canvas/canvas.html
292
293       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
302       GNOME Canvas Library Reference Manual
303       http://developer.gnome.org/doc/API/2.0/libgnomecanvas/index.html
304
305       perl(1), Glib(3pm), Gtk2(3pm).
306
307       To discuss gtk2-perl, ask questions and flame/praise the authors, join
308       gtk-perl-list@gnome.org at lists.gnome.org.
309

AUTHOR

311       muppet <scott at asofyet dot org>, with patches from Torsten Schoenfeld
312       <kaffetisch at web dot de>.
313
314       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
320       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
325       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
330       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.
334
335
336
337perl v5.30.0                      2019-07-26                 Gnome2::Canvas(3)
Impressum