.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UI::Dialog::Backend 3pm"
.TH UI::Dialog::Backend 3pm "2004-08-01" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
UI::Dialog::Backend
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  use UI::Dialog::Backend;
\&  BEGIN {
\&    use vars qw( @ISA );
\&    @ISA = qw( UI::Dialog::Backend );
\&  }
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
UI::Dialog::Backend is simply a collection of primarily internal methods.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
While this module is inherited by all UI::Dialog backend modules, this module
itself is not meant for direct usage. The \*(L"\s-1STATE\s0 \s-1METHODS\s0\*(R" and \*(L"\s-1UTILITY\s0 \s-1METHODS\s0\*(R"
documentation is applicable to all backends thus rendering the \s-1POD\s0 for this class
more important to the end-programmer than the usage of the class itself.
.SH "EXPORT"
.IX Header "EXPORT"
.RS 2
None
.RE
.SH "INHERITS"
.IX Header "INHERITS"
.RS 2
None
.RE
.SH "BACKEND EXTENSIONS"
.IX Header "BACKEND EXTENSIONS"
.Sh "nautilus"
.IX Subsection "nautilus"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my @paths = $d\->nautilus\->paths();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This method gives access to the UI::Dialog::Backend::Nautilus class. This will
automagically try to load the UI::Dialog::Backend::Nautilus module or it will
silently fail.
.RE
.RE
.RS 4
.RE
.Sh "xosd"
.IX Subsection "xosd"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $d\->xosd\->line( "a line of text on your screen" );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This method gives access to the UI::Dialog::Backend::XOSD class. This will
automagically try to load the UI::Dialog::Backend::XOSD module or it will
silently fail.
.RE
.RE
.RS 4
.RE
.SH "STATE METHODS"
.IX Header "STATE METHODS"
.Sh "attr( )"
.IX Subsection "attr( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 2
\& my $value = $self\->attr(\(aqlistheight\(aq);
\& my $new_value = $d\->attr(\(aqlistheight\(aq,5);
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Either sets and returns the value of the desired attribute, or just returns
the value of the desired attribute.
.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
.Sh "state( )"
.IX Subsection "state( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& if ($d\->state() eq "OK") {
\&   # the last user response was "OK"
\& } else {
\&   # something other than an "OK" response
\& }
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Returns the state of the last dialog widget command. The value can be one of
\&\*(L"\s-1OK\s0\*(R", \*(L"\s-1CANCEL\s0\*(R" or \*(L"\s-1ESC\s0\*(R". The return data is based on the exit codes (return
value) of the last widget displayed. Some backends also support other exit
values than the standard few and these are represented as \*(L"\s-1EXTRA\s0\*(R" (3), \*(L"\s-1HELP\s0\*(R"
(2), and \*(L"\s-1ERROR\s0\*(R" (255).
.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
.Sh "ra( )"
.IX Subsection "ra( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my @array = $d\->ra();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Returns the last widget's data as an array.
.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
.Sh "rs( )"
.IX Subsection "rs( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $string = $d\->rs();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Returns the last widget's data as a (possibly multiline) string.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1SCALAR\s0.
.RE
.RE
.RS 4
.RE
.Sh "rv( )"
.IX Subsection "rv( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $string = $d\->rv();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Returns the last widget's exit status, aka: return value. This is the value
used when determining the \fIstate()\fR of a widget.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1SCALAR\s0.
.RE
.RE
.RS 4
.RE
.SH "CALLBACK FUNCTIONS"
.IX Header "CALLBACK FUNCTIONS"
.Sh "\s-1PRE\s0"
.IX Subsection "PRE"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& sub CB_PRE {
\&   my $widget_args = shift();
\&   print "Caller: ".$args\->{\(aqcaller\(aq}."\en";
\& }
\& my $d = new UI::Dialog ( callbacks => { PRE => \e&CB_PRE } );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This function recieves a hasref of the current argument values and is called
before any widget performs any operations.
.RE
.RE
.RS 4
.RE
.Sh "\s-1POST\s0"
.IX Subsection "POST"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 6
\& sub CB_POST {
\&   my $widget_args = shift();
\&   my $state = shift();
\&   print "Caller: ".$args\->{\(aqcaller\(aq}.", State: ".$state."\en";
\& }
\& my $d = new UI::Dialog ( callbacks => { POST => \e&CB_POST } );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This function recieves a hasref of the current argument values and the one word
state indicator (as reported by \fIstate()\fR) and is called after all widget
operations have been performed (including other callback functions).
.RE
.RE
.RS 4
.RE
.Sh "\s-1OK\s0"
.IX Subsection "OK"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& sub CB_OK_FUNC {
\&   my $widget_args = shift();
\&   print "Widget caller: ".$args\->{\(aqcaller\(aq}."\en";
\& }
\& my $d = new UI::Dialog ( callbacks => { OK => \e&CB_OK_FUNC } );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This function recieves a hasref of the current argument values and is called
when any widget finishes with a \fIstate()\fR of \*(L"\s-1OK\s0\*(R" but before the \s-1POST\s0 callback.
.RE
.RE
.RS 4
.RE
.Sh "\s-1CANCEL\s0"
.IX Subsection "CANCEL"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& sub CB_CANCEL {
\&   my $widget_args = shift();
\&   print "Caller: ".$args\->{\(aqcaller\(aq}."\en";
\& }
\& my $d = new UI::Dialog ( callbacks => { CANCEL => \e&CB_CANCEL } );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This function recieves a hasref of the current argument values and is called
when any widget finishes with a \fIstate()\fR of \*(L"\s-1CANCEL\s0\*(R" but before the \s-1POST\s0
callback. Be forewarned that with respect to the \fIyesno()\fR type widgets, a
user response of \*(L"\s-1NO\s0\*(R" is interpreted as \*(L"\s-1CANCEL\s0\*(R" and will execute this function.
.RE
.RE
.RS 4
.RE
.Sh "\s-1ESC\s0"
.IX Subsection "ESC"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& sub CB_ESC {
\&   my $widget_args = shift();
\&   print "Caller: ".$args\->{\(aqcaller\(aq}."\en";
\& }
\& my $d = new UI::Dialog ( callbacks => { ESC => \e&CB_ESC } );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This function recieves a hasref of the current argument values and is called
when any widget finishes with a \fIstate()\fR of \*(L"\s-1ESC\s0\*(R" but before the \s-1POST\s0 callback.
.RE
.RE
.RS 4
.RE
.Sh "\s-1HELP\s0"
.IX Subsection "HELP"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& sub CB_HELP {
\&   my $widget_args = shift();
\&   print "Caller: ".$args\->{\(aqcaller\(aq}."\en";
\& }
\& my $d = new UI::Dialog ( callbacks => { HELP => \e&CB_HELP } );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This function recieves a hasref of the current argument values and is called
when any widget finishes with a \fIstate()\fR of \*(L"\s-1HELP\s0\*(R" but before the \s-1POST\s0 callback.
The user response of \*(L"\s-1HELP\s0\*(R" is not supported by all backends.
.RE
.RE
.RS 4
.RE
.Sh "\s-1EXTRA\s0"
.IX Subsection "EXTRA"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& sub CB_EXTRA {
\&   my $widget_args = shift();
\&   print "Caller: ".$args\->{\(aqcaller\(aq}."\en";
\& }
\& my $d = new UI::Dialog ( callbacks => { EXTRA => \e&CB_EXTRA } );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This function recieves a hasref of the current argument values and is called
when any widget finishes with a \fIstate()\fR of \*(L"\s-1EXTRA\s0\*(R" but before the \s-1POST\s0 callback.
The user response of \*(L"\s-1EXTRA\s0\*(R" is not supported by all backends.
.RE
.RE
.RS 4
.RE
.SH "UTILITY METHODS"
.IX Header "UTILITY METHODS"
.Sh "beep( )"
.IX Subsection "beep( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $d\->beep();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
If the \fIbeep\fR\|(1) application can be found, use it to make a beep sound.
Otherwise print \*(L"\ea\*(R" to \s-1STDERR\s0 which normally is good enough to make
some noise.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
\&\s-1TRUE\s0 (1) regardless of result.
.RE
.RE
.RS 4
.RE
.Sh "clear( )"
.IX Subsection "clear( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $d\->clear();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Clear the terminal screen via \s-1STDOUT\s0 and the `clear` command. This method is
technically useless for any \s-1GUI\s0 based dialog variants.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
\&\s-1TRUE\s0 (1) regardless of result.
.RE
.RE
.RS 4
.RE
.Sh "word_wrap( )"
.IX Subsection "word_wrap( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my @wrapped_text = $d\->word_wrap($cols,$indent,$sub_indent,@text);
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Using the Text::Wrap::wrap function, wrap the words in a string (or array of
strings). This is primarily used within the \fI_organize_text()\fR method but may
be of use to the end\-programmer.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
A word-wrapped version of the given text data.
.RE
.RE
.RS 4
.RE
.Sh "gen_tempfile_name( )"
.IX Subsection "gen_tempfile_name( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $tempfile = $d\->gen_tempfile_name();
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This method returns a temporary file name generated using one of the following
(in order): the File::Temp perl module if detected, the program \*(L"mktemp\*(R" or
an extremely simplistic built-in name generator.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
A temporary file name.
.RE
.RE
.RS 4
.RE
.Sh "gen_random_string( )"
.IX Subsection "gen_random_string( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $random_string = $d\->gen_random_string(5);
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will return a string of random (printable) characters of an arbitrary
user-definable length (defaults to 5);
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
A string of random \s-1ASCII\s0 characters.
.RE
.RE
.RS 4
.RE
.SH "WIDGET WRAPPER METHODS"
.IX Header "WIDGET WRAPPER METHODS"
These methods are common methods to most backends as they do not have native
support for the functionality, yet the functionality is achievable by utilizing
existing compatible methods.
.Sh "fselect( )"
.IX Subsection "fselect( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $path = $self\->fselect( path => $start_path );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Using the \fImenu()\fR and \fImsgbox()\fR widgets we can simulate a file browser interface.
Note: to select a directory, go into it and then pick the '.' entry.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1SCALAR\s0 for positive results and \s-1FALSE\s0 (0) for everything else.
.RE
.RE
.RS 4
.RE
.Sh "dselect( )"
.IX Subsection "dselect( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $path = $self\->dselect( path => $start_path );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Using the \fIfselect()\fR widget we can simulate a directory browser interface.
Note: to select a directory, go into it and then pick the '.' entry.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1SCALAR\s0 for positive results and \s-1FALSE\s0 (0) for everything else.
.RE
.RE
.RS 4
.RE
.SH "BACKEND METHODS"
.IX Header "BACKEND METHODS"
These methods are only necessary for someone wishing to create more
UI::Dialog::Backend:: Modules. These are never needed to be directly
used but are none the less documented here for reference purposes.
.Sh "command_state( )"
.IX Subsection "command_state( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& if ($self\->command_state("/some/shell/command")) {
\&   #: command succeeded
\& } else {
\&   #: command failed
\& }
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will execute the given command and send \s-1STDOUT\s0 and \s-1STDERR\s0 to /dev/null
then analyse the exit code and return accordingly.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
\&\s-1TRUE\s0 (1) for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "command_string( )"
.IX Subsection "command_string( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 7
\& my ($rv,$scalar) = $self\->command_string("/some/shell/command");
\& if ($rv >= 1) {
\&   #: command failed
\& } else {
\&   #: command succeeded
\&   print "The command results: ".$scalar."\en";
\& }
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will execute the given command, catch \s-1STDOUT\s0 and \s-1STDERR\s0, then return
the \s-1SCALAR\s0 data.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1SCALAR\s0 for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "command_array( )"
.IX Subsection "command_array( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 9
\& my ($rv,@array) = $self\->command_array("/some/shell/command");
\& if ($rv >= 1) {
\&   #: command failed
\& } else {
\&   #: command succeeded
\&   foreach my $line_of_output (@array) {
\&      print "The command results: ".$line_of_output."\en";
\&   }
\& }
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will execute the given command, catch \s-1STDOUT\s0 and \s-1STDERR\s0, then return
the data, split by newlines, as an \s-1ARRAY\s0.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
an \s-1ARRAY\s0 for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "_pre( )"
.IX Subsection "_pre( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $args = $self\->_pre(@_);
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will use \fI_merge_attrs()\fR, perform any pre-widget-exec things and
then return the current argument list as a hashref. This is used in
every widget before anything is actually done in the widget and is
responsible for running the optional callback function labelled \*(L"\s-1PRE\s0\*(R".
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1HASHREF\s0.
.RE
.RE
.RS 4
.RE
.Sh "_post( )"
.IX Subsection "_post( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $self\->_post( $args );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This method is used in every widget after all operations (for the immediate
widget call) are complete but before the widget actually returns anything. This
method is responsible for running the optional callback funcions labelled \*(L"\s-1OK\s0\*(R",
\&\*(L"\s-1ESC\s0\*(R", \*(L"\s-1CANCEL\s0\*(R" and \*(L"\s-1POST\s0\*(R" with \*(L"\s-1POST\s0\*(R" being executed absolutely last.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
Nothing.
.RE
.RE
.RS 4
.RE
.Sh "_merge_attrs( )"
.IX Subsection "_merge_attrs( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $args = $self\->_merge_attrs(@_);
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will apply the arguments passed in with the defaults stored in
\&\f(CW$self\fR\->{'_opts'} (which was instantiated upon object construction).
The return result is the \*(L"current\*(R" options as defined by the defaults
with the argument options overriding them.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1HASHREF\s0.
.RE
.RE
.RS 4
.RE
.Sh "_find_bin( )"
.IX Subsection "_find_bin( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $ZenityBinaryPath = $self\->_find_bin(\(aqzenity\(aq);
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will look in the default path directories for the program of the given
name. The default \s-1PATH\s0 list is: /bin, /usr/bin, /usr/local/bin, /opt/bin.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1SCALAR\s0.
.RE
.RE
.RS 4
.RE
.Sh "_esc_text( )"
.IX Subsection "_esc_text( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $escaped_text = $self\->_esc_text( $raw_text );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will escape the following with a prefixing '\e' character:
.Sp
.Vb 1
\&  Character \-> Escaped
.Ve
.Sp
.Vb 11
\&      "          \e"
\&      `          \e`
\&      (          \e(
\&      )          \e)
\&      [          \e[
\&      ]          \e]
\&      {          \e}
\&      }          \e}
\&      $          \e$
\&      <          \e<
\&      >          \e>
.Ve
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
an \s-1SCALAR\s0 for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "_strip_text( )"
.IX Subsection "_strip_text( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& my $clean_text = $self\->_strip_text( $text_with_markup );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will strip various markup sequences from within the given argument data.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
an \s-1SCALAR\s0 for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "_organize_text( )"
.IX Subsection "_organize_text( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 2
\& my $final_text1 = $self\->_organize_text( $text_with_markup );
\& my $final_text2 = $self\->_organize_text( \e@text_with_markup );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This will strip various markup sequences from within the given argument data.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
a \s-1SCALAR\s0 for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "_is_bsd( )"
.IX Subsection "_is_bsd( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 5
\& if ($self\->_is_bsd()) {
\&   # do something with BSD specific characteristics
\& } else {
\&   # do something with general perl characteristics
\& }
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This simply checks (case\-insensitively) the perlvar $^0 for the string \*(L"bsd\*(R".
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
\&\s-1TRUE\s0 (1) for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "_list_dir( )"
.IX Subsection "_list_dir( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 2
\& my $menu_list = $self\->_list_dir( \(aq/some/path/to/a/directory\(aq,
\&                                   [ \(aqoptional\(aq, \(aqprefix\(aq, \(aqitems\(aq ] );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
Gather a list of the contents of a directory and forumlate a list suitable for
use with most (if not all) file/path selection dialog variant widgets. An
optional array reference will have all elements prefixing the directory list.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
an \s-1ARRAYREF\s0 for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "_debug( )"
.IX Subsection "_debug( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $self\->_debug( $debuging_message_string, $debuging_level );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This method will print to \s-1STDERR\s0 the debugging message provided if and only
if the debuging level is greater than or equal to the \f(CW$debuging_level\fR. The
debugging level argument is optional and defaults to a level of 1.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
\&\s-1TRUE\s0 (1) for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.Sh "_error( )"
.IX Subsection "_error( )"
.IP "\s-1EXAMPLE\s0" 4
.IX Item "EXAMPLE"
.RS 4
.Vb 1
\& $self\->_error( $error_message_string );
.Ve
.RE
.RS 4
.RE
.IP "\s-1DESCRIPTION\s0" 4
.IX Item "DESCRIPTION"
.RS 4
.RS 6
This method will print to \s-1STDERR\s0 the error message provided regardless of
debugging level.
.RE
.RE
.RS 4
.RE
.IP "\s-1RETURNS\s0" 4
.IX Item "RETURNS"
.RS 4
.RS 6
\&\s-1TRUE\s0 (1) for positive results and \s-1FALSE\s0 (0) for anything else.
.RE
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\s-1PERLDOC\s0" 2
.IX Item "PERLDOC"
.Vb 13
\& UI::Dialog
\& UI::Dialog::Console
\& UI::Dialog::GNOME
\& UI::Dialog::KDE
\& 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\s0 \s-1FILES\s0" 2
.IX Item "MAN FILES"
.Vb 2
\& dialog(1), whiptail(1), zenity(1), gdialog(1), Xdialog(1),
\& kdialog(1), nautilus(1) and osd_cat(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, <kckrinke@opendoorsoftware.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.Vb 1
\& Copyright (C) 2003  Kevin C. Krinke <kckrinke@opendoorsoftware.com>
.Ve
.PP
.Vb 4
\& 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.
.Ve
.PP
.Vb 4
\& 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.
.Ve
.PP
.Vb 3
\& 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