GNOME.org
 

[perl-Gtk3] Add documentation for all overrides and customizations

commit 0ac21a171070c1ebd0016eff165125d7161dc588
Author: Torsten Schönfeld <kaffeetisch gmx de>
Date:   Thu Sep 10 17:41:33 2015 +0200

    Add documentation for all overrides and customizations

 lib/Gtk3.pm |  657 +++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 577 insertions(+), 80 deletions(-)
---
diff --git a/lib/Gtk3.pm b/lib/Gtk3.pm
index 2be4a6d..023c925 100644
--- a/lib/Gtk3.pm
+++ b/lib/Gtk3.pm
@@ -1,5 +1,46 @@
 package Gtk3;
 
+=encoding utf8
+
+=head1 NAME
+
+Gtk3 - Perl interface to the 3.x series of the gtk+ toolkit
+
+=head1 SYNOPSIS
+
+  use Gtk3 -init;
+  my $window = Gtk3::Window->new ('toplevel');
+  my $button = Gtk3::Button->new ('Quit');
+  $button->signal_connect (clicked => sub { Gtk3::main_quit });
+  $window->add ($button);
+  $window->show_all;
+  Gtk3::main;
+
+=head1 ABSTRACT
+
+Perl bindings to the 3.x series of the gtk+ toolkit.  This module allows you to
+write graphical user interfaces in a Perlish and object-oriented way, freeing
+you from the casting and memory management in C, yet remaining very close in
+spirit to original API.
+
+=head1 DESCRIPTION
+
+The C<Gtk3> module allows a Perl developer to use the gtk+ graphical user
+interface library.  Find out more about gtk+ at L<http://www.gtk.org>.
+
+The gtk+ reference manual is also a handy companion when writing C<Gtk3>
+programs in Perl: L<http://developer.gnome.org/gtk3/stable/>.  The Perl
+bindings follow the C API very closely, and the C reference documentation
+should be considered the canonical source.  The principles underlying the
+mapping from C to Perl are explained in the documentation of
+L<Glib::Object::Introspection>, on which C<Gtk3> is based.
+
+L<Glib::Object::Introspection> also comes with the C<perli11ndoc> program which
+displays the API reference documentation of all installed libraries organized
+in accordance with these principles.
+
+=cut
+
 use strict;
 use warnings;
 use Carp qw/croak/;
@@ -9,6 +50,28 @@ use Exporter;
 
 our @ISA = qw(Exporter);
 
+=head2 Wrapped libraries
+
+C<Gtk3> automatically sets up the following correspondence between C libraries
+and Perl packages:
+
+  Library       | Package
+  --------------+----------
+  Gtk-3.0       | Gtk3
+  Gdk-3.0       | Gtk3::Gdk
+  GdkPixbuf-2.0 | Gtk3::Gdk
+  Pango-1.0     | Pango
+
+=cut
+
+=head2 Import arguments
+
+When importing C<Gtk3>, you can pass C<-init> as in C<< use Gtk3 -init; >> to
+have C<Gtk3::init> automatically called.  You can also pass a version number to
+require a certain version of C<Gtk3>.
+
+=cut
+
 my $_GTK_BASENAME = 'Gtk';
 my $_GTK_VERSION = '3.0';
 my $_GTK_PACKAGE = 'Gtk3';
@@ -25,7 +88,50 @@ my $_PANGO_BASENAME = 'Pango';
 my $_PANGO_VERSION = '1.0';
 my $_PANGO_PACKAGE = 'Pango';
 
-# - gtk customization ------------------------------------------------------- #
+=head2 Customizations and overrides
+
+In order to make things more Perlish or to make porting from C<Gtk2> to C<Gtk3>
+easier, C<Gtk3> customizes the API generated by L<Glib::Object::Introspection>
+in a few spots:
+
+=over
+
+=cut
+
+# - Customizations ---------------------------------------------------------- #
+
+=item * The array ref normally returned by the following functions is flattened
+into a list:
+
+=over
+
+=item Gtk3::ActionGroup::list_actions
+
+=item Gtk3::Builder::get_objects
+
+=item Gtk3::CellLayout::get_cells
+
+=item Gtk3::Container::get_children
+
+=item Gtk3::SizeGroup::get_widgets
+
+=item Gtk3::TreePath::get_indices
+
+=item Gtk3::TreeView::get_columns
+
+=item Gtk3::UIManager::get_action_groups
+
+=item Gtk3::UIManager::get_toplevels
+
+=item Gtk3::Window::list_toplevels
+
+=item Gtk3::stock_list_ids
+
+=item Gtk3::Gdk::Pixbuf::get_formats
+
+=back
+
+=cut
 
 my @_GTK_FLATTEN_ARRAY_REF_RETURN_FOR = qw/
   Gtk3::ActionGroup::list_actions
@@ -40,6 +146,77 @@ my @_GTK_FLATTEN_ARRAY_REF_RETURN_FOR = qw/
   Gtk3::Window::list_toplevels
   Gtk3::stock_list_ids
 /;
