Provided by: libui-dialog-perl_1.09-1_all bug

NAME

       UI::Dialog::Backend - simply a collection of primarily internal methods.

SYNOPSIS

         use UI::Dialog::Backend;
         BEGIN {
           use vars qw( @ISA );
           @ISA = qw( UI::Dialog::Backend );
         }

ABSTRACT

       UI::Dialog::Backend is simply a collection of primarily internal methods.

DESCRIPTION

       While this module is inherited by all UI::Dialog backend modules, this module itself is
       not meant for direct usage. The "STATE METHODS" and "UTILITY METHODS" documentation is
       applicable to all backends thus rendering the POD for this class more important to the
       end-programmer than the usage of the class itself.

EXPORT

         None

INHERITS

         None

BACKEND EXTENSIONS

   nautilus
       EXAMPLE
            my @paths = $d->nautilus->paths();

       DESCRIPTION
                 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.

   xosd
       EXAMPLE
            $d->xosd->line( "a line of text on your screen" );

       DESCRIPTION
                 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.

STATE METHODS

   attr( )
       EXAMPLE
            my $value = $self->attr('listheight');
            my $new_value = $d->attr('listheight',5);

       DESCRIPTION
                 Either sets and returns the value of the desired attribute, or just returns the
                 value of the desired attribute.

       RETURNS
                 a single SCALAR.

   state( )
       EXAMPLE
            if ($d->state() eq "OK") {
              # the last user response was "OK"
            } else {
              # something other than an "OK" response
            }

       DESCRIPTION
                 Returns the state of the last dialog widget command. The value can be one of
                 "OK", "CANCEL" or "ESC". 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 "EXTRA" \fIs0(3),
                 "HELP" \fIs0(2), and "ERROR" (255).

       RETURNS
                 a single SCALAR.

   ra( )
       EXAMPLE
            my @array = $d->ra();

       DESCRIPTION
                 Returns the last widget's data as an array.

       RETURNS
                 an ARRAY.

   rs( )
       EXAMPLE
            my $string = $d->rs();

       DESCRIPTION
                 Returns the last widget's data as a (possibly multiline) string.

       RETURNS
                 a SCALAR.

   rv( )
       EXAMPLE
            my $string = $d->rv();

       DESCRIPTION
                 Returns the last widget's exit status, aka: return value. This is the value used
                 when determining the state() of a widget.

       RETURNS
                 a SCALAR.

CALLBACK FUNCTIONS

   PRE
       EXAMPLE
            sub CB_PRE {
              my $widget_args = shift();
              print "Caller: ".$args->{'caller'}."\n";
            }
            my $d = new UI::Dialog ( callbacks => { PRE => \&CB_PRE } );

       DESCRIPTION
                 This function recieves a hasref of the current argument values and is called
                 before any widget performs any operations.

   POST
       EXAMPLE
            sub CB_POST {
              my $widget_args = shift();
              my $state = shift();
              print "Caller: ".$args->{'caller'}.", State: ".$state."\n";
            }
            my $d = new UI::Dialog ( callbacks => { POST => \&CB_POST } );

       DESCRIPTION
                 This function recieves a hasref of the current argument values and the one word
                 state indicator (as reported by state()) and is called after all widget
                 operations have been performed (including other callback functions).

   OK
       EXAMPLE
            sub CB_OK_FUNC {
              my $widget_args = shift();
              print "Widget caller: ".$args->{'caller'}."\n";
            }
            my $d = new UI::Dialog ( callbacks => { OK => \&CB_OK_FUNC } );

       DESCRIPTION
                 This function recieves a hasref of the current argument values and is called
                 when any widget finishes with a state() of "OK" but before the POST callback.

   CANCEL
       EXAMPLE
            sub CB_CANCEL {
              my $widget_args = shift();
              print "Caller: ".$args->{'caller'}."\n";
            }
            my $d = new UI::Dialog ( callbacks => { CANCEL => \&CB_CANCEL } );

       DESCRIPTION
                 This function recieves a hasref of the current argument values and is called
                 when any widget finishes with a state() of "CANCEL" but before the POST
                 callback. Be forewarned that with respect to the yesno() type widgets, a user
                 response of "NO" is interpreted as "CANCEL" and will execute this function.

   ESC
       EXAMPLE
            sub CB_ESC {
              my $widget_args = shift();
              print "Caller: ".$args->{'caller'}."\n";
            }
            my $d = new UI::Dialog ( callbacks => { ESC => \&CB_ESC } );

       DESCRIPTION
                 This function recieves a hasref of the current argument values and is called
                 when any widget finishes with a state() of "ESC" but before the POST callback.

   HELP
       EXAMPLE
            sub CB_HELP {
              my $widget_args = shift();
              print "Caller: ".$args->{'caller'}."\n";
            }
            my $d = new UI::Dialog ( callbacks => { HELP => \&CB_HELP } );

       DESCRIPTION
                 This function recieves a hasref of the current argument values and is called
                 when any widget finishes with a state() of "HELP" but before the POST callback.
                 The user response of "HELP" is not supported by all backends.

   EXTRA
       EXAMPLE
            sub CB_EXTRA {
              my $widget_args = shift();
              print "Caller: ".$args->{'caller'}."\n";
            }
            my $d = new UI::Dialog ( callbacks => { EXTRA => \&CB_EXTRA } );

       DESCRIPTION
                 This function recieves a hasref of the current argument values and is called
                 when any widget finishes with a state() of "EXTRA" but before the POST callback.
                 The user response of "EXTRA" is not supported by all backends.

UTILITY METHODS

   beep( )
       EXAMPLE
            $d->beep();

       DESCRIPTION
                 If the beep(1) application can be found, use it to make a beep sound.  Otherwise
                 print "\a" to STDERR which normally is good enough to make some noise.

       RETURNS
                 TRUE \fIs0(1) regardless of result.

   clear( )
       EXAMPLE
            $d->clear();

       DESCRIPTION
                 Clear the terminal screen via STDOUT and the `clear` command. This method is
                 technically useless for any GUI based dialog variants.

       RETURNS
                 TRUE \fIs0(1) regardless of result.

   word_wrap( )
       EXAMPLE
            my @wrapped_text = $d->word_wrap($cols,$indent,$sub_indent,@text);

       DESCRIPTION
                 Using the Text::Wrap::wrap function, wrap the words in a string (or array of
                 strings). This is primarily used within the _organize_text() method but may be
                 of use to the end-programmer.

       RETURNS
                 A word-wrapped version of the given text data.

   gen_tempfile_name( )
       EXAMPLE
            my $tempfile = $d->gen_tempfile_name();

       DESCRIPTION
                 This method returns a temporary file name generated using one of the following
                 (in order): the File::Temp perl module if detected, the program "mktemp" or an
                 extremely simplistic built-in name generator.

       RETURNS
                 A temporary file name.

   gen_random_string( )
       EXAMPLE
            my $random_string = $d->gen_random_string(5);

       DESCRIPTION
                 This will return a string of random (printable) characters of an arbitrary user-
                 definable length (defaults to 5);

       RETURNS
                 A string of random ASCII characters.

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.

   fselect( )
       EXAMPLE
            my $path = $self->fselect( path => $start_path );

       DESCRIPTION
                 Using the menu() and msgbox() widgets we can simulate a file browser interface.
                 Note: to select a directory, go into it and then pick the '.' entry.

       RETURNS
                 a SCALAR for positive results and FALSE \fIs0(0) for everything else.

   dselect( )
       EXAMPLE
            my $path = $self->dselect( path => $start_path );

       DESCRIPTION
                 Using the fselect() widget we can simulate a directory browser interface.  Note:
                 to select a directory, go into it and then pick the '.' entry.

       RETURNS
                 a SCALAR for positive results and FALSE \fIs0(0) for everything else.

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.

   command_state( )
       EXAMPLE
            if ($self->command_state("/some/shell/command")) {
              #: command succeeded
            } else {
              #: command failed
            }

       DESCRIPTION
                 This will execute the given command and send STDOUT and STDERR to /dev/null then
                 analyse the exit code and return accordingly.

       RETURNS
                 TRUE \fIs0(1) for positive results and FALSE \fIs0(0) for anything else.

   command_string( )
       EXAMPLE
            my ($rv,$scalar) = $self->command_string("/some/shell/command");
            if ($rv >= 1) {
              #: command failed
            } else {
              #: command succeeded
              print "The command results: ".$scalar."\n";
            }

       DESCRIPTION
                 This will execute the given command, catch STDOUT and STDERR, then return the
                 SCALAR data.

       RETURNS
                 a SCALAR for positive results and FALSE \fIs0(0) for anything else.

   command_array( )
       EXAMPLE
            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."\n";
              }
            }

       DESCRIPTION
                 This will execute the given command, catch STDOUT and STDERR, then return the
                 data, split by newlines, as an ARRAY.

       RETURNS
                 an ARRAY for positive results and FALSE \fIs0(0) for anything else.

   _pre( )
       EXAMPLE
            my $args = $self->_pre(@_);

       DESCRIPTION
                 This will use _merge_attrs(), 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 "PRE".

       RETURNS
                 a HASHREF.

   _post( )
       EXAMPLE
            $self->_post( $args );

       DESCRIPTION
                 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 "OK",
                 "ESC", "CANCEL" and "POST" with "POST" being executed absolutely last.

       RETURNS
                 Nothing.

   _merge_attrs( )
       EXAMPLE
            my $args = $self->_merge_attrs(@_);

       DESCRIPTION
                 This will apply the arguments passed in with the defaults stored in
                 $self->{'_opts'} (which was instantiated upon object construction).  The return
                 result is the "current" options as defined by the defaults with the argument
                 options overriding them.

       RETURNS
                 a HASHREF.

   _find_bin( )
       EXAMPLE
            my $ZenityBinaryPath = $self->_find_bin('zenity');

       DESCRIPTION
                 This will look in the default path directories for the program of the given
                 name. The default PATH list is: /bin, /usr/bin, /usr/local/bin, /opt/bin.

       RETURNS
                 a SCALAR.

   _esc_text( )
       EXAMPLE
            my $escaped_text = $self->_esc_text( $raw_text );

       DESCRIPTION
                 This will escape the following with a prefixing '\' character:

                   Character -> Escaped

                       "          \"
                       `          \`
                       (          \(
                       )          \)
                       [          \[
                       ]          \]
                       {          \}
                       }          \}
                       $          \$
                       <          \<
                       >          \>

       RETURNS
                 an SCALAR for positive results and FALSE \fIs0(0) for anything else.

   _strip_text( )
       EXAMPLE
            my $clean_text = $self->_strip_text( $text_with_markup );

       DESCRIPTION
                 This will strip various markup sequences from within the given argument data.

       RETURNS
                 an SCALAR for positive results and FALSE \fIs0(0) for anything else.

   _organize_text( )
       EXAMPLE
            my $final_text1 = $self->_organize_text( $text_with_markup );
            my $final_text2 = $self->_organize_text( \@text_with_markup );

       DESCRIPTION
                 This will strip various markup sequences from within the given argument data.

       RETURNS
                 a SCALAR for positive results and FALSE \fIs0(0) for anything else.

   _is_bsd( )
       EXAMPLE
            if ($self->_is_bsd()) {
              # do something with BSD specific characteristics
            } else {
              # do something with general perl characteristics
            }

       DESCRIPTION
                 This simply checks (case-insensitively) the perlvar $^0 for the string "bsd".

       RETURNS
                 TRUE \fIs0(1) for positive results and FALSE \fIs0(0) for anything else.

   _list_dir( )
       EXAMPLE
            my $menu_list = $self->_list_dir( '/some/path/to/a/directory',
                                              [ 'optional', 'prefix', 'items' ] );

       DESCRIPTION
                 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.

       RETURNS
                 an ARRAYREF for positive results and FALSE \fIs0(0) for anything else.

   _debug( )
       EXAMPLE
            $self->_debug( $debuging_message_string, $debuging_level );

       DESCRIPTION
                 This method will print to STDERR the debugging message provided if and only if
                 the debuging level is greater than or equal to the $debuging_level. The
                 debugging level argument is optional and defaults to a level of 1.

       RETURNS
                 TRUE \fIs0(1) for positive results and FALSE \fIs0(0) for anything else.

   _error( )
       EXAMPLE
            $self->_error( $error_message_string );

       DESCRIPTION
                 This method will print to STDERR the error message provided regardless of
                 debugging level.

       RETURNS
                 TRUE \fIs0(1) for positive results and FALSE \fIs0(0) for anything else.

SEE ALSO

       PERLDOC
          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

       MAN FILES
          dialog(1), whiptail(1), zenity(1), gdialog(1), Xdialog(1),
          kdialog(1), nautilus(1) and osd_cat(1).

BUGS

       Please email the author with any bug reports. Include the name of the module in the
       subject line.

AUTHOR

       Kevin C. Krinke, <kevin@krinke.ca>

COPYRIGHT AND LICENSE

        Copyright (C) 2013  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