3
UI::Dialog::Screen::Menu
7
use UI::Dialog::Screen::Menu;
9
# $d is an existing instance of UI::Dialog
11
my $screen = new UI::Dialog::Screen::Menu ( dialog => $d );
12
$screen->add_menu_item("This is the label", sub { print "Hello\n"; });
14
# $rv is 0 if the user canceled, 1 if any menu item was selected.
15
my $rv = $screen->run();
19
UI::Dialog::Screen::Menu is a helper class which enables a clean and
20
modular code flow for menu driven applications using UI::Dialog. Using
21
callbacks assigned to menu items, a reactionary model to scripting with
22
UI::Dialog becomes rapidly easy.
26
UI::Dialog::Screen::Menu is actually "external" to the UI::Dialog core
27
usage. The class simply wraps around an existing UI::Dialog instance
28
for rendering a menu-driven flow of screens.
30
Using this class, you define a number of screen instances and assign
31
callbacks to each of the menu items. Once defined, simply call B<run()>
32
(or B<loop()> to execute B<run()> indefinitely). When a user selects
33
one of the menu items, the assigned function will be executed. From
34
within those functions, simply call other UI::Dialog::Screen::Menu
35
instances and that's how you branch your user's experience from one
36
screen to the next. See the B<EXAMPLES>
56
=head2 new( %options )
64
# Have UI::Dialog::Screen::Menu use an existing UI::Dialog instance
65
# to render the user interface.
66
my $s = new( dialog => $d );
68
# Also accepts UI::Dialog constructor arguments, so that it can create
69
# it's own instance of UI::Dialog if none is provided.
70
my $s = new( title => 'Default Title', backtitle => 'Backtitle',
71
width => 65, height => 20, listheight => 5,
72
order => [ 'zenity', 'xdialog', 'gdialog' ] );
80
This is the Class Constructor method. It accepts a list of key => value pairs
81
and uses them as the defaults when interacting with the various widgets.
89
A blessed object reference of the UI::Dialog::Screen::Menu class.
95
The (...)'s after each option indicate the default for the option. An * denotes
96
support by all the widget methods on a per-use policy defaulting to the values
97
decided during object creation.
101
=item B<dialog = UI::Dialog> (undef)
103
=item B<debug = 0,1,2> (0)
105
=item B<order = [ zenity, xdialog, gdialog, kdialog, cdialog, whiptail, ascii ]> (as indicated)
107
=item B<PATH = [ /bin, /usr/bin, /usr/local/bin, /opt/bin ]> (as indicated)
109
=item B<backtitle = "backtitle"> ('') *
111
=item B<title = "title"> ('') *
113
=item B<beepbefore = 0,1> (0) *
115
=item B<beepafter = 0,1> (0) *
117
=item B<height = \d+> (20) *
119
=item B<width = \d+> (65) *
121
=item B<listheight = \d+> (5) *
145
Render the screen menu immediately. This method blocks until the user
146
input has been received and acted upon.
154
TRUE if the user selected an item from the menu, FALSE otherwise.
176
Calls the B<run()> method immediately. Once B<run()> completes it's
177
execution, the B<loop()> decides whether or not to display again. If
178
the return value of run() is TRUE, the B<loop()> will continue. If the
179
use pressed Cancel (or Escape) or any other action other than one of
180
the menu items; the B<loop()> will end. The B<loop()> will also end
181
if the B<break_loop()> method is called.
189
TRUE if the user selected an item from the menu, FALSE otherwise.
203
if ($s->is_looping()) {
204
print "Currently in a UI::Dialog::Screen::Menu loop\n";
213
Returns TRUE if the given screen is in a menu B<loop()>, FALSE
244
Flags the screen menu to stop looping. This does not close or
245
otherwise clear the screen. This simply flags the loop to exit
246
at the end of it's current run.
260
=head1 SCREEN METHODS
262
=head2 add_menu_item( )
270
my $index = $s->add_menu_item( "Menu Item Label", \%some_function );
278
Append a new item to the menu list.
286
Returns the list index (starting from 0) of the item that was just
287
appended to the list.
293
=head2 get_menu_items( )
301
my @items = $s->get_menu_items();
309
Returns an array of hashrefs. Each hash contains a "label" and
310
"func" key/value pairs.
324
=head2 del_menu_item( )
332
my $old_item = $d->del_menu_item( $index );
340
Remove a specific item from the menu, addressed by it's list index
341
(starting from 0), and return the menu item as a hashref.
349
A HASH containing the 'label' and 'func' of the menu item that was
350
just removed from the menu list.
356
=head2 set_menu_item( )
364
# Modify the 'label' and 'func' for a specific menu item
365
my $original_item = $s->set_menu_item( $index, $label, $func );
367
# Modify just the label of a menu item
368
my $original_item = $s->set_menu_item( $index, $label, undef );
370
# Modify just the func of a menu item
371
my $original_item = $s->set_menu_item( $index, undef, $func );
373
# Effectively do nothing
374
my $original_item = $s->set_menu_item( $index, undef, undef );
382
Modify the menu item addressed by the given index (starting from 0).
383
If the 'label' and/or 'func' arguments are undef then the previous
392
A HASH of the original values for the modified menu item.
400
The below example assumed that $d is an instances of UI::Dialog.
402
# Create our first screen
403
my $s1 = new UI::Dialog::Screen::Menu ( dialog => $d );
404
$s1->add_menu_item( "Just an option", \&some_function );
406
# Add a menu item that updates it's own label every time
410
( "Counter: ".$counter,
412
my ($self,$dialog,$index) = @_;
414
$self->set_menu_item($index,"Counter: ".$counter, undef);
418
# Create a second screen
419
my $s2 = new UI::Dialog::Screen::Menu ( dialog => $d );
420
$s2->add_menu_item( "Another item", \&another_function );
422
# Link the second screen to an option of the first
423
$s1->add_menu_item( "Goto Screen 2", sub { $s2->loop(); } );
425
# Start a menu loop and actually display the first screen
428
Users can get to second menu from selecting the third item on the first
429
menu screen. As long as the user continues to select items from the
430
second menu, it will continue to loop. If the user cancels the second
431
screen, the will return to the first which will itself continue to loop.
444
UI::Dialog::Backend::ASCII
445
UI::Dialog::Backend::CDialog
446
UI::Dialog::Backend::GDialog
447
UI::Dialog::Backend::KDialog
448
UI::Dialog::Backend::Nautilus
449
UI::Dialog::Backend::Whiptail
450
UI::Dialog::Backend::XDialog
451
UI::Dialog::Backend::XOSD
452
UI::Dialog::Backend::Zenity
460
dialog(1), whiptail(1), zenity(1), gdialog(1), Xdialog(1),
461
osd_cat(1), kdialog(1) and nautilus(1)
467
Please email the author with any bug reports. Include the name of the
468
module in the subject line.
472
Kevin C. Krinke, E<lt>kevin@krinke.caE<gt>
474
=head1 COPYRIGHT AND LICENSE
476
Copyright (C) 2013 Kevin C. Krinke <kevin@krinke.ca>
478
This library is free software; you can redistribute it and/or
479
modify it under the terms of the GNU Lesser General Public
480
License as published by the Free Software Foundation; either
481
version 2.1 of the License, or (at your option) any later version.
483
This library is distributed in the hope that it will be useful,
484
but WITHOUT ANY WARRANTY; without even the implied warranty of
485
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
486
Lesser General Public License for more details.
488
You should have received a copy of the GNU Lesser General Public
489
License along with this library; if not, write to the Free Software
490
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
added
removed
.pc/FixSpellingAndManDescription.diff/lib/UI/Dialog/Screen/Menu.pod