+
+my @_GDK_PIXBUF_FLATTEN_ARRAY_REF_RETURN_FOR = qw/
+  Gtk3::Gdk::Pixbuf::get_formats
+/;
+
+=item * The following functions normally return a boolean and additional out
+arguments, where the boolean indicates whether the out arguments are valid.
+They are altered such that when the boolean is true, only the additional out
+arguments are returned, and when the boolean is false, an empty list is
+returned.
+
+=over
+
+=item Gtk3::TextBuffer::get_selection_bounds
+
+=item Gtk3::TreeModel::get_iter
+
+=item Gtk3::TreeModel::get_iter_first
+
+=item Gtk3::TreeModel::get_iter_from_string
+
+=item Gtk3::TreeModel::iter_children
+
+=item Gtk3::TreeModel::iter_nth_child
+
+=item Gtk3::TreeModel::iter_parent
+
+=item Gtk3::TreeModelFilter::convert_child_iter_to_iter
+
+=item Gtk3::TreeModelSort::convert_child_iter_to_iter
+
+=item Gtk3::TreeSelection::get_selected
+
+=item Gtk3::TreeView::get_dest_row_at_pos
+
+=item Gtk3::TreeView::get_path_at_pos
+
+=item Gtk3::TreeView::get_tooltip_context
+
+=item Gtk3::TreeView::get_visible_range
+
+=item Gtk3::TreeViewColumn::cell_get_position
+
+=item Gtk3::stock_lookup
+
+=item Gtk3::Gdk::Event::get_axis
+
+=item Gtk3::Gdk::Event::get_button
+
+=item Gtk3::Gdk::Event::get_click_count
+
+=item Gtk3::Gdk::Event::get_coords
+
+=item Gtk3::Gdk::Event::get_keycode
+
+=item Gtk3::Gdk::Event::get_keyval
+
+=item Gtk3::Gdk::Event::get_scroll_direction
+
+=item Gtk3::Gdk::Event::get_scroll_deltas
+
+=item Gtk3::Gdk::Event::get_state
+
+=item Gtk3::Gdk::Event::get_root_coords
+
+=item Gtk3::Gdk::Window::get_origin
+
+=back
+
+=cut
+
 my @_GTK_HANDLE_SENTINEL_BOOLEAN_FOR = qw/
   Gtk3::TextBuffer::get_selection_bounds
   Gtk3::TreeModel::get_iter
@@ -58,12 +235,43 @@ my @_GTK_HANDLE_SENTINEL_BOOLEAN_FOR = qw/
   Gtk3::TreeViewColumn::cell_get_position
   Gtk3::stock_lookup
 /;
+
+my @_GDK_HANDLE_SENTINEL_BOOLEAN_FOR = qw/
+  Gtk3::Gdk::Event::get_axis
+  Gtk3::Gdk::Event::get_button
+  Gtk3::Gdk::Event::get_click_count
+  Gtk3::Gdk::Event::get_coords
+  Gtk3::Gdk::Event::get_keycode
+  Gtk3::Gdk::Event::get_keyval
+  Gtk3::Gdk::Event::get_scroll_direction
+  Gtk3::Gdk::Event::get_scroll_deltas
+  Gtk3::Gdk::Event::get_state
+  Gtk3::Gdk::Event::get_root_coords
+  Gtk3::Gdk::Window::get_origin
+/;
+
 my @_GTK_USE_GENERIC_SIGNAL_MARSHALLER_FOR = (
   ['Gtk3::Editable', 'insert-text'],
   ['Gtk3::Dialog',   'response',    \&Gtk3::Dialog::_gtk3_perl_response_converter],
   ['Gtk3::InfoBar',  'response',    \&Gtk3::Dialog::_gtk3_perl_response_converter],
 );
 
