.\" 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::Druid 3pm"
.TH UI::Dialog::Screen::Druid 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::Druid \- wrapper to screen dialogs.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use UI::Dialog::Screen::Druid;
\&
\&  # $d is an existing instance of UI::Dialog
\&
\&  my $druid = new UI::Dialog::Screen::Druid ( dialog => $d );
\&  $druid\->add_yesno_step(\*(Aqsomename\*(Aq,"Ask the user a y/n question?");
\&  $druid\->add_input_step
\&    ( \*(Aqanothertag\*(Aq,"Tell me something:",
\&      "Hello World: {{somename}}"
\&    );
\&  my (%answers) = $druid\->perform();
\&  if ($answers{aborted}) {
\&    die "user canceled at step: ".$answers{key}."\en";
\&  }
\&
\&  # %answers contains all the responses, keyed by the first argument
\&  # used in the add_*_step() methods.
\&  print $answers{anothertag}."\en";
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
UI::Dialog::Screen::Druid is a helper class which enables a clean and
modular code flow for menu driven applications using UI::Dialog. Using
a simple \*(L"question\*(R" format, tucked into a queue; developers can ask
a series of questions and receive back a \s-1HASH\s0 (or \s-1HASHREF\s0) of all the
user input keyed by the first argument to the add_*\fI_step()\fR methods.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
UI::Dialog::Screen::Druid is actually \*(L"external\*(R" to the UI::Dialog core
usage. The class simply wraps around an existing UI::Dialog instance
for rendering a druid-walkthrough series of dialogs.
.PP
Using this class, you define one (or more) druid instances and assign
tags and helpful text to questions. Once defined, simply call \fB\f(BIperform()\fB\fR
and receive the resulting \s-1HASH\s0 (or \s-1HASHREF\s0).
.PP
If the user aborts (presses <\s-1ESC\s0>) the druid performance, a simple
hash containing two key/value pairs is returned and resembles the
following:
.PP
.Vb 1
\& { aborted => 1, key => "tagNameOfAbortedStep" }
.Ve
.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::Druid use an existing UI::Dialog instance
\& # to render the user interface.
\& my $druid = 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 $druid = 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::Druid 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 "DRUID METHODS"
.IX Header "DRUID METHODS"
.SS "add_yesno_step( )"
.IX Subsection "add_yesno_step( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $druid\->add_yesno_step( "yesnotag", "Yes/no question?" );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Append a new \fB\f(BIyesno()\fB\fR dialog step to the druid performance, keyed
by the first argument.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
Nothing
.RE
.RE
.RS 4
.RE
.SS "add_input_step( )"
.IX Subsection "add_input_step( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $druid\->add_input_step( "inputtag", "Helpful text", "default text" );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Append a new \fB\f(BIinputbox()\fB\fR dialog step to the druid performance, keyed
by the first argument.
.Sp
A unique property to this druid step in particular is that the default
text (the third arguement) goes through a semi-templating system. By
using \fB{{keytag}}\fR within the default text string, when the input
question is posed to the user, the \fB{{keytag}}\fR string is replaced
with the user's response to a prior question keyed as \fBkeytag\fR. For
example:
.Sp
.Vb 10
\& $druid\->add_input_step
\&   ( "user_name",
\&     "Tell me the user name you\*(Aqd like.",
\&     "$ENV{USER}"
\&   );
\& $druid\->add_input_step
\&   ( "another_q",
\&     "What is the email address you\*(Aqd like?",
\&     "{{user_name}}@example.com"
\&   );
.Ve
.Sp
When the above is performed, assuming the user entered \*(L"boring\*(R" for
the \fIuser_name\fR question; the suggested (default) email address would
become \fIboring@example.com\fR.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
Nothing
.RE
.RE
.RS 4
.RE
.SS "add_password_step( )"
.IX Subsection "add_password_step( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $druid\->add_password_step( "passwordtag", "Helpful text." );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Append a new \fB\f(BIpassword()\fB\fR dialog step to the druid performance, keyed
by the first argument.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
Nothing
.RE
.RE
.RS 4
.RE
.SS "add_menu_step( )"
.IX Subsection "add_menu_step( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $druid\->add_menu_step( "menutag", "Helpful text", [qw|item0 item1|] );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Append a new \fB\f(BImenu()\fB\fR dialog step to the druid performance, keyed
by the first argument.
.Sp
The third argument is an \s-1ARRAYREF\s0 containing the options the user
can select from. This is not the same as the \fImenu()\fR method's \fBlist\fR
argument. Whatever is supplied is what is returned as the response
for the keyed question. In the above \fB\s-1EXAMPLE\s0\fR the user would be
presented with two options in a menu; \*(L"item0\*(R" and \*(L"item1\*(R". Upon
selecting one of those two options; the \fI\f(CI%answers\fI\fR \s-1HASH\s0 would
contain \fImenutag =\fR \*(L"item0\*(R"> (if the user selected \*(L"item0\*(R" of course).
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
Nothing
.RE
.RE
.RS 4
.RE
.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::Menu
\& 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