Term-Menus
view release on metacpan or search on metacpan
lib/Term/Menus.pm view on Meta::CPAN
Reasons to use this module are:
=over 2
=item *
You have a list (or array) of items, and wish to present the user a simple
CMD enviroment menu to pick a single item and return that item as a scalar
(or simple string). Example:
use Term::Menus;
my @list=('First Item','Second Item','Third Item');
my $banner=" Please Pick an Item:";
my $selection=&pick(\@list,$banner);
print "SELECTION = $selection\n";
The user sees ==>
Please Pick an Item:
1 First Item
2 Second Item
3 Third Item
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 2 >-<ENTER>----------------------------------
The user sees ==>
SELECTION = Second Item
=item *
You have a large list of items and need scrolling capability:
use Term::Menus;
my @list=`ls -1 /bin`;
my $banner=" Please Pick an Item:";
my $selection=&pick(\@list,$banner);
print "SELECTION = $selection\n";
The user sees ==>
Please Pick an Item:
1 arch
2 ash
3 awk
4 basename
5 bash
6 cat
7 chgrp
8 chmod
9 chown
10 cp
a. Select All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--<ENTER>--------------------------------------
Please Pick an Item:
11 cpio
12 csh
13 cut
14 date
15 dd
16 df
17 echo
18 ed
19 egrep
20 env
a. Select All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 14 >-<ENTER>----------------------------------
The user sees ==>
SELECTION = date
=item *
You need to select multiple items and return the selected list:
use Term::Menus;
my %Menu_1=(
Item_1 => {
Text => "/bin Utility - ]Convey[",
Convey => [ `ls -1 /bin` ],
},
Select => 'Many',
Banner => "\n Choose a /bin Utility :"
);
my @selections=&Menu(\%Menu_1);
print "SELECTIONS = @selections\n";
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
3 /bin Utility - awk
4 /bin Utility - basename
5 /bin Utility - bash
6 /bin Utility - cat
7 /bin Utility - chgrp
8 /bin Utility - chmod
9 /bin Utility - chown
10 /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 3 >-<ENTER>----------------------------------
--< 7 >-<ENTER>----------------------------------
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
* 3 /bin Utility - awk
4 /bin Utility - basename
5 /bin Utility - bash
6 /bin Utility - cat
* 7 /bin Utility - chgrp
8 /bin Utility - chmod
9 /bin Utility - chown
10 /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< f >-<ENTER>----------------------------------
The user sees ==>
SELECTIONS = /bin Utility - awk /bin Utility - chgrp
=item *
You need sub-menus:
use Term::Menus;
my %Menu_2=(
Name => 'Menu_2',
Item_1 => {
Text => "]Previous[ is a ]Convey[ Utility",
Convey => [ 'Good','Bad' ]
},
Select => 'One',
Banner => "\n Choose an Answer :"
);
my %Menu_1=(
Name => 'Menu_1',
Item_1 => {
Text => "/bin/Utility - ]Convey[",
Convey => [ `ls -1 /bin` ],
Result => \%Menu_2,
},
Select => 'One',
Banner => "\n Choose a /bin Utility :"
);
my $selection=&Menu(\%Menu_1);
print "\n SELECTION=$selection\n";
The user sees ==>
Choose a /bin Utility :
1. /bin Utility - arch
2. /bin Utility - ash
3. /bin Utility - awk
4. /bin Utility - basename
5. /bin Utility - bash
6. /bin Utility - cat
7. /bin Utility - chgrp
8. /bin Utility - chmod
9. /bin Utility - chown
10. /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
Choose an Answer :
1 bash is a Good Utility
2 bash is a Bad Utility
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 1 >-<ENTER>----------------------------------
The user sees ==>
SELECTIONS = bash is a Good Utility
=item *
You have a large amount of text, or instructional information, and want
a I<banner only screen> that displays the banner only (no selections) and
that moves to the next screen/menu with just a press of the ENTER key.
Yet, you want to preserve selections from earlier menus, and/or return
to more menus after user completes reading the banner only screens.
You can also navigate backwards and forwards through these screens.
use Term::Menus:
my %Menu_1=(
Name => 'Menu_1',
Banner => "\n This is a BANNER ONLY display."
);
&Menu(\%Menu_1);
The user sees ==>
This is a BANNER ONLY display.
([ESC] to Quit) Press ENTER to continue ...
=item *
You want to use perl subroutines to create the text items and/or banner:
use Term::Menus;
sub create_items {
my $previous=shift;
lib/Term/Menus.pm view on Meta::CPAN
push @textlines, "$previous is a Bad Utility";
return @textlines;
## return value must be an array
## NOT an array reference
}
sub create_banner {
my $previous=shift;
return "\n Choose an Answer for $previous :"
## return value MUST be a string for banner
}
my %Menu_2=(
Name => 'Menu_2',
Item_1 => {
Text => "]Convey[",
Convey => "create_items(]Previous[)",
},
Select => 'One',
Banner => "create_banner(]Previous[)",
);
my %Menu_1=(
Name => 'Menu_1',
Item_1 => {
Text => "/bin/Utility - ]Convey[",
Convey => [ `ls -1 /bin` ],
Result => \%Menu_2,
},
Select => 'One',
Banner => "\n Choose a /bin Utility :"
);
my @selection=&Menu(\%Menu_1);
print "\n SELECTION=@selection\n";
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
3 /bin Utility - awk
4 /bin Utility - basename
5 /bin Utility - bash
6 /bin Utility - cat
7 /bin Utility - chgrp
8 /bin Utility - chmod
9 /bin Utility - chown
10 /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
Choose an Answer for bash :
1 bash is a Good Utility
2 bash is a Bad Utility
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 1 >-<ENTER>----------------------------------
The user sees ==>
SELECTION = bash is a Good Utility
=item *
You want to use anonymous subroutines to create the text items and/or banner
(see the more detailed treatment of anonymous subroutines and Term::Menus
macros in a later section of this documentation):
use Term::Menus;
my $create_items = sub {
my $previous=shift;
my @textlines=();
push @textlines, "$previous is a Good Utility";
push @textlines, "$previous is a Bad Utility";
return \@textlines;
## return value must an array reference
};
my $create_banner = sub {
my $previous=shift;
return "\n Choose an Answer for ]Previous[ :"
## return value MUST be a string for banner
};
my %Menu_2=(
Name => 'Menu_2',
Item_1 => {
Text => "]Convey[",
Convey => $create_items->(']Previous['), # Subroutine executed
# at runtime by Perl
# and result is passed
# to Term::Menus.
# Do not use this argument
# construct with Result =>
# elements because only Menu
# blocks or subroutines can
# be passed. (Unless the
# return item is itself
# a Menu configuration
# block [HASH] or an
# anonymous subroutine
# [CODE])
},
Select => 'One',
Banner => $create_banner, # Perl passes sub itself at runtime and
# execution is carried out by Term::Menus.
);
my %Menu_1=(
Name => 'Menu_1',
Item_1 => {
Text => "/bin/Utility - ]Convey[",
Convey => [ `ls -1 /bin` ],
Result => \%Menu_2,
},
Select => 'One',
Banner => "\n Choose a /bin Utility :"
);
my @selection=&Menu(\%Menu_1);
print "\n SELECTION=@selection\n";
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
3 /bin Utility - awk
4 /bin Utility - basename
5 /bin Utility - bash
6 /bin Utility - cat
7 /bin Utility - chgrp
8 /bin Utility - chmod
9 /bin Utility - chown
10 /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
Choose an Answer for bash :
1 bash is a Good Utility
2 bash is a Bad Utility
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 1 >-<ENTER>----------------------------------
The user sees ==>
SELECTION = bash is a Good Utility
=back
Usage questions should be directed to the Usenet newsgroup
comp.lang.perl.modules.
Contact me, Brian Kelly <Brian.Kelly@fullautosoftware.net>,
if you find any bugs or have suggestions for improvements.
=head2 What To Know Before Using
=over 2
=item *
There are two methods available with Term::Menus - &pick() and &Menu().
C<&Menu()> uses C<&pick()> - you can get the same results using
only
C<&Menu()>. However, if you need to simply pick one item from a single
list - use C<&pick()>. The syntax is simpler, and you'll write less code.
;-)
=item *
You'll need to be running at least Perl version 5.002 to use this
module.
=back
=head1 METHODS
=over 4
=item B<pick> - create a simple menu
$pick = &pick ($list|\@list|['list',...],[$Banner]);
lib/Term/Menus.pm view on Meta::CPAN
appearance, constitution and purpose. An element's syntax is as you would
expect it to be in perl - a key string pointing to an assocaited value: key
=> value. The following items list supported key names and ther associated
value types:
=over 4
=item
B<Text> => 'Char String consisting of ASCII Characters'
=over 2
The I<Text> element provides a customized descriptive string for the Item.
It is the text the user will see displayed, describing the selection.
Text => 'This is Item_1',
=back
=item
B<Convey> => [ List ] --or-- @List --or-- $Scalar --or-- 'ASCII String' --or-- Anonymous Subroutine --or-- Subroutine Reference --or-- Ordinary Subroutine (*Ordinary* subroutine calls need to be surrounded by quotes. DO NOT use quotes with anonymous ...
=over 2
The I<Convey> element has a twofold purpose; it provides for the contents
of the C<]Convey[> macro, and defines or contains the string or result that
is passed on to child menus - if any. Use of this configuration element is
I<optional>. If C<Convey> is not a list, then it's value is passed onto child
menus. If C<Convey> I<is> a list, then the Item selected is passed onto the
children - if any. It is important to note, I<when used>, that only the
resulting I<Convey> string - B<I<NOT>> the the Item C<Text> value or string,
is conveyed to child menus. When the C<Convey> element is not used, the
full Item C<Text> value B<is> conveyed to the children - if any. However, the
full contents of the C<Text> element is I<returned> as the I<Result> of the
operation when the user completes all menu activity. See the I<Macro> section
below for more information.
Convey => [ `ls -1` ],
B<NOTE:> When using anonymous subroutines or subroutine references, there may be situations where code populating the Convey item encounters an error or gets data that is empty or unsatisfactory for some reason, and there is a need to print a mes...
=back
=item
B<Default> => 'Char String' --or-- Perl regular expression - qr/.../
=over 2
The I<Default> element provides a means to pre-select certain elements,
as if the items were selected by the user. This can be done with two
constructs - simple string or pre-compiled regular expression.
Note: The C<Default> element is available only when the C<Select> element
is set to C<'Many'> - C<Select => 'Many',>
Default => 'base|chown',
Default => qr/base|chown/i,
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
3 /bin Utility - awk
* 4 /bin Utility - basename
5 /bin Utility - bash
6 /bin Utility - cat
7 /bin Utility - chgrp
8 /bin Utility - chmod
* 9 /bin Utility - chown
10 /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
=back
=item
B<Select> => 'One' --or-- 'Many'
=over 2
The ITEM LEVEL I<Select> element provides a means to inform Term::Menus
that the specific items of a single ITEM BLOCK (as opposed to full menu)
are subject to multiple selecting - or just single selection. This is
useful in particular for Directory Tree navigation - where files can
be multi-selected (or tagged), yet when a directory is selectedi, it
forces an immediate navigation and new menu - showing the contents of
the just selected directory.
B<NOTE:> See the B<RECURSIVELY CALLED MENUS> section for more information.
Select => 'More',
The user sees ==>
d 1 bin
d 2 blib
d 3 dist
d 4 inc
d 5 lib
d 6 Module
d 7 t
8 briangreat2.txt
* 9 ChangeLog
10 close.perl
a. Select All f. FINISH
___
49 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
=back
=item
B<Exclude> => 'Char String' --or-- Perl regular expression - qr/.../
=over 2
The I<Exclude> element provides a means to remove matching elements
from the Menu seen by the user. This element is useful only when the
C<]Convey[> macro is used to populate items. This can be done with two
constructs - simple string or pre-compiled regular expression.
Exclude => 'base|chown',
Exclude => qr/base|chown/i,
=back
=item
B<Include> => 'Char String' --or-- Perl regular expression - qr/.../
=over 2
The I<Include> element provides a means to create items filtered from a larger
list of potential items available via the C<]Convey[> macro. This element is
useful only when the C<]Convey[> macro is used to populate items. The
C<Exclude> element can be used in conjunction with C<Include> to further
refine the final list of items used to construct the menu. The C<Include>
element - when used - always takes presidence, and the C<Exclude> will be used
only on the C<Include> filtered results. This element can be used with
two value constructs - simple string or pre-compiled regular expression.
Include => 'base|chown',
Include => qr/base|chown/i,
=back
=item
B<Result> => \%Menu_2 --or -- "&any_method()",
=over 2
=item
I<Result> is an I<optional> element that also has two important uses:
=item
For selecting the child menu next in the chain of operation and conveyance,
Result => \%Menu_2,
--or--
=item
For building customized method arguements using C<&Menu()>'s built-in
macros.
=item
Result => "&any_method($arg1,\"]Selected[\",\"]Previous[\")",
B<NOTE:> I<ALWAYS> be sure to surround the subroutine or method calling
syntax with DOUBLE QUOTES. (You can use single quotes if you don't want
interpolation). Quotes are necessary because you're telling C<&Menu()> -
I<not> Perl - what method you want invoked. C<&Menu()> won't invoke the method
until after all other processing - where Perl will try to invoke it the first
time it encounters the line during runtime - lo----ng before a user gets a
chance to see or do I<anything>. B<BUT> - be sure I<B<NOT>> to use quotes
when assigning a child menu reference to the C<Result> value.
Again, I<Result> is an I<optional> element. The default behavior when
C<Result> is omitted from the Item Configuration element, is for the selection
to be returned to the C<&Menu()>'s calling script/module/app. If the C<Select>
element was set to C<'One'>, then that item is returned regardless of whether
the Perl structure receiving the output is an array or scalar. If there were
multiple selections - i.e., C<Select> is set to C<'Many'> - then, depending
on what structure is set for receiving the output, will determine whether
C<&Menu()> returns a list (i.e. - array), or I<reference> to an array.
=back
=item
B<Input> => 1 --or -- 0,
=over 2
=item
I<Input> is an I<optional> element that that is used with Term::Menus L<FORMS|/FORMS>:
lib/Term/Menus.pm view on Meta::CPAN
=back
=head3 Item Configuration Macros
Each Menu Item can utilize a very powerful set of configuration I<Macros>.
These constructs principally act as purveyors of information - from one
menu to another, from one element to another. There are currently three
available Macros:
=over 4
=item
B<]Convey[>
=over 2
C<]Convey[> is used in conjunction with the I<Convey> element (described)
earlier. It's purpose to "convey" or transport or carry a list item associated
with the C<Convey> element - and replace the C<]Convey[> Macro in the C<Text>
element value with that list item. The I<Convey> mechanism utilizing the
C<Convey> Macro is essentially an I<Item multiplier>. The entire contents of
the list associated with the I<Convey> element will be turned into it's own
C<Item> when the menu is displayed. Both ordinary and anonymous subroutines can be use to dynamically generate I<Convey> lists. (With I<]Convey[>, macros can be used only as subroutine arguments or in the body of anonymous subroutines - see other exa...
use Term::Menus;
my %Menu_1=(
Name => 'Menu_1',
Item_1 => {
Text => "/bin/Utility - ]Convey[",
Convey => [ `ls -1 /bin` ],
Result => \%Menu_2,
},
Select => 'One',
Banner => "\n Choose a /bin Utility :"
);
my @selections=&Menu(\%Menu_1);
print "SELECTIONS=@selections\n";
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
3 /bin Utility - awk
4 /bin Utility - basename
5 /bin Utility - bash
6 /bin Utility - cat
7 /bin Utility - chgrp
8 /bin Utility - chmod
9 /bin Utility - chown
10 /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
B<NOTE:> C<]C[> can be used as a shorthand for C<]Convey[>.
=back
=item
B<]Previous[>
=over 2
C<]Previous[> can be used in child menus. The C<]Previous[> Macro contains
the I<Selection> of the parent menu. Unlike the C<]Convey[> Macro, the
C<]Previous[> Macro can be used in both the C<Text> element value, and the
C<Result> element values (when constructing method calls):
The C<]Previous[> Macro can also be used in the Banner.
use Term::Menus;
my %Menu_2=(
Name => 'Menu_2',
Item_1 => {
Text => "]Previous[ is a ]Convey[ Utility",
Convey => [ 'Good','Bad' ]
},
Select => 'One',
Banner => "\n Choose an Answer :"
);
my %Menu_1=(
Name => 'Menu_1',
Item_1 => {
Text => "/bin/Utility - ]Convey[",
Convey => [ `ls -1 /bin` ],
Result => \%Menu_2,
},
Select => 'One',
Banner => "\n Choose a /bin Utility :"
);
my @selections=&Menu(\%Menu_1);
print "SELECTIONS=@selections\n";
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
3 /bin Utility - awk
4 /bin Utility - basename
5 /bin Utility - bash
6 /bin Utility - cat
7 /bin Utility - chgrp
8 /bin Utility - chmod
9 /bin Utility - chown
10 /bin Utility - cp
a. Select All c. Clear All f. FINISH
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
Choose an Answer :
1 bash is a Good Utility
2 bash is a Bad Utility
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 1 >-<ENTER>----------------------------------
The user sees ==>
SELECTIONS = bash is a Good Utility
B<NOTE:> C<]P[> can be used as a shorthand for C<]Previous[>.
=back
=item
B<]Previous[{> <I<Menu_Name>> B<}> i.e. Explicit Named Macro
=over 2
C<]Previous[{Menu_Name}> (i.e. Explicit Named Macros) can be used in child menus.
The C<]Previous[{Menu_Name}> Macro contains the I<Selection> of any preceding menu
specified with the C<Menu_Name> string. The C<]Previous[{Menu_Name}> follows the
same conventions as the C<]Previous[> Macro - but enables access to the selection
of i<any> preceding menu. This is very useful for Menu trees more than two levels
deep.
The C<]Previous[{Menu_Name}> Macro can also be used in the Banner.
use Term::Menus;
my %Menu_3=(
Name => 'Menu_3',
Item_1 => {
Text => "]Convey[ said ]P[{Menu_1} is a ]Previous[ Utility!",
Convey => [ 'Bob','Mary' ]
},
Select => 'One',
Banner => "\n Who commented on ]Previous[{Menu_1}? :"
);
my %Menu_2=(
Name => 'Menu_2',
Item_1 => {
Text => "]Previous[ is a ]C[ Utility",
Convey => [ 'Good','Bad' ],
Result => \%Menu_3,
},
Select => 'One',
Banner => "\n Is ]P[ Good or Bad? :"
);
my %Menu_1=(
Name => 'Menu_1',
Item_1 => {
Text => "/bin/Utility - ]Convey[",
Convey => [ `ls -1 /bin` ],
Result => \%Menu_2,
},
Select => 'One',
Banner => "\n Choose a /bin Utility :"
);
my @selections=&Menu(\%Menu_1);
print "SELECTIONS=@selections\n";
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
3 /bin Utility - awk
4 /bin Utility - basename
5 /bin Utility - bash
6 /bin Utility - cat
7 /bin Utility - chgrp
8 /bin Utility - chmod
9 /bin Utility - chown
10 /bin Utility - cp
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
Is bash Good or Bad? :
1 bash is a Good Utility
2 bash is a Bad Utility
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 1 >-<ENTER>----------------------------------
Who commented on bash? :
1 Bob said bash is a Good Utility!
2 Mary said bash is a Good Utility!
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 2 >-<ENTER>----------------------------------
The user sees ==>
SELECTIONS = Mary said bash is a Good Utility!
B<NOTE:> C<]P[> can be used as a shorthand for C<]Previous[>.
C<]P[{Menu_Name}> can be used as a shorthand for C<]Previous[{Menu_Name}>.
C<]C[> can be used as a shorthand for C<]Convey[>.
=back
=item
B<]Selected[>
=over 2
C<]Selected[> can only be used in a I<terminal> menu. B<(> I<A terminal menu is
the last menu in the chain, or the last menu the user sees. It is the menu that
defines the> C<Result> I<element with a method> C<Result =E<gt> &any_method()>,
I<or does not have a> C<Result> I<element included or defined.> B<)>
C<]Selected[> is used to pass the selection of the I<current> menu to the
C<Result> element method of the current menu:
use Term::Menus;
sub selected { print "\n SELECTED ITEM = $_[0]\n" }
lib/Term/Menus.pm view on Meta::CPAN
"]I[{'input_example',4}",
"]I[{'input_example',5}",
"]I[{'input_example',6}" },
};
my @output=Menu($input_example);
print "\n OUTPUT=@output\n";
=head3 Input Macro -> Banner
The Input Macro syntax for Banner is as follows:
]I[{<identity_number>,'<default_input>',<length_of_input_box>}
*NOTE* => Be sure you have a RESULT C<]I[> macro for every BANNER C<]I[> macro you use!
=head3 Input Macro -> Result
The Input Macro syntax for Result is as follows:
]I[{'<menu_name>','<identity_number>'}
=head3 Output Macro -> Banner
The Output Macro syntax for Banner is as follows:
]O[{<identity_number>,'<name_of_method_to_operate_on_character_input>'}
=head1 USAGE and NAVIGATION
Usage of C<&pick()> and/or C<&Menu()> during the runtime of a script in which
one or both are included, is simple and intuitive. Nearly everything the end
user needs in terms of instruction is included on-screen. The
script-writer/developer/programmer can also include whatever instructions s/he
deems necessary and/or helpful in the customizable C<Banner> (as described
above). There is however, one important feature about using C<&Menu()> with
sub-menus that's important to know about.
=head2 Forward ' B<E<gt>> ' and Backward ' B<E<lt>> ' Navigation
When working with more than one C<&Menu()> screen, it's valuable to know how
to navigate back and forth between the different C<&Menu()> levels/layers. For
example, above was illustrated the output for two layers of menus - a parent
and a child:
=over 4
The user sees ==>
Choose a /bin Utility :
1. /bin Utility - arch
2. /bin Utility - ash
3. /bin Utility - awk
4. /bin Utility - basename
5. /bin Utility - bash
6. /bin Utility - cat
7. /bin Utility - chgrp
8. /bin Utility - chmod
9. /bin Utility - chown
10. /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
The user sees ==>
Choose an Answer :
1 bash is a Good Utility
2 bash is a Bad Utility
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
In the above example, suppose that the user "fat-fingered" his/her
choice, and really didn't want to "bash" bash, but wanted to bash
awk instead. Is restarting the whole script/application now necessary?
Suppose it was a process that had run overnight, and the user is seeing
this menu through fogged glasses from the steam rising out of their
morning coffee? Having to run the whole job again would not be welcome news
for the BOSS. THANKFULLY, navigation makes this situation avoidable.
All the user would have to do is type ' B<E<lt>> ' to go backward to the
previous menu, and ' B<E<gt>> ' to go forward to the next menu (assuming there
is one in each case):
The user sees ==>
Choose an Answer :
1 bash is a Good Utility
2 bash is a Bad Utility
(Press [F1] for HELP)
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< > >-<ENTER>-----------------------------
The user sees ==>
Choose a /bin Utility :
1 /bin Utility - arch
2 /bin Utility - ash
3 /bin Utility - awk
4 /bin Utility - basename
- 5 /bin Utility - bash
6 /bin Utility - cat
7 /bin Utility - chgrp
8 /bin Utility - chmod
9 /bin Utility - chown
10 /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
Note in the above example the Dash ' B<-> ' in front of item B<5.> This informs
the user that s/he had previously selected this item. To clear the selection,
the user would simply choose item B<5> again. This effectively deletes the
previous choice and restores the menu for a new selection. If the user was
satisfied with the choice, and was simply double checking thier selection, they
simply repeat the navigation process by typing ' B<E<gt>> ' - then <ENTER>
-
and returning to the child menu they left.
If the child menu was a I<multiple-selection> menu, and the user had made some
selections before navigating back to the parent menu, the user would see a
' B<+> ' rather than a ' B<-> '. This informs the user that selections were
made in the child menu.
Choose a /bin Utility :
1. /bin Utility - arch
2. /bin Utility - ash
3. /bin Utility - awk
4. /bin Utility - basename
+ 5. /bin Utility - bash
6. /bin Utility - cat
7. /bin Utility - chgrp
8. /bin Utility - chmod
9. /bin Utility - chown
10. /bin Utility - cp
a. Select All c. Clear All f. FINISH
___
93 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
=back
=head2 View Sorted Items ' B<%> '
When working with numerous items in a single menu, it may be desirable to see
the set of choices organized in either descending or reverse acscii order.
Term::Menus provides this feature with the I<Percent> ' B<%> ' key. Simply
type ' B<%> ' and the items will be sorted in descending ascii order. Type
' B<%> ' again, and you will see the items reverse sorted. Assume that we have
the following menus.
=over 4
The user sees ==>
Choose a /bin Utility :
* 1 [.exe
* 2 2to3
3 2to3-3.2
* 4 411toppm.exe
5 a2p.exe
6 aaflip.exe
7 aclocal
* 8 aclocal-1.10
9 aclocal-1.11
* 10 aclocal-1.12
a. Select All c. Clear All f. FINISH
___
1925 Total Choices |_v_| Scroll with ARROW keys [F1] for HELP
([ESC] to Quit) PLEASE ENTER A CHOICE:
--< % >-<ENTER>----------------------------------
The user sees ==>
Choose a /bin Utility :
* 2. 2to3
3. 2to3-3.2
* 4. 411toppm.exe
759. FvwmCommand.exe
1650. Ted.exe
1782. WPrefs.exe
1785. X
1889. XWin.exe
1808. Xdmx.exe
1815. Xephyr.exe
a. Select All c. Clear All f. FINISH
( run in 0.531 second using v1.01-cache-2.11-cpan-5511b514fd6 )