+=item * Values of type Gtk3::ResponseType are converted to and from nick names
+if possible, while still allowing raw IDs, in the following places:
+
+=over
+
+=item - For Gtk3::Dialog and Gtk3::InfoBar: the signal C<response> as well as
+the methods C<add_action_widget>, C<add_button>, C<add_buttons>, C<response>,
+C<set_default_response> and C<set_response_sensitive>.
+
+=item - For Gtk3::Dialog: the methods C<get_response_for_widget>,
+C<get_widget_for_response>, C<run> and C<set_alternative_button_order>.
+
+=back
+
+=cut
+
 # GtkResponseType: id <-> nick
 my $_GTK_RESPONSE_ID_TO_NICK = sub {
   my ($id) = @_;
@@ -92,6 +300,22 @@ sub Gtk3::Dialog::_gtk3_perl_response_converter {
   return ($dialog, $_GTK_RESPONSE_ID_TO_NICK->($id));
 }
 
+=item * Values of type Gtk3::IconSize are converted to and from nick names if
+possible, while still allowing raw IDs, in the following places:
+
+=over
+
+=item - Gtk3::Image: the constructors new_from_stock, new_from_icon_set,
+new_from_icon_name and new_from_gicon, the getters get_stock, get_icon_set,
+get_icon_name and get_gicon and the setters set_from_stock, set_from_icon_set,
+set_from_icon_name, set_from_gicon.
+
+=item - Gtk3::Widget: the method render_icon.
+
+=back
+
+=cut
+
 # GtkIconSize: id <-> nick
 my $_GTK_ICON_SIZE_ID_TO_NICK = sub {
   my ($id) = @_;
@@ -122,20 +346,34 @@ my $_GTK_ICON_SIZE_NICK_TO_ID = sub {
   return $nick;
 };
 
-# - gdk customization ------------------------------------------------------- #
+=item * The constants C<Gtk3::EVENT_PROPAGATE> and C<Gtk3::EVENT_STOP> can be
+used in handlers for event signals like C<key-press-event> to indicate whether
+or not the event should continue propagating through the widget hierarchy.
+
+=cut
+
+# Names "STOP" and "PROPAGATE" here are per the GtkWidget event signal
+# descriptions.  In some other flavours of signals the jargon is "handled"
+# instead of "stop".  "Handled" matches g_signal_accumulator_true_handled(),
+# though that function doesn't rate a mention in the Gtk docs.  There's
+# nothing fixed in the idea of "true means cease emission" (whether it's
+# called "stop" or "handled").  You can just as easily have false for cease
+# (the way the underlying GSignalAccumulator func in fact operates).  The
+# upshot being don't want to attempt to be too universal with the names
+# here; "EVENT" is meant to hint at the context or signal flavour they're
+# for use with.
+sub Gtk3::EVENT_PROPAGATE() { !1 };
+sub Gtk3::EVENT_STOP() { 1 };
+
+=item * The records corresponding to the various Gtk3::Gdk::Event types, like
+C<expose> or C<key-release>, are represented as objects blessed into specific
+Perl packages, like C<Gtk3::Gdk::EventExpose> or C<Gtk3::Gdk::EventKey>, that
+all inherit from C<Gtk3::Gdk::Event>.  This allows you to seemlessly access
+type-specific fields as well as common fields, as in C<< $event->window >> or
+C<< $event->keyval >>.
+
+=cut
 
-my @_GDK_HANDLE_SENTINEL_BOOLEAN_FOR = qw/
-  Gtk3::Gdk::Event::get_axis
-  Gtk3::Gdk::Event::get_button
-  Gtk3::Gdk::Event::get_click_count
-  Gtk3::Gdk::Event::get_coords
-  Gtk3::Gdk::Event::get_keycode
-  Gtk3::Gdk::Event::get_keyval
-  Gtk3::Gdk::Event::get_scroll_direction
-  Gtk3::Gdk::Event::get_scroll_deltas
-  Gtk3::Gdk::Event::get_state
-  Gtk3::Gdk::Event::get_root_coords
-/;
 my %_GDK_REBLESSERS = (
   'Gtk3::Gdk::Event' => \&Gtk3::Gdk::Event::_rebless,
 );
@@ -202,13 +440,12 @@ sub Gtk3::Gdk::Event::_rebless {
   return bless $event, $package;
 }
 
-# - gdk-pixbuf customization ------------------------------------------------ #
+# - Wiring ------------------------------------------------------------------ #
 
-my @_GDK_PIXBUF_FLATTEN_ARRAY_REF_RETURN_FOR = qw/
-  Gtk3::Gdk::Pixbuf::get_formats
-/;
+=item * Gtk3::Gdk::Atom has overloads for the C<==> and C<!=> operators that
+check for equality of the underlying atoms.
 
-# - Wiring ------------------------------------------------------------------ #
+=cut
 
 sub import {
   my $class = shift;
@@ -270,6 +507,15 @@ sub import {
 
 # - Overrides --------------------------------------------------------------- #
 
+=item * For backwards compatibility, C<Gtk3::CHECK_VERSION>,
+C<Gtk3::check_version>, C<Gtk3::init>, C<Gtk3::init_check>, C<Gtk3::main>,
+C<Gtk3::main_level> and C<Gtk3::main_quit> can be called as class-static or as
+normal functions: for example, C<< Gtk3->main_quit >> and C<< Gtk3::main_quit
+>> are both supported.  Additionally, C<Gtk3::init> and C<Gtk3::init_check>
+automatically handle passing and updating C<@ARGV> as appropriate.
+
+=cut
+
 sub Gtk3::CHECK_VERSION {
   return not defined Gtk3::check_version(@_ == 4 ? @_[1..3] : @_);
 }
@@ -279,19 +525,6 @@ sub Gtk3::check_version {
                                        @_ == 4 ? @_[1..3] : @_);
 }
 
-# Names "STOP" and "PROPAGATE" here are per the GtkWidget event signal
-# descriptions.  In some other flavours of signals the jargon is "handled"
-# instead of "stop".  "Handled" matches g_signal_accumulator_true_handled(),
-# though that function doesn't rate a mention in the Gtk docs.  There's
-# nothing fixed in the idea of "true means cease emission" (whether it's
-# called "stop" or "handled").  You can just as easily have false for cease
-# (the way the underlying GSignalAccumulator func in fact operates).  The
-# upshot being don't want to attempt to be too universal with the names
-# here; "EVENT" is meant to hint at the context or signal flavour they're
-# for use with.
-sub Gtk3::EVENT_PROPAGATE() { !1 };
-sub Gtk3::EVENT_STOP() { 1 };
-
 sub Gtk3::init {
   my $rest = Glib::Object::Introspection->invoke (
                $_GTK_BASENAME, undef, 'init',
@@ -323,6 +556,10 @@ sub Gtk3::main_quit {
   Glib::Object::Introspection->invoke ($_GTK_BASENAME, undef, 'main_quit');
 }
 
+=item * A Perl reimplementation of C<Gtk3::show_about_dialog> is provided.
+
+=cut
+
 {
   my $global_about_dialog = undef;
   my $about_dialog_key = '__gtk3_about_dialog';
@@ -360,6 +597,11 @@ sub Gtk3::main_quit {
   }
 }
 
+=item * Perl reimplementations of C<Gtk3::ActionGroup::add_actions>,
+C<add_radio_actions> and C<add_toggle_actions> are provided.
+
+=cut
+
 sub Gtk3::ActionGroup::add_actions {
   my ($self, $entries, $user_data) = @_;
 
@@ -533,6 +775,14 @@ sub Gtk3::ActionGroup::add_radio_actions {
   }
 }
 
+=item * C<Gtk3::Builder::add_objects_from_file> and C<add_objects_from_string>
+also accept a list of objects instead of an array ref.
+
+=item * C<Gtk3::Builder::add_objects_from_string> and C<add_from_string> don't
+take length arguments, as they are computed automatically.
+
+=cut
+
 sub Gtk3::Builder::add_objects_from_file {
   my ($builder, $filename, @rest) = @_;
   my $ref = _rest_to_ref (\ rest);
@@ -556,6 +806,11 @@ sub Gtk3::Builder::add_from_string {
     $builder, $string, -1); # wants length in bytes
 }
 
+=item * A Perl reimplementation of C<Gtk3::Builder::connect_signals> is
+provided.
+
+=cut
+
 # Copied from Gtk2.pm
 sub Gtk3::Builder::connect_signals {
   my $builder = shift;
@@ -628,6 +883,12 @@ sub Gtk3::Builder::connect_signals {
   }
 }
 
+=item * The default C<new> constructors of Gtk3::Button, Gtk3::CheckButton,
+Gtk3::ColorButton, Gtk3::FontButton and Gtk3::ToggleButton reroute to
+C<new_with_mnemonic> if given an extra argument.
+
+=cut
+
 {
   no strict 'refs';
   my @button_classes = ([Button => 'new_with_mnemonic'],
@@ -649,6 +910,11 @@ sub Gtk3::Builder::connect_signals {
   }
 }
 
+=item * The default C<new> constructor of Gtk3::CheckMenuItem reroutes to
+C<new_with_mnemonic> if given an extra argument.
+
+=cut
+
 sub Gtk3::CheckMenuItem::new {
   my ($class, $mnemonic) = @_;
   if (defined $mnemonic) {
@@ -658,6 +924,11 @@ sub Gtk3::CheckMenuItem::new {
     $_GTK_BASENAME, 'CheckMenuItem', 'new', @_);
 }
 
+=item * C<Gtk3::Container::get_focus_chain> returns a list of widgets, or an
+empty list.
+
+=cut
+
 sub Gtk3::Container::get_focus_chain {
   my ($container) = @_;
   my ($is_set, $widgets) = Glib::Object::Introspection->invoke (
@@ -667,6 +938,10 @@ sub Gtk3::Container::get_focus_chain {
   return @$widgets;
 }
 
+=item * C<Gtk3::Container::set_focus_chain> also accepts a list of widgets.
+
+=cut
+
 sub Gtk3::Container::set_focus_chain {
   my ($container, @rest) = @_;
   return Glib::Object::Introspection->invoke (
@@ -674,6 +949,10 @@ sub Gtk3::Container::set_focus_chain {
     $container, _rest_to_ref (\ rest));
 }
 
+=item * C<Gtk3::CssProvider::load_from_data> also accepts a string.
+
+=cut
+
 sub Gtk3::CssProvider::load_from_data {
   my ($self, $data) = @_;
   return Glib::Object::Introspection->invoke (
@@ -681,6 +960,11 @@ sub Gtk3::CssProvider::load_from_data {
     $self, _unpack_unless_array_ref ($data));
 }
 
+=item * For Gtk3::Dialog and Gtk3::InfoBar, a Perl implementaion of
+C<add_buttons> is provided.
+
+=cut
+
 # Gtk3::Dialog / Gtk3::InfoBar methods due to overlap
 {
   no strict qw(refs);
@@ -731,6 +1015,12 @@ sub Gtk3::Dialog::get_widget_for_response {
     $_[0], $_GTK_RESPONSE_NICK_TO_ID->($_[1]));
 }
 
+=item * C<Gtk3::Dialog::new> can optionally be called as C<< Gtk3::Dialog->new
+(TITLE, PARENT, FLAGS, ...) >> where C<...> is a series of button text and
+response id pairs.
+
+=cut
+
 sub Gtk3::Dialog::new {
   my ($class, $title, $parent, $flags, @rest) = @_;
   if (@_ == 1) {
@@ -751,6 +1041,10 @@ sub Gtk3::Dialog::new {
   }
 }
 
+=item * A Perl implementation of C<Gtk3::Dialog::new_with_buttons> is provided.
+
+=cut
+
 sub Gtk3::Dialog::new_with_buttons {
   &Gtk3::Dialog::new;
 }
@@ -769,17 +1063,25 @@ sub Gtk3::Dialog::set_alternative_button_order {
     $dialog, [map { $_GTK_RESPONSE_NICK_TO_ID->($_) } @rest]);
 }
 
+=item * The C<length> argument of C<Gtk3::Editable::insert_text> is optional.
+
+=cut
+
 sub Gtk3::Editable::insert_text {
   return Glib::Object::Introspection->invoke (
     $_GTK_BASENAME, 'Editable', 'insert_text',
     @_ == 4 ? @_ : (@_[0,1], -1, $_[2])); # wants length in bytes
 }
 
+=item * A Perl implementation of C<Gtk3::FileChooserDialog::new> is provided.
+
+=cut
+
 sub Gtk3::FileChooserDialog::new {
   my ($class, $title, $parent, $action, @varargs) = @_;
 
   if (@varargs % 2) {
-    croak 'Usage: Gtk2::FileChooserDialog->new' .
+    croak 'Usage: Gtk3::FileChooserDialog->new' .
           ' (title, parent, action, backend, button-text =>' .
           " response-id, ...)\n";
   }
@@ -801,6 +1103,11 @@ sub Gtk3::FileChooserDialog::new {
   return $result;
 }
 
+=item * C<Gtk3::HBox::new> uses the defaults homogeneous = FALSE and spacing =
+5.
+
+=cut
+
 sub Gtk3::HBox::new {
   my ($class, $homogeneous, $spacing) = @_;
   $homogeneous = 0 unless defined $homogeneous;
@@ -838,6 +1145,11 @@ sub Gtk3::HBox::new {
   }
 }
 
+=item * The default C<new> constructor of Gtk3::ImageMenuItem reroutes to
+C<new_with_mnemonic> if given an extra argument.
+
+=cut
+
 sub Gtk3::ImageMenuItem::new {
   my ($class, $mnemonic) = @_;
   if (defined $mnemonic) {
@@ -847,6 +1159,12 @@ sub Gtk3::ImageMenuItem::new {
     $_GTK_BASENAME, 'ImageMenuItem', 'new', @_);
 }
 
+=item * C<Gtk3::InfoBar::new> can optionally be called as C<<
+Gtk3::InfoBar->new (...) >> where C<...> is a series of button text and
+response id pairs.
+
+=cut
+
 sub Gtk3::InfoBar::new {
   my ($class, @buttons) = @_;
   if (@_ == 1) {
@@ -863,10 +1181,20 @@ sub Gtk3::InfoBar::new {
   }
 }
 
+=item * A Perl reimplementation of C<Gtk3::InfoBar::new_with_buttons> is
+provided.
+
+=cut
+
 sub Gtk3::InfoBar::new_with_buttons {
   &Gtk3::InfoBar::new;
 }
 
+=item * The default C<new> constructor of Gtk3::LinkButton reroutes to
+C<new_with_label> if given an extra argument.
+
+=cut
+
 sub Gtk3::LinkButton::new {
   my ($class, $uri, $label) = @_;
   if (defined $label) {
@@ -877,15 +1205,29 @@ sub Gtk3::LinkButton::new {
   }
 }
 
+=item * C<Gtk3::ListStore::new> also accepts a list of type names.
+
+=cut
+
 sub Gtk3::ListStore::new {
   return _common_tree_model_new ('ListStore', @_);
 }
 
+=item * Gtk3::ListStore has a C<get> method that calls C<Gtk3::TreeModel::get>
+instead of C<Glib::Object::get>.
+
+=cut
+
 # Reroute 'get' to Gtk3::TreeModel instead of Glib::Object.
 sub Gtk3::ListStore::get {
   return Gtk3::TreeModel::get (@_);
 }
 
+=item * C<Gtk3::ListStore::insert_with_values> also accepts a list of C<<
+column => value >> pairs and reroutes to C<insert_with_valuesv>.
+
+=cut
+
 sub Gtk3::ListStore::insert_with_values {
   my ($model, $position, @columns_and_values) = @_;
   my ($columns, $values) = _unpack_keys_and_values (\ columns_and_values);
@@ -905,15 +1247,30 @@ sub Gtk3::ListStore::insert_with_values {
     $model, $position, $columns, \ wrapped_values);
 }
 
+=item * C<Gtk3::ListStore::set> also accepts a list of C<< column => value >>
+pairs.
+
+=cut
+
 sub Gtk3::ListStore::set {
   return _common_tree_model_set ('ListStore', @_);
 }
 
+=item * C<Gtk3::Menu::popup> reroutes to C<popup_for_device> for better
+callback handling.
+
+=cut
+
 sub Gtk3::Menu::popup {
   my $self = shift;
   $self->popup_for_device (undef, @_);
 }
 
+=item * C<Gtk3::Menu::popup_for_device> allows the given menu position func to
+return only x and y coordinates, defaulting C<push_in> to FALSE.
+
+=cut
+
 sub Gtk3::Menu::popup_for_device {
   my ($menu, $device, $parent_menu_shell, $parent_menu_item, $func, $data, $button, $activate_time) = @_;
   my $real_func = $func ? sub {
@@ -936,6 +1293,11 @@ sub Gtk3::Menu::popup_for_device {
     $menu, $device, $parent_menu_shell, $parent_menu_item, $real_func, $data, $button, $activate_time);
 }
 
+=item * The default C<new> constructor of Gtk3::MenuItem reroutes to
+C<new_with_mnemonic> if given an extra argument.
+
+=cut
+
 sub Gtk3::MenuItem::new {
   my ($class, $mnemonic) = @_;
   if (defined $mnemonic) {
@@ -945,6 +1307,10 @@ sub Gtk3::MenuItem::new {
     $_GTK_BASENAME, 'MenuItem', 'new', @_);
 }
 
+=item * A Perl reimplementation of C<Gtk3::MessageDialog::new> is provided.
+
+=cut
+
 sub Gtk3::MessageDialog::new {
   my ($class, $parent, $flags, $type, $buttons, $format, @args) = @_;
   my $dialog = Glib::Object::new ($class, message_type => $type,
@@ -966,6 +1332,13 @@ sub Gtk3::MessageDialog::new {
   return $dialog;
 }
 
+=item * The group handling in the constructors and accessors of
+Gtk3::RadioAction, Gtk3::RadioButton, Gtk3::RadioMenuItem and
+Gtk3::RadioToolButton is amended to work correctly when given array refs of
+group members or single group members.
+
+=cut
+
 # Gtk3::RadioAction, Gtk3::RadioButton, Gtk3::RadioMenuItem and
 # Gtk3::RadioToolButton constructors.
 {
@@ -1058,6 +1431,11 @@ sub Gtk3::MessageDialog::new {
   }
 }
 
+=item * Perl reimplementations of C<Gtk3::RecentChooserDialog::new> and
+C<new_for_manager> are provided.
+
+=cut
+
 sub Gtk3::RecentChooserDialog::new {
   my ($class, $title, $parent, @buttons) = @_;
   my $dialog = Glib::Object::new ($class, title => $title);
@@ -1083,6 +1461,12 @@ sub Gtk3::RecentChooserDialog::new_for_manager {
   return $dialog;
 }
 
+=item * Redirects are provided from C<Gtk3::Stock::[function]> to
+C<Gtk3::stock_[function]> for C<add>, C<add_static>, C<list_ids>, C<lookup> and
+C<set_translate_func>.
+
+=cut
+
 {
   no strict qw/refs/;
 
@@ -1099,6 +1483,10 @@ sub Gtk3::RecentChooserDialog::new_for_manager {
   }
 }
 
+=item * A Perl reimplementation of C<Gtk3::TextBuffer::create_tag> is provided.
+
+=cut
+
 sub Gtk3::TextBuffer::create_tag {
   my ($buffer, $tag_name, @rest) = @_;
   if (@rest % 2) {
@@ -1113,6 +1501,12 @@ sub Gtk3::TextBuffer::create_tag {
   return $tag;
 }
 
+=item * The C<length> arguments of C<Gtk3::TextBuffer::insert>,
+C<insert_at_cursor>, C<insert_interactive>, C<insert_interactive_at_cursor> and
+C<set_text> are optional.
+
+=cut
+
 sub Gtk3::TextBuffer::insert {
   return Glib::Object::Introspection->invoke (
     $_GTK_BASENAME, 'TextBuffer', 'insert',
@@ -1137,6 +1531,12 @@ sub Gtk3::TextBuffer::insert_interactive_at_cursor {
     @_ == 4 ? @_ : (@_[0,1], -1, $_[2])); # wants length in bytes
 }
 
+=item * Perl reimplementations of C<Gtk3::TextBuffer::insert_with_tags> and
+C<insert_with_tags_by_name> are provided which do not require a C<length>
+argument.
+
+=cut
+
 sub Gtk3::TextBuffer::insert_with_tags {
   my ($buffer, $iter, $text, @tags) = @_;
   my $start_offset = $iter->get_offset;
@@ -1169,6 +1569,10 @@ sub Gtk3::TextBuffer::set_text {
     @_ == 3 ? @_ : (@_[0,1], -1)); # wants length in bytes
 }
 
+=item * A Perl reimplementation of C<Gtk3::TreeModel::get> is provided.
+
+=cut
+
 sub Gtk3::TreeModel::get {
   my ($model, $iter, @columns) = @_;
   if (! columns) {
@@ -1178,6 +1582,12 @@ sub Gtk3::TreeModel::get {
   return @values[0..$#values];
 }
 
+=item * A redirect is added from C<Gtk3::TreeModelFilter::new> to
+<Gtk3::TreeModel::filter_new> so that Gtk3::TreeModelFilter objects can be
+constructed normally.
+
+=cut
+
 # Not needed anymore once <https://bugzilla.gnome.org/show_bug.cgi?id=646742>
 # is fixed.
 sub Gtk3::TreeModelFilter::new {
@@ -1186,11 +1596,22 @@ sub Gtk3::TreeModelFilter::new {
     $_GTK_BASENAME, 'TreeModel', 'filter_new', $child_model, $root);
 }
 
+=item * Gtk3::TreeModelFilter has a C<get> method that calls
+C<Gtk3::TreeModel::get> instead of C<Glib::Object::get>.
+
+=cut
+
 # Reroute 'get' to Gtk3::TreeModel instead of Glib::Object.
 sub Gtk3::TreeModelFilter::get {
   return Gtk3::TreeModel::get (@_);
 }
 
+=item * A redirect is added from C<Gtk3::TreeModelSort::new_with_model> to
+<Gtk3::TreeModel::sort_new_with_model> so that Gtk3::TreeModelSort objects can
+be constructed normally.
+
+=cut
+
 # Not needed anymore once <https://bugzilla.gnome.org/show_bug.cgi?id=646742>
 # is fixed.
 sub Gtk3::TreeModelSort::new_with_model {
@@ -1199,11 +1620,21 @@ sub Gtk3::TreeModelSort::new_with_model {
     $_GTK_BASENAME, 'TreeModel', 'sort_new_with_model', $child_model);
 }
 
+=item * Gtk3::TreeModelSort has a C<get> method that calls
+C<Gtk3::TreeModel::get> instead of C<Glib::Object::get>.
+
+=cut
+
 # Reroute 'get' to Gtk3::TreeModel instead of Glib::Object.
 sub Gtk3::TreeModelSort::get {
   return Gtk3::TreeModel::get (@_);
 }
 
+=item * C<Gtk3::TreePath::new> redirects to C<new_from_string> if an additional
+argument is given.
+
+=cut
+
 sub Gtk3::TreePath::new {
   my ($class, @args) = @_;
   my $method = (@args == 1) ? 'new_from_string' : 'new';
@@ -1211,6 +1642,11 @@ sub Gtk3::TreePath::new {
     $_GTK_BASENAME, 'TreePath', $method, @_);
 }
 
+=item * A Perl reimplementation of C<Gtk3::TreePath::new_from_indices> is
+provided.
+
+=cut
+
 sub Gtk3::TreePath::new_from_indices {
   my ($class, @indices) = @_;
   my $path = Gtk3::TreePath->new;
@@ -1220,15 +1656,29 @@ sub Gtk3::TreePath::new_from_indices {
   return $path;
 }
 
+=item * C<Gtk3::TreeStore::new> also accepts a list of type names.
+
+=cut
+
 sub Gtk3::TreeStore::new {
   return _common_tree_model_new ('TreeStore', @_);
 }
 
+=item * Gtk3::TreeStore has a C<get> method that calls C<Gtk3::TreeModel::get>
+instead of C<Glib::Object::get>.
+
+=cut
+
 # Reroute 'get' to Gtk3::TreeModel instead of Glib::Object.
 sub Gtk3::TreeStore::get {
   return Gtk3::TreeModel::get (@_);
 }
 
+=item * C<Gtk3::TreeStore::insert_with_values> also accepts a list of C<<
+column => value >> pairs.
+
+=cut
+
 sub Gtk3::TreeStore::insert_with_values {
   my ($model, $parent, $position, @columns_and_values) = @_;
   my ($columns, $values) = _unpack_keys_and_values (\ columns_and_values);
@@ -1248,10 +1698,20 @@ sub Gtk3::TreeStore::insert_with_values {
     $model, $parent, $position, $columns, \ wrapped_values);
 }
 
+=item * C<Gtk3::TreeStore::set> also accepts a list of C<< column => value >>
+pairs.
+
+=cut
+
 sub Gtk3::TreeStore::set {
   return _common_tree_model_set ('TreeStore', @_);
 }
 
+=item * C<Gtk3::TreeView::new> redirects to C<new_with_model> if an additional
+argument is given.
+
+=cut
+
 sub Gtk3::TreeView::new {
   my ($class, @args) = @_;
   my $method = (@args == 1) ? 'new_with_model' : 'new';
@@ -1259,6 +1719,11 @@ sub Gtk3::TreeView::new {
     $_GTK_BASENAME, 'TreeView', $method, @_);
 }
 
+=item * A Perl reimplementation of
+C<Gtk3::TreeView::insert_column_with_attributes> is provided.
+
+=cut
+
 sub Gtk3::TreeView::insert_column_with_attributes {
   my ($tree_view, $position, $title, $cell, @rest) = @_;
   if (@rest % 2) {
@@ -1274,6 +1739,11 @@ sub Gtk3::TreeView::insert_column_with_attributes {
   return $n;
 }
 
+=item * A Perl reimplementation of C<Gtk3::TreeViewColumn::new_with_attributes>
+is provided.
+
+=cut
+
 sub Gtk3::TreeViewColumn::new_with_attributes {
   my ($class, $title, $cell, @rest) = @_;
   if (@rest % 2) {
@@ -1288,6 +1758,11 @@ sub Gtk3::TreeViewColumn::new_with_attributes {
   return $object;
 }
 
+=item * Perl reimplementations of C<Gtk3::TreeViewColumn::set_attributes> and
+C<Gtk3::CellLayout::set_attributes> are provided.
+
+=cut
+
 # Gtk3::TreeViewColumn::set_attributes and Gtk3::CellLayout::set_attributes
 {
   no strict 'refs';
@@ -1305,6 +1780,10 @@ sub Gtk3::TreeViewColumn::new_with_attributes {
   }
 }
 
+=item * C<Gtk3::UIManager::add_ui_from_string> takes no C<length> argument.
+
+=cut
+
 sub Gtk3::UIManager::add_ui_from_string {
   my ($manager, $string) = @_;
   return Glib::Object::Introspection->invoke (
@@ -1312,6 +1791,11 @@ sub Gtk3::UIManager::add_ui_from_string {
     $manager, $string, -1); # wants length in bytes
 }
 
+=item * C<Gtk3::VBox::new> uses the defaults homogeneous = FALSE and spacing =
+5.
+
+=cut
+
 sub Gtk3::VBox::new {
   my ($class, $homogeneous, $spacing) = @_;
   $homogeneous = 0 unless defined $homogeneous;
@@ -1327,6 +1811,10 @@ sub Gtk3::Widget::render_icon {
     $_GTK_ICON_SIZE_NICK_TO_ID->($size), $detail);
 }
 
+=item * C<Gtk3::Window::new> uses the default type = 'toplevel'.
+
+=cut
+
 sub Gtk3::Window::new {
   my ($class, $type) = @_;
   $type = 'toplevel' unless defined $type;
@@ -1334,7 +1822,12 @@ sub Gtk3::Window::new {
     $_GTK_BASENAME, 'Window', 'new', $class, $type);
 }
 
-# Gdk
+# --- Gdk ---
+
+=item * A constructor C<Gtk3::Gdk::RGBA::new> is provided that can be called as
+C<< Gtk3::Gdk::RGBA->new (r, g, b, a) >>.
+
+=cut
 
 sub Gtk3::Gdk::RGBA::new {
   my ($class, @rest) = @_;
@@ -1348,6 +1841,12 @@ sub Gtk3::Gdk::RGBA::new {
   return Glib::Boxed::new ($class, @rest);
 }
 
+=item * C<Gtk3::Gdk::RGBA::parse> can be called as a function returning a new
+instance (C<< $rgba = Gtk3::Gdk::RGBA::parse ($spec) >>) or as a method (C<<
+$rgba->parse ($spec) >>).
+
+=cut
+
 sub Gtk3::Gdk::RGBA::parse {
   my $have_instance;
   {
@@ -1368,6 +1867,11 @@ sub Gtk3::Gdk::RGBA::parse {
   }
 }
 
+=item * C<Gtk3::Gdk::Window::new> optionally computes the C<attr_mask>
+automatically from the given C<attr>.
+
+=cut
+
 sub Gtk3::Gdk::Window::new {
   my ($class, $parent, $attr, $attr_mask) = @_;
   if (not defined $attr_mask) {
@@ -1392,7 +1896,11 @@ sub Gtk3::Gdk::Window::new {
     $class, $parent, $attr, $attr_mask);
 }
 
-# GdkPixbuf
+# --- GdkPixbuf ---
+
+=item * C<Gtk3::Gdk::Pixbuf::get_pixels> returns a byte string.
+
+=cut
 
 sub Gtk3::Gdk::Pixbuf::get_pixels {
   my $pixel_aref = Glib::Object::Introspection->invoke (
@@ -1444,6 +1952,11 @@ my $HAVE_GDK_PIXBUF_2_31_3 = sub {
          (Gtk3::Gdk::PIXBUF_MAJOR () == 2 && Gtk3::Gdk::PIXBUF_MINOR () == 31 && Gtk3::Gdk::PIXBUF_MICRO () 

= 3);

 };
 
+=item * C<Gtk3::Gdk::Pixbuf::save>, C<save_to_buffer> and C<save_to_callback>
+also accept C<< key => value >> pairs and invoke the correct C function as
+appropriate for the current gdk-pixbuf version.
+
+=cut
 
 sub Gtk3::Gdk::Pixbuf::save {
   my ($pixbuf, $filename, $type, @rest) = @_;
@@ -1513,7 +2026,11 @@ sub Gtk3::Gdk::Pixbuf::save_to_callback {
     $pixbuf, $save_func, $user_data, $type, $keys, $values);
 }
 
-# Pango
+# --- Pango ---
+
+=item * C<Pango::Layout::set_text> takes no C<length> argument.
+
+=cut
 
 sub Pango::Layout::set_text {
   return Glib::Object::Introspection->invoke (
@@ -1521,8 +2038,23 @@ sub Pango::Layout::set_text {
     @_ == 3 ? @_ : (@_[0,1], -1)); # wants length in bytes
 }
 
+=back
+
+=cut
+
 # - Fixes ------------------------------------------------------------------- #
 
+=head2 Perl compatibility
+
+As of 5.20.0, perl does not automatically re-check the locale environment for
+changes.  If a function thus changes the locale behind perl's back, problems
+might arise whenever numbers are formatted, for example when checking versions.
+To ensure perl's assumption about the locale are up-to-date, the functions
+C<Gtk3::init>, C<init_check>, C<init_with_args> and C<parse_args> are amended
+to let perl know of any changes.
+
+=cut
+
 # Compatibility with perl 5.20 and non-dot locales.  Wrap all functions that
 # might end up calling setlocale() such that POSIX::setlocale() is also called
 # to ensure perl knows about the current locale.  See the discussion in
@@ -1642,45 +2174,6 @@ sub _rest_to_ref {
 
 __END__
 
-# - Docs -------------------------------------------------------------------- #
-
-=head1 NAME
-
-Gtk3 - Perl interface to the 3.x series of the gtk+ toolkit
-
-=head1 SYNOPSIS
-
-  use Gtk3 -init;
-  my $window = Gtk3::Window->new ('toplevel');
-  my $button = Gtk3::Button->new ('Quit');
-  $button->signal_connect (clicked => sub { Gtk3::main_quit });
-  $window->add ($button);
-  $window->show_all;
-  Gtk3::main;
-
-=head1 ABSTRACT
-
-Perl bindings to the 3.x series of the gtk+ toolkit.  This module allows you to
-write graphical user interfaces in a Perlish and object-oriented way, freeing
-you from the casting and memory management in C, yet remaining very close in
-spirit to original API.
-
-=head1 DESCRIPTION
-
-The Gtk3 module allows a Perl developer to use the gtk+ graphical user
-interface library.  Find out more about gtk+ at L<http://www.gtk.org>.
-
-The gtk+ reference manual is also a handy companion when writing Gtk3 programs
-in Perl: L<http://developer.gnome.org/gtk3/stable/>.  The Perl bindings follow
-the C API very closely, and the C reference documentation should be considered
-the canonical source.
-
-To discuss Gtk3 and ask questions join gtk-perl-list gnome org at
-L<http://mail.gnome.org/mailman/listinfo/gtk-perl-list>.
-
-Also have a look at the gtk2-perl website and sourceforge project page,
-L<http://gtk2-perl.sourceforge.net>.
-
 =head2 Porting from Gtk2 to Gtk3
 
 The majority of the API has not changed, so as a first approximation you can
@@ -1757,16 +2250,20 @@ remove them.
 
 =over
 
-=item L<Glib>
+=item * To discuss Gtk3 and ask questions join gtk-perl-list gnome org at
+L<http://mail.gnome.org/mailman/listinfo/gtk-perl-list>.
+
+=item * Also have a look at the gtk2-perl website and sourceforge project page,
+L<http://gtk2-perl.sourceforge.net>.
 
-=item L<Glib::Object::Introspection>
+=item * L<Glib>
+
+=item * L<Glib::Object::Introspection>
 
 =back
 
 =head1 AUTHORS
 
-=encoding utf8
-
 =over
 
 =item Torsten Schönfeld <kaffeetisch gmx de>
@@ -1775,7 +2272,7 @@ remove them.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2011-2013 by Torsten Schoenfeld <kaffeetisch gmx de>
+Copyright (C) 2011-2015 by Torsten Schoenfeld <kaffeetisch gmx de>
 
 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
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]