NAME

UI::Dialog::Backend

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" (3), "HELP" (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 (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 (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 (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 (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 (1) for positive results and FALSE (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 (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 (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 (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 (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 (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 (1) for positive results and FALSE (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 (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 (1) for positive results and FALSE (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 (1) for positive results and FALSE (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