UI::Dialog::Backend(3pm) | User Contributed Perl Documentation | UI::Dialog::Backend(3pm) |
NAME¶
UI::Dialog::BackendSYNOPSIS¶
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.
- 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.
- 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.
- EXAMPLE
my @array = $d->ra();
- DESCRIPTION
Returns the last widget's data as an
array.
- RETURNS
an ARRAY.
- EXAMPLE
my $string = $d->rs();
- DESCRIPTION
Returns the last widget's data as a (possibly
multiline) string.
- RETURNS
a SCALAR.
- 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.
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.- 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.
- 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.- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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, <kckrinke@opendoorsoftware.com>COPYRIGHT AND LICENSE¶
Copyright (C) 2003 Kevin C. Krinke <kckrinke@opendoorsoftware.com>
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
2004-08-01 | perl v5.8.8 |