From e2aa64e6ccd5b071ae0fa2577605fe39f29b2d0b Mon Sep 17 00:00:00 2001 From: "Thierry.Vignaud" Date: Thu, 22 May 2014 11:21:12 +0200 Subject: convert comments to POD --- perl-install/ugtk3.pm | 180 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 136 insertions(+), 44 deletions(-) (limited to 'perl-install/ugtk3.pm') diff --git a/perl-install/ugtk3.pm b/perl-install/ugtk3.pm index d2bcc18ed..b16e0a46b 100644 --- a/perl-install/ugtk3.pm +++ b/perl-install/ugtk3.pm @@ -40,18 +40,27 @@ use mygtk3 qw(gtknew); #- do not import gtkadd which conflicts with ugtk3 versio use Gtk3; +=head1 SYNOPSYS + +B enables to write GUIes using Gtk+3. It adds nice wrappers on top of +L, notably gtkpowerpack() and its children gtkpack*() + +=cut $border = 5; sub wm_icon() { $wm_icon || $::Wizard_pix_up || "wiz_default_up.png" } -# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=--- -# wrappers -# -# Functional-style wrappers to existing Gtk functions; allows to program in -# a more functional way, and especially, first, to avoid using temp -# variables, and second, to "see" directly in the code the user interface -# you're building. +=head1 Wrappers + +Functional-style wrappers to existing Gtk functions; allows to program in +a more functional way, and especially, first, to avoid using temp +variables, and second, to "see" directly in the code the user interface +you're building. + +=over + +=cut sub gtkdestroy { mygtk3::may_destroy($_[0]) } sub gtkflush() { mygtk3::flush() } @@ -122,7 +131,12 @@ sub gtkappenditems { $w; } -# append page to a notebook +=item gtkappend_page($notebook, $page, $o_title) + +append page to a notebook + +=cut + sub gtkappend_page { my ($notebook, $page, $o_title) = @_; $notebook->append_page($page, $o_title); @@ -249,13 +263,16 @@ sub gtktreeview_children { @l; } +=back +=head1 Create functions -# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=--- -# create -# -# Helpers that allow omitting common operations on common widgets -# (e.g. create widgets with good default properties) +Helpers that allow omitting common operations on common widgets +(e.g. create widgets with good default properties) + +=over + +=cut sub create_pixbutton { my ($label, $pix, $reverse_order) = @_; @@ -286,11 +303,15 @@ sub n_line_size { round($nbline * ($fontinfo{ascent} + $fontinfo{descent} + $spacing) + 8); } -# Glib::Markup::escape_text() if no use for us because it'll do extra -# s/X/&foobar;/ (such as s/'/'/) that are suitable for -# Gtk3::Labels but are not for Gtk3::TextViews, resulting in -# displaying the raw enriched text instead... -# +=item escape_text_for_TextView_markup_format($str) + +Glib::Markup::escape_text() if no use for us because it'll do extra +s/X/&foobar;/ (such as s/'/'/) that are suitable for +Gtk3::Labels but are not for Gtk3::TextViews, resulting in +displaying the raw enriched text instead... + +=cut + sub escape_text_for_TextView_markup_format { my ($str) = @_; my %rules = ('&' => '&', @@ -582,12 +603,16 @@ sub gtkcreate_frame { gtknew('Frame', text => $label, border_width => 5); } +=back + +=head1 Helpers + +Functions that do typical operations on widgets, that you may need in +several places of your programs. -# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=--- -# helpers -# -# Functions that do typical operations on widgets, that you may need in -# several places of your programs. +=over + +=cut sub _find_imgfile { my ($name) = @_; @@ -604,13 +629,23 @@ sub _find_imgfile { } } -# use it if you want to display an icon/image in your app +=item gtkcreate_img($file, $o_size) + +use it if you want to display an icon/image in your app + +=cut + sub gtkcreate_img { my ($file, $o_size) = @_; gtknew('Image', file => $file, if_($o_size, size => $o_size)); } -# use it if you want to draw an image onto a drawingarea +=item gtkcreate_pixbuf($file, $o_size) + +use it if you want to draw an image onto a drawingarea + +=cut + sub gtkcreate_pixbuf { my ($file, $o_size) = @_; gtknew('Pixbuf', file => $file, if_($o_size, size => $o_size)); @@ -634,7 +669,12 @@ sub set_main_window_size { mygtk3::set_main_window_size($o->{rwindow}); } -# extracts interesting font metrics for a given widget +=item gtkfontinfo($widget) + +extracts interesting font metrics for a given widget + +=cut + sub gtkfontinfo { my ($widget) = @_; my $context = $widget->get_pango_context; @@ -699,14 +739,21 @@ sub set_default_step_items { sub get_default_step_items { ($def_step_title) } -# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=--- -# toplevel window creation helper -# -# Use the 'new' function as a method constructor and then 'main' on it to -# launch the main loop. Use $o->{retval} to indicate that the window needs -# to terminate. -# Set $::isWizard to have a wizard appearance. -# Set $::isEmbedded and $::XID so that the window will plug. +=back + +=head1 Toplevel window creation helper + +=over + +=item new($type, $title, %opts) + +Use the 'new' function as a method constructor and then 'main' on it to +launch the main loop. Use $o->{retval} to indicate that the window needs +to terminate. +Set $::isWizard to have a wizard appearance. +Set $::isEmbedded and $::XID so that the window will plug. + +=cut sub new { my ($type, $title, %opts) = @_; @@ -782,11 +829,16 @@ sub exit { #- in case "exit" above was not called by the program END { &exit() } -# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=--- -# ask -# -# Full UI managed functions that will return to you the value that the -# user chose. +=back + +=head1 Ask functions + +Full UI managed functions that will return to you the value that the +user chose. + +=over + +=cut sub ask_warn { my $w = ugtk3->new(shift @_, grab => 1); $w->_ask_warn(@_); main($w) } sub ask_yesorno { my $w = ugtk3->new(shift @_, grab => 1); $w->_ask_okcancel(@_, N("Yes"), N("No")); main($w) } @@ -1217,7 +1269,13 @@ sub gtk_new_TextView_get_log { $log_scroll, $pid; } -# misc helpers: +=back + +=head1 Misc helpers & widgets + +=over + +=cut package Gtk3::TreeStore; sub append_set { @@ -1231,7 +1289,13 @@ sub append_set { package Gtk3::ListStore; -# Append a new row, set the values, return the TreeIter + +=item Gtk3::ListStore::append_set($model, @values) + +Append a new row, set the values, return the TreeIter + +=cut + sub append_set { my ($model, @values) = @_; # compatibility: @@ -1243,7 +1307,13 @@ sub append_set { package Gtk3::TreeModel; -# gets the string representation of a TreeIter + +=item Gtk3::TreeModel::get_path_str($self, $iter) + +gets the string representation of a TreeIter + +=cut + sub get_path_str { my ($self, $iter) = @_; my $path = $self->get_path($iter); @@ -1260,7 +1330,13 @@ sub iter_each_children { } package Gtk3::TreeView; -# likewise gtk-1.2 function + +=item Gtk3::TreeView;::toggle_expansion($self, $path, $b_open_all) + +gtk-1.2 compatibility function + +=cut + sub toggle_expansion { my ($self, $path, $b_open_all) = @_; if ($self->row_expanded($path)) { @@ -1273,7 +1349,12 @@ sub toggle_expansion { package Gtk3::ComboBox; use MDK::Common; -# try to get combox <==> option menu mapping +=item Gtk3::ComboBox::set_popdown_strings($w, @strs) + +try to get combox <==> option menu mapping + +=cut + sub set_popdown_strings { my ($w, @strs) = @_; my $model = $w->get_model; @@ -1345,6 +1426,13 @@ sub new_with_text { package Gtk3::Banner; +=item Gtk3::Banner widget + +Used in tools & installer banner bars + +=cut + + use MDK::Common; use mygtk3 qw(gtknew); use ugtk3 qw(:helpers :wrappers); @@ -1481,4 +1569,8 @@ sub new { }; } +=back + +=cut + 1; -- cgit v1.2.1