summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThierry.Vignaud <thierry.vignaud@gmail.com>2014-05-22 11:21:12 +0200
committerThierry Vignaud <thierry.vignaud@gmail.com>2014-05-24 01:47:16 +0200
commite2aa64e6ccd5b071ae0fa2577605fe39f29b2d0b (patch)
tree6675f47ba99ba15fe69c39c29b6fd02d3460bd6f
parentb2c42ba3b0fa6ae68c9f2cb78fa37831e844f8af (diff)
downloaddrakx-e2aa64e6ccd5b071ae0fa2577605fe39f29b2d0b.tar
drakx-e2aa64e6ccd5b071ae0fa2577605fe39f29b2d0b.tar.gz
drakx-e2aa64e6ccd5b071ae0fa2577605fe39f29b2d0b.tar.bz2
drakx-e2aa64e6ccd5b071ae0fa2577605fe39f29b2d0b.tar.xz
drakx-e2aa64e6ccd5b071ae0fa2577605fe39f29b2d0b.zip
convert comments to POD
-rw-r--r--perl-install/interactive.pm275
-rw-r--r--perl-install/ugtk3.pm180
2 files changed, 335 insertions, 120 deletions
diff --git a/perl-install/interactive.pm b/perl-install/interactive.pm
index 34ae7a4de..b24c67e7f 100644
--- a/perl-install/interactive.pm
+++ b/perl-install/interactive.pm
@@ -9,83 +9,68 @@ use strict;
use common;
use do_pkgs;
-#- minimal example using interactive:
-#
-#- > use lib qw(/usr/lib/libDrakX);
-#- > use interactive;
-#- > my $in = interactive->vnew;
-#- > $in->ask_okcancel('title', 'question');
-#- > $in->exit;
-
-#- ask_from_ takes global options ($common):
-#- title => window title
-#- messages => message displayed in the upper part of the window
-#- ok => force the name of the "Ok"/"Next" button
-#- cancel => force the name of the "Cancel"/"Previous" button
-#- focus_cancel => force focus on the "Cancel" button
-#- focus_first => (deprecated) force focus on the first entry
-#- ok_disabled => function returning wether {ok} should be disabled (grayed)
-#- validate => function called when {ok} is pressed. If it returns false, the first entry is focused, otherwise it quits
-#- advanced => (deprecated) function called when the "advanced" expander is toggled
-#- advanced_messages => (deprecated) message displayed when "Advanced" is pressed
-#- advanced_label => (deprecated) force the name of the "Advanced" button
-#- advanced_label_close => (deprecated) force the name of the "Basic" button
-#- advanced_state => (deprecated) if set to 1, force the "Advanced" part of the dialog to be opened initially
-#- advanced_title => (deprecated) title of the advanced item popup dialog (else reusing main title)
-#- callbacks => (deprecated) functions called when something happen: complete advanced ok_disabled
-
-#- ask_from_ takes a list of entries with fields:
-#- val => reference to the value
-#- label => description
-#- title => a boolean: whether the label should be displayed as a title (see GNOME's HIG)
-#- icon => icon to put before the description
-#- help => tooltip
-#- advanced => (deprecated) wether it is shown in by default or only in advanced mode
-#- focus_out => function called when the entry is focused out
-#- changed => function called when the entry is modified
-#- validate => function called when "Ok" is pressed. If it returns false, this entry is focused, otherwise it quits
-#- disabled => function returning wether it should be disabled (grayed)
-#- focus => function returning wether it should be focused
-#- alignment => preferred alignment
-#- do_not_expand => do not eat all horizontal space
-#- install_button => if possible, use improved graphical style
-#- gtk => gtk preferences
-#- type =>
-#- button => (with clicked or clicked_may_quit)
-#- (type defaults to button if clicked or clicked_may_quit is there)
-#- (val need not be a reference) (if clicked_may_quit return true, it's as if "Ok" was pressed)
-#- label => (val need not be a reference) (type defaults to label if val is not a reference)
-#- bool (with "text" or "image" (which overrides text) giving an image filename)
-#- range (with min, max, SpinButton)
-#- combo (with list, not_edit, format)
-#- list (with list, icon2f (aka icon), separator (aka tree), format (aka pre_format function),
-#- help can be a hash or a function,
-#- tree_expanded boolean telling wether the tree should be wide open by default
-#- quit_if_double_click boolean
-#- allow_empty_list disables the special cases for 0 and 1 element lists
-#- image2f is a subroutine which takes a value of the list as parameter, and returns image_file_name
-#- entry (the default) (with hidden)
-#- expander (with text, expanded, message, children(a list of sub entries))
-#
-#- heritate from this class and you'll get all made interactivity for same steps.
-#- for this you need to provide
-#- - ask_from_listW(o, title, messages, arrayref, default) returns one string of arrayref
-#-
-#- where
-#- - o is the object
-#- - title is a string
-#- - messages is an refarray of strings
-#- - default is an optional string (default is in arrayref)
-#- - arrayref is an arrayref of strings
-#- - arrayref2 contains booleans telling the default state,
-#-
-#- ask_from_list and ask_from_list_ are wrappers around ask_from_biglist and ask_from_smalllist
-#-
-#- ask_from_list_ just translate arrayref before calling ask_from_list and untranslate the result
-#-
-#- ask_from_listW should handle differently small lists and big ones.
-#-
+=head1 NAME
+interactive - a GUI layer with multiple backend (text console, Gtk+ GUI, web)
+
+=head1 SYNOPSYS
+
+B<interactive> enables to write GUIes that will work everywhere:
+
+=over 4
+
+=item * text console
+
+implemented by L<interactive::stdio> & L<interactive::curses>
+
+=item * web browser
+
+implemented by L<interactive::http>
+
+=item * GUI
+
+implemented by L<interactive::gtk>
+
+=back
+
+=head1 Minimal example using interactive
+
+ use lib qw(/usr/lib/libDrakX);
+ use interactive;
+ my $in = interactive->vnew;
+ $in->ask_okcancel('title', 'question');
+ $in->exit;
+
+=head1 Backends
+
+heritate from this class and you'll get all made interactivity for same steps.
+for this you need to provide
+
+C<ask_from_listW(o, title, messages, arrayref, default)> which returns one string of arrayref
+
+where:
+
+=over 4
+
+=item * B<o> is the object
+
+=item * B<title> is a string
+
+=item * B<messages> is an refarray of strings
+
+=item * B<default> is an optional string (default is in arrayref)
+
+=item * B<arrayref> is an arrayref of strings
+
+=item * B<arrayref>2 contains booleans telling the default state,
+
+=back
+
+=head1 Functions
+
+=over
+
+=cut
#-######################################################################################
#- OO Stuff
@@ -263,6 +248,18 @@ sub ask_fileW {
$o->ask_from_entry($common->{title}, $common->{message} || N("Choose a file"));
}
+=item ask_from_list($o, $title, $message, $l, $o_def)
+
+=item ask_from_list_($o, $title, $message, $l, $o_def)
+
+ask_from_list() and ask_from_list_() are wrappers around ask_from_biglist and ask_from_smalllist
+
+ask_from_list_() just translate arrayref before calling ask_from_list and untranslate the result
+
+ask_from_listW() should handle differently small lists and big ones.
+
+=cut
+
sub ask_from_list {
my ($o, $title, $message, $l, $o_def) = @_;
ask_from_listf($o, $title, $message, undef, $l, $o_def);
@@ -514,6 +511,128 @@ sub migrate_advanced {
}) ];
}
+
+=item ask_from_($o, $common, $l)
+
+ask_from_() takes global options ($common):
+
+=over 4
+
+=item * B<title>: window title
+
+=item * B<messages>: message displayed in the upper part of the window
+
+=item * B<ok>: force the name of the "Ok"/"Next" button
+
+=item * B<cancel>: force the name of the "Cancel"/"Previous" button
+
+=item * B<focus_cancel>: force focus on the "Cancel" button
+
+=item * I<focus_first>: (deprecated) force focus on the first entry
+
+=item * B<ok_disabled>: function returning wether {ok} should be disabled (grayed)
+
+=item * B<validate>: function called when {ok} is pressed. If it returns false, the first entry is focused, otherwise it quits
+
+=item * I<advanced>: (deprecated) function called when the "advanced" expander is toggled
+
+=item * I<advanced_messages>: (deprecated) message displayed when "Advanced" is pressed
+
+=item * I<advanced_label>: (deprecated) force the name of the "Advanced" button
+
+=item * I<advanced_label_close>: (deprecated) force the name of the "Basic" button
+
+=item * I<advanced_state>: (deprecated) if set to 1, force the "Advanced" part of the dialog to be opened initially
+
+=item * I<advanced_title>: (deprecated) title of the advanced item popup dialog (else reusing main title)
+
+=item * I<callbacks>: (deprecated) functions called when something happen: complete advanced ok_disabled
+
+=back
+
+ask_from_ takes a list of entries with fields:
+
+=over 4
+
+=item * B<val>: reference to the value
+
+=item * B<label>: description
+
+=item * B<title>: a boolean: whether the label should be displayed as a title (see GNOME's HIG)
+
+=item * B<icon>: icon to put before the description
+
+=item * B<help>: tooltip
+
+=item * I<advanced>: (deprecated) wether it is shown in by default or only in advanced mode
+
+=item * B<focus_out>: function called when the entry is focused out
+
+=item * B<changed>: function called when the entry is modified
+
+=item * B<validate>: function called when "Ok" is pressed. If it returns false, this entry is focused, otherwise it quits
+
+=item * B<disabled>: function returning wether it should be disabled (grayed)
+
+=item * B<focus>: function returning wether it should be focused
+
+=item * B<alignment>: preferred alignment
+
+=item * B<do_not_expand>: do not eat all horizontal space
+
+=item * B<install_button>: if possible, use improved graphical style
+
+=item * B<gtk>: gtk preferences
+
+=item * B<type>:
+
+=over 4
+
+=item * B<button>: (with clicked or clicked_may_quit)
+
+I<type> defaults to button if clicked or clicked_may_quit is there.
+I<val> need not be a reference.
+If I<clicked_may_quit> return true, it's as if "Ok" was pressed.
+
+=item * B<label>:
+I<val> need not be a reference.
+I<type> defaults to label if val is not a reference.
+
+=item * B<bool>: (with "text" or "image" (which overrides text) giving an image filename)
+
+=item * B<range>: (with min, max, SpinButton)
+
+=item * B<combo>: (with list, not_edit, format)
+
+=item * B<list>: (with list, icon2f (aka icon), separator (aka tree), format (aka pre_format function),
+
+It has these optional parameters:
+
+=over 4
+
+=item * B<help>: can be a hash or a function,
+
+=item * B<tree_expanded>: boolean telling wether the tree should be wide open by default
+
+=item * B<quit_if_double_click>: boolean
+
+=item * B<allow_empty_list>: disables the special cases for 0 and 1 element lists
+
+=item * B<image2f>: a subroutine which takes a value of the list as parameter, and returns image_file_name
+
+=back
+
+=item * B<entry>: (the default) (with hidden)
+
+=item * B<expander>: (with text, expanded, message, children(a list of sub entries))
+
+=back
+
+=back
+
+=cut
+
+
sub ask_from_ {
my ($o, $common, $l) = @_;
ask_from_normalize($o, $common, $l);
@@ -654,4 +773,8 @@ sub interactive_help_sub_display_id {
&& sub { $o->ask_warn(N("Help"), $o->interactive_help_get_id($id)) };
}
+=back
+
+=cut
+
1;
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<ugtk3> enables to write GUIes using Gtk+3. It adds nice wrappers on top of
+L<Gtk3>, 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/'/&apos;/) 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/'/&apos;/) 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 = ('&' => '&amp;',
@@ -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;