.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "UI::Dialog::Screen::Menu 3pm"
.TH UI::Dialog::Screen::Menu 3pm "2018-10-27" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UI::Dialog::Screen::Menu \- wrapper to screen dialogs.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use UI::Dialog::Screen::Menu;
\&
\&  # $d is an existing instance of UI::Dialog
\&
\&  my $screen = new UI::Dialog::Screen::Menu ( dialog => $d );
\&  $screen\->add_menu_item("This is the label", sub { print "Hello\en"; });
\&
\&  # $rv is 0 if the user canceled, 1 if any menu item was selected.
\&  my $rv = $screen\->run();
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
UI::Dialog::Screen::Menu is a helper class which enables a clean and
modular code flow for menu driven applications using UI::Dialog. Using
callbacks assigned to menu items, a reactionary model to scripting with
UI::Dialog becomes rapidly easy.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
UI::Dialog::Screen::Menu is actually \*(L"external\*(R" to the UI::Dialog core
usage. The class simply wraps around an existing UI::Dialog instance
for rendering a menu-driven flow of screens.
.PP
Using this class, you define a number of screen instances and assign
callbacks to each of the menu items. Once defined, simply call \fB\f(BIrun()\fB\fR
(or \fB\f(BIloop()\fB\fR to execute \fB\f(BIrun()\fB\fR indefinitely). When a user selects
one of the menu items, the assigned function will be executed. From
within those functions, simply call other UI::Dialog::Screen::Menu
instances and that's how you branch your user's experience from one
screen to the next. See the \fB\s-1EXAMPLES\s0\fR
.SH "EXPORT"
.IX Header "EXPORT"
.RS 2
None
.RE
.SH "INHERITS"
.IX Header "INHERITS"
.RS 2
None
.RE
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .SS "new( %options )"
.el .SS "new( \f(CW%options\fP )"
.IX Subsection "new( %options )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 3
\& # Have UI::Dialog::Screen::Menu use an existing UI::Dialog instance
\& # to render the user interface.
\& my $s = new( dialog => $d );
\&
\& # Also accepts UI::Dialog constructor arguments, so that it can create
\& # it\*(Aqs own instance of UI::Dialog if none is provided.
\& my $s = new( title => \*(AqDefault Title\*(Aq, backtitle => \*(AqBacktitle\*(Aq,
\&              width => 65, height => 20, listheight => 5,
\&              order => [ \*(Aqzenity\*(Aq, \*(Aqxdialog\*(Aq, \*(Aqgdialog\*(Aq ] );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This is the Class Constructor method. It accepts a list of key => value pairs
and uses them as the defaults when interacting with the various widgets.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
A blessed object reference of the UI::Dialog::Screen::Menu class.
.RE
.RE
.RS 4
.RE
.IP "\s-1OPTIONS\s0" 4
.IX Item "OPTIONS"
The (...)'s after each option indicate the default for the option. An * denotes
support by all the widget methods on a per-use policy defaulting to the values
decided during object creation.
.RS 4
.IP "\fBdialog = UI::Dialog\fR (undef)" 6
.IX Item "dialog = UI::Dialog (undef)"
.PD 0
.IP "\fBdebug = 0,1,2\fR (0)" 6
.IX Item "debug = 0,1,2 (0)"
.IP "\fBorder = [ zenity, xdialog, gdialog, kdialog, cdialog, whiptail, ascii ]\fR (as indicated)" 6
.IX Item "order = [ zenity, xdialog, gdialog, kdialog, cdialog, whiptail, ascii ] (as indicated)"
.IP "\fB\s-1PATH\s0 = [ /bin, /usr/bin, /usr/local/bin, /opt/bin ]\fR (as indicated)" 6
.IX Item "PATH = [ /bin, /usr/bin, /usr/local/bin, /opt/bin ] (as indicated)"
.ie n .IP "\fBbacktitle = ""backtitle""\fR ('') *" 6
.el .IP "\fBbacktitle = ``backtitle''\fR ('') *" 6
.IX Item "backtitle = backtitle ('') *"
.ie n .IP "\fBtitle = ""title""\fR ('') *" 6
.el .IP "\fBtitle = ``title''\fR ('') *" 6
.IX Item "title = title ('') *"
.IP "\fBbeepbefore = 0,1\fR (0) *" 6
.IX Item "beepbefore = 0,1 (0) *"
.IP "\fBbeepafter = 0,1\fR (0) *" 6
.IX Item "beepafter = 0,1 (0) *"
.IP "\fBheight = \ed+\fR (20) *" 6
.IX Item "height = d+ (20) *"
.IP "\fBwidth = \ed+\fR (65) *" 6
.IX Item "width = d+ (65) *"
.IP "\fBlistheight = \ed+\fR (5) *" 6
.IX Item "listheight = d+ (5) *"
.RE
.RS 4
.RE
.PD
.SH "STATE METHODS"
.IX Header "STATE METHODS"
.SS "run( )"
.IX Subsection "run( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $rv = $s\->run();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Render the screen menu immediately. This method blocks until the user
input has been received and acted upon.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
\&\s-1TRUE\s0 if the user selected an item from the menu, \s-1FALSE\s0 otherwise.
.RE
.RE
.RS 4
.RE
.SS "loop( )"
.IX Subsection "loop( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $s\->loop();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Calls the \fB\f(BIrun()\fB\fR method immediately. Once \fB\f(BIrun()\fB\fR completes it's
execution, the \fB\f(BIloop()\fB\fR decides whether or not to display again. If
the return value of \fIrun()\fR is \s-1TRUE,\s0 the \fB\f(BIloop()\fB\fR will continue. If the
use pressed Cancel (or Escape) or any other action other than one of
the menu items; the \fB\f(BIloop()\fB\fR will end. The \fB\f(BIloop()\fB\fR will also end
if the \fB\f(BIbreak_loop()\fB\fR method is called.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
\&\s-1TRUE\s0 if the user selected an item from the menu, \s-1FALSE\s0 otherwise.
.RE
.RE
.RS 4
.RE
.SS "is_looping( )"
.IX Subsection "is_looping( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 3
\& if ($s\->is_looping()) {
\&     print "Currently in a UI::Dialog::Screen::Menu loop\en";
\& }
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Returns \s-1TRUE\s0 if the given screen is in a menu \fB\f(BIloop()\fB\fR, \s-1FALSE\s0
otherwise.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a single \s-1SCALAR.\s0
.RE
.RE
.RS 4
.RE
.SS "break_loop( )"
.IX Subsection "break_loop( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $s\->break_loop();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Flags the screen menu to stop looping. This does not close or
otherwise clear the screen. This simply flags the loop to exit
at the end of it's current run.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
None.
.RE
.RE
.RS 4
.RE
.SH "SCREEN METHODS"
.IX Header "SCREEN METHODS"
.SS "add_menu_item( )"
.IX Subsection "add_menu_item( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $index = $s\->add_menu_item( "Menu Item Label", \e%some_function );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Append a new item to the menu list.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
Returns the list index (starting from 0) of the item that was just
appended to the list.
.RE
.RE
.RS 4
.RE
.SS "get_menu_items( )"
.IX Subsection "get_menu_items( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my @items = $s\->get_menu_items();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Returns an array of hashrefs. Each hash contains a \*(L"label\*(R" and
\&\*(L"func\*(R" key/value pairs.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
An \s-1ARRAY.\s0
.RE
.RE
.RS 4
.RE
.SS "del_menu_item( )"
.IX Subsection "del_menu_item( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $old_item = $d\->del_menu_item( $index );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Remove a specific item from the menu, addressed by it's list index
(starting from 0), and return the menu item as a hashref.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
A \s-1HASH\s0 containing the 'label' and 'func' of the menu item that was
just removed from the menu list.
.RE
.RE
.RS 4
.RE
.SS "set_menu_item( )"
.IX Subsection "set_menu_item( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 2
\& # Modify the \*(Aqlabel\*(Aq and \*(Aqfunc\*(Aq for a specific menu item
\& my $original_item = $s\->set_menu_item( $index, $label, $func );
\&
\& # Modify just the label of a menu item
\& my $original_item = $s\->set_menu_item( $index, $label, undef );
\&
\& # Modify just the func of a menu item
\& my $original_item = $s\->set_menu_item( $index, undef, $func );
\&
\& # Effectively do nothing
\& my $original_item = $s\->set_menu_item( $index, undef, undef );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Modify the menu item addressed by the given index (starting from 0).
If the 'label' and/or 'func' arguments are undef then the previous
value is kept.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
A \s-1HASH\s0 of the original values for the modified menu item.
.RE
.RE
.RS 4
.RE
.SH "EXAMPLE USAGE"
.IX Header "EXAMPLE USAGE"
The below example assumed that \f(CW$d\fR is an instances of UI::Dialog.
.PP
.Vb 3
\& # Create our first screen
\& my $s1 = new UI::Dialog::Screen::Menu ( dialog => $d );
\& $s1\->add_menu_item( "Just an option", \e&some_function );
\&
\& # Add a menu item that updates it\*(Aqs own label every time
\& # it is selected.
\& our $counter = 0;
\& $s1\->add_menu_item
\&  ( "Counter: ".$counter,
\&    sub {
\&      my ($self,$dialog,$index) = @_;
\&      $counter++;
\&      $self\->set_menu_item($index,"Counter: ".$counter, undef);
\&    }
\&  );
\&
\& # Create a second screen
\& my $s2 = new UI::Dialog::Screen::Menu ( dialog => $d );
\& $s2\->add_menu_item( "Another item", \e&another_function );
\&
\& # Link the second screen to an option of the first
\& $s1\->add_menu_item( "Goto Screen 2", sub { $s2\->loop(); } );
\&
\& # Start a menu loop and actually display the first screen
\& $s1\->loop();
.Ve
.PP
Users can get to second menu from selecting the third item on the first
menu screen. As long as the user continues to select items from the
second menu, it will continue to loop. If the user cancels the second
screen, the will return to the first which will itself continue to loop.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\s-1PERLDOC\s0" 2
.IX Item "PERLDOC"
.Vb 10
\& UI::Dialog
\& UI::Dialog::GNOME
\& UI::Dialog::KDE
\& UI::Dialog::Console
\& UI::Dialog::Screen::Druid
\& UI::Dialog::Backend
\& UI::Dialog::Backend::ASCII
\& UI::Dialog::Backend::CDialog
\& UI::Dialog::Backend::GDialog
\& UI::Dialog::Backend::KDialog
\& UI::Dialog::Backend::Nautilus
\& UI::Dialog::Backend::Whiptail
\& UI::Dialog::Backend::XDialog
\& UI::Dialog::Backend::XOSD
\& UI::Dialog::Backend::Zenity
.Ve
.IP "\s-1MAN FILES\s0" 2
.IX Item "MAN FILES"
.Vb 2
\& dialog(1), whiptail(1), zenity(1), gdialog(1), Xdialog(1),
\& osd_cat(1), kdialog(1) and nautilus(1)
.Ve
.SH "BUGS"
.IX Header "BUGS"
Please email the author with any bug reports. Include the name of the
module in the subject line.
.SH "AUTHOR"
.IX Header "AUTHOR"
Kevin C. Krinke, <kevin@krinke.ca>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.Vb 1
\& Copyright (C) 2004\-2016  Kevin C. Krinke <kevin@krinke.ca>
\&
\& This library is free software; you can redistribute it and/or
\& modify it under the terms of the GNU Lesser General Public
\& License as published by the Free Software Foundation; either
\& version 2.1 of the License, or (at your option) any later version.
\&
\& This library is distributed in the hope that it will be useful,
\& but WITHOUT ANY WARRANTY; without even the implied warranty of
\& MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
\& Lesser General Public License for more details.
\&
\& You should have received a copy of the GNU Lesser General Public
\& License along with this library; if not, write to the Free Software
\& Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111\-1307 USA
.Ve