Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
UI::Dialog::Backend(3)User Contributed Perl DocumentatioUI::Dialog::Backend(3)

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.

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

       DESCRIPTION
		 This method gives access to the
		 UI::Dialog::Backend::NotifySend class.	This will
		 automagically try to load the UI::Dialog::Backend::NotifySend
		 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) 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

perl v5.24.1			  2016-02-03		UI::Dialog::Backend(3)

NAME | SYNOPSIS | ABSTRACT | DESCRIPTION | EXPORT | INHERITS | BACKEND EXTENSIONS | STATE METHODS | CALLBACK FUNCTIONS | UTILITY METHODS | WIDGET WRAPPER METHODS | BACKEND METHODS | SEE ALSO | BUGS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=UI::Dialog::Backend&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help