diff options
| -rw-r--r-- | perl-install/interactive.pm | 275 | ||||
| -rw-r--r-- | perl-install/ugtk3.pm | 180 |
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/'/'/) 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; |