[perl-gnome2-canvas/doc-reorg] Moved main POD docs out of *.xs files and in to Canvas.pm
- From: Brian Manning <bmanning src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [perl-gnome2-canvas/doc-reorg] Moved main POD docs out of *.xs files and in to Canvas.pm
- Date: Thu, 29 Oct 2020 02:40:11 +0000 (UTC)
commit 5a4449829cf1b88c300f022229bdbf867a8644fe
Author: Brian Manning <bmanning src gnome org>
Date: Wed Oct 28 19:37:48 2020 -0700
Moved main POD docs out of *.xs files and in to Canvas.pm
- Patch from Torsten applied that moves a majority of the docs out of
the *.xs files, where they were dynamically generated into POD
files, and into the Canvas.pm file, where they should be available
for static viewing and parsing by CPAN search engines
Canvas.pm | 168 +++++++++++++++++++++++++++++++++++++++++++++++-
xs/GnomeCanvas.xs | 174 +-------------------------------------------------
xs/GnomeCanvasUtil.xs | 3 +
3 files changed, 169 insertions(+), 176 deletions(-)
---
diff --git a/Canvas.pm b/Canvas.pm
index 1034936..42e15b4 100644
--- a/Canvas.pm
+++ b/Canvas.pm
@@ -30,8 +30,170 @@ bootstrap Gnome2::Canvas $VERSION;
1;
__END__
-This is not the POD you're looking for.
+=head1 NAME
-The documentation for this module is generated from the XS source, and
-is stored in separate .pod files.
+Gnome2::Canvas - A structured graphics canvas
+=head1 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;
+
+=head1 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 C<< Gnome2::Canvas->new >> or
+C<< 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 C<< $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. C<< $canvas->w2c >> converts world to canvas pixel
+coordinates and C<< canvas->c2w >> converts from canvas to
+world. To get the affine transform matrix for converting
+from world coordinates to canvas coordinates call C<< $canvas->w2c_affine >>.
+C<< $canvas->window_to_world >> converts from window to world
+coordinates and C<< $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 C<< $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
+C<< $canvas->set_scroll_region >> and to get the current region
+C<< $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 C<< $canvas->set_center_scroll_region >> to enable or
+disable this behavior. To scroll to a particular canvas pixel coordinate
+use C<< $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 C<< $canvas->get_scroll_offsets >>.
+
+=head1 SEE ALSO
+
+Gnome2::Canvas::index(3pm) lists the generated Perl API reference PODs.
+
+Gnome2::Canvas::main(3pm), in particular, lists the API in the Gnome2::Canvas
+package.
+
+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.
+
+=cut
+
+=for position COPYRIGHT
+
+=head1 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.
+
+=head1 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.
+
+=cut
diff --git a/xs/GnomeCanvas.xs b/xs/GnomeCanvas.xs
index 2a00c63..8fc078a 100644
--- a/xs/GnomeCanvas.xs
+++ b/xs/GnomeCanvas.xs
@@ -110,181 +110,9 @@ BOOT:
# and now back to Gnome2::Canvas
#
-=for object Gnome2::Canvas A structured graphics canvas
-
-=cut
-
-=for position SYNOPSIS
-
-=head1 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;
-
+=for object Gnome2::Canvas::main - A structured graphics canvas
=cut
-=for position DESCRIPTION
-
-=head1 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 C<< Gnome2::Canvas->new >> or
-C<< 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 C<< $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. C<< $canvas->w2c >> converts world to canvas pixel
-coordinates and C<< canvas->c2w >> converts from canvas to
-world. To get the affine transform matrix for converting
-from world coordinates to canvas coordinates call C<< $canvas->w2c_affine >>.
-C<< $canvas->window_to_world >> converts from window to world
-coordinates and C<< $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 C<< $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
-C<< $canvas->set_scroll_region >> and to get the current region
-C<< $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 C<< $canvas->set_center_scroll_region >> to enable or
-disable this behavior. To scroll to a particular canvas pixel coordinate
-use C<< $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 C<< $canvas->get_scroll_offsets >>.
-
-=cut
-
-=for position SEE_ALSO
-
-=head1 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.
-
-=cut
-
-=for position COPYRIGHT
-
-=head1 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.
-
-=head1 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, see
-L<https://www.gnu.org/licenses/>.
-
-=cut
-
-
=for apidoc new_aa
Create a new empty canvas in antialiased mode.
=cut
diff --git a/xs/GnomeCanvasUtil.xs b/xs/GnomeCanvasUtil.xs
index 9a82121..d49e8c1 100644
--- a/xs/GnomeCanvasUtil.xs
+++ b/xs/GnomeCanvasUtil.xs
@@ -103,6 +103,9 @@ BOOT:
MODULE = Gnome2::Canvas::Util PACKAGE = Gnome2::Canvas PREFIX = gnome_canvas_
+=for object Gnome2::Canvas::main
+=cut
+
## int gnome_canvas_get_miter_points (double x1, double y1, double x2, double y2, double x3, double y3,
double width, double *mx1, double *my1, double *mx2, double *my2)
=for apidoc
=for signature ($mx1, $my1, $mx2, $my2) = Gnome2::Canvas->get_miter_points ($x1, $y1, $x2, $y2, $x3, $y3,
$width)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]