UI::Di...Backend(3pm)

📦

version 1.21 · 3 versions

1.21 · ubuntu jammy, ubuntu noble (latest)
1.21 · ubuntu resolute, ubuntu stonking
1.21 · debian bookworm, debian trixie

💖 UI::Dialog::Backend 💖

okay bestie, welcome to the UI::Dialog::Backend page 💅 this is the one from the User Contributed Perl Documentation section (yep, the (3pm) one) and it's lowkey the backbone of the whole UI::Dialog situation. this is part 1 of 2 so don't go anywhere, we're not done yet 🫶

✨ NAME ✨

UI::Dialog::Backend — literally just a collection of primarily internal methods. that's it. that's the name. slay.

🌸 SYNOPSIS 🌸

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

🦋 ABSTRACT 🦋

UI::Dialog::Backend is, and I cannot stress this enough, simply a collection of primarily internal methods. periodt.

🎀 DESCRIPTION 🎀

so here's the tea ☕ — every UI::Dialog backend module inherits from this one, but this module itself is not meant for direct usage. like, it's not the main character of your script, it's the supporting cast.

the STATE METHODS and UTILITY METHODS docs in here apply to all the backends, which means the POD for this class is genuinely more important to you, the end-programmer, than actually using the class itself. iykyk 💜

🌈 EXPORT 🌈

None

nothing. zero. nada. it's giving minimalist.

⭐ INHERITS ⭐

None

it inherits from nobody. it's a self-made icon 👑

👑 BACKEND EXTENSIONS 👑

🐚 nautilus

EXAMPLE

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

DESCRIPTION

this method gives you access to the UI::Dialog::Backend::Nautilus class. it will automagically try to load the UI::Dialog::Backend::Nautilus module, or it will silently fail. no drama, no error, just vibes 🌊

📺 xosd

EXAMPLE

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

DESCRIPTION

this method gives you access to the UI::Dialog::Backend::XOSD class. it will automagically try to load the UI::Dialog::Backend::XOSD module, or it will silently fail. same energy, different backend ✨

🔔 notify_send

EXAMPLE

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

DESCRIPTION

this method gives you access to the UI::Dialog::Backend::NotifySend class. it will automagically try to load the UI::Dialog::Backend::NotifySend module, or it will silently fail. shy but functional 🫶

💅 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 attribute you asked for, or just returns the value of the attribute you asked for. depends on whether you passed a new value. it's giving "read the room" 🎀

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 (aka the return value) of the last widget displayed.

some backends also support other exit values beyond the standard few, and those show up as "EXTRA" (3), "HELP" (2), and "ERROR" (255). so like, know your numbers 💀

RETURNS

a single SCALAR.

📦 ra( )

EXAMPLE

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

DESCRIPTION

returns the last widget's data as an array. array girlies rise 🙌

RETURNS

an ARRAY.

📝 rs( )

EXAMPLE

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

DESCRIPTION

returns the last widget's data as a (possibly multiline) string. yes, multiline. it can be long, bestie, don't panic.

RETURNS

a SCALAR.

🔢 rv( )

EXAMPLE

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

DESCRIPTION

returns the last widget's exit status, aka: the return value. this is the exact value used when determining the state() of a widget. so if state() is the vibe, rv() is the receipt 🧾

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 receives a hashref of the current argument values, and it gets called before any widget performs any operations. it's the pre-game 🏁

⏭️ 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 receives a hashref of the current argument values and the one-word state indicator (as reported by state()), and it gets called after all widget operations have been performed — including the other callback functions. it's the afters 🎉

✅ 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 receives a hashref of the current argument values, and it gets called when any widget finishes with a state() of "OK" — but before the POST callback. so like, OK first, POST after. respect the order bestie 🫡

❌ 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 receives a hashref of the current argument values, and it gets called when any widget finishes with a state() of "CANCEL" — but before the POST callback.

⚠️ be forewarned, bestie: with respect to the yesno() type widgets, a user response of "NO" is interpreted as "CANCEL" and will execute this function. so "no" is not just "no" here, it's a whole callback. not me finding that out the hard way 😭

🆘 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 receives a hashref of the current argument values, and it gets called when any widget finishes with a state() of "ESC" — but before the POST callback. escape room energy 🚪💨

💡 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 receives a hashref of the current argument values, and it gets called when any widget finishes with a state() of "HELP" — but before the POST callback. quick heads up: the user response of "HELP" is not supported by all backends. so don't count on it everywhere, ngl 🙈

🎁 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 receives a hashref of the current argument values, and it gets called when any widget finishes with a state() of "EXTRA" — but before the POST callback. and same disclaimer as HELP: the user response of "EXTRA" is not supported by all backends. it's giving "available in select stores only" 🛍️

🛠️ UTILITY METHODS 🛠️

🔔 beep( )

EXAMPLE

$d->beep();

DESCRIPTION

if the beep(1) application can be found, it uses that to make a beep sound. otherwise it prints "\a" to STDERR, which normally is good enough to make some noise. either way, you're getting that notification, bestie 📣

RETURNS

TRUE (1) regardless of result. always true. always iconic.

🧼 clear( )

EXAMPLE

$d->clear();

DESCRIPTION

clears the terminal screen via STDOUT and the clear command. quick note: this method is technically useless for any GUI based dialog variants. so if you're on a GUI, it's doing nothing, and that's fine 💅

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, it wraps the words in a string (or an array of strings). this is primarily used inside the _organize_text() method, but it may also be of use to you, the end-programmer. sharing is caring 🫶

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 it's detected, the program mktemp, or an extremely simplistic built-in name generator. first come, first served ✨

RETURNS

a temporary file name.

🎲 gen_random_string( )

EXAMPLE

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

DESCRIPTION

this returns a string of random (printable) characters, of an arbitrary user-definable length — and it defaults to 5. so gen_random_string() with no args still gives you five little guys 🐣

RETURNS

a string of random ASCII characters.

these methods are common to most backends, because those backends don't have native support for the functionality — but the functionality is still achievable by utilizing existing compatible methods. we improvise, we adapt, we slay 💅

📁 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. that's the move. don't overthink it.

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. same trick, same energy 🦋

RETURNS

a SCALAR for positive results, and FALSE (0) for everything else.

💅 BACKEND METHODS 💅

okay bestie, real talk: these methods are only for the girlies out there who wanna build their own UI::Dialog::Backend:: modules. You will literally never need to call them directly. But they're documented here anyway for reference, because we're thorough and we don't gatekeep. ✨

🎀 `command_state( )`

EXAMPLE

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

DESCRIPTION

This runs the command you gave it, yeets STDOUT and STDERR straight to /dev/null (no thoughts, head empty), then peeks at the exit code and returns based on that. It's giving "vibe check via exit status". 🫶

RETURNS

TRUE (1) for positive results, and FALSE (0) for literally 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

Runs the command, catches STDOUT and STDERR, and hands you back the SCALAR data. Snatched. 💖

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

Runs the command, catches STDOUT and STDERR, and returns the data split by newlines as an ARRAY. One line per element, iconic behaviour, no notes. 👑

RETURNS

an ARRAY for positive results, and FALSE (0) for anything else.

💜 `_pre( )`

EXAMPLE

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

DESCRIPTION

This one calls up _merge_attrs(), does all the pre-widget-exec things, and then returns the current argument list as a hashref. Every single widget runs this before it actually does anything, and it's the one responsible for firing off the optional callback function labelled "PRE". She's the opening act fr fr. 🎤

RETURNS

a HASHREF.

🌈 `_post( )`

EXAMPLE

$self->_post( $args );

DESCRIPTION

Every widget runs this after all its operations for the immediate widget call are done, but before the widget actually returns anything. This method is the one that runs the optional callback functions labelled "OK", "ESC", "CANCEL" and "POST" — and "POST" gets executed absolutely last, always. Cleanup crew with main character energy. 💅

RETURNS

Nothing.

⭐ `_merge_attrs( )`

EXAMPLE

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

DESCRIPTION

Takes the arguments you passed in and layers them over the defaults stored in $self->{'_opts'} (which got instantiated back when the object was constructed). What comes back is the "current" options — defaults first, with your argument options overriding them. It's a glow-up for your args. ✨

RETURNS

a HASHREF.

🍓 `_find_bin( )`

EXAMPLE

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

DESCRIPTION

Goes looking through the default path directories for a program with the given name. The default PATH list is: /bin, /usr/bin, /usr/local/bin, /opt/bin. She will find that binary, no cap. 🔍

RETURNS

a SCALAR.

🧚 `_esc_text( )`

EXAMPLE

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

DESCRIPTION

Escapes the following with a prefixing '\' character:

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

RETURNS

a SCALAR for positive results, and FALSE (0) for anything else.

🎀 `_strip_text( )`

EXAMPLE

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

DESCRIPTION

Strips various markup sequences out of the argument data you hand it. Declutter queen. 🧹

RETURNS

a 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

Strips various markup sequences out of the argument data you hand it. (Yes bestie, this is what the original says, and we do not change the facts around here. 💀)

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

Simply checks (case-insensitively) the perlvar $^0 for the string "bsd". That's it. That's the whole method. 💖

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

Gathers a list of a directory's contents and formulates a list suitable for use with most (if not all) file/path selection dialog variant widgets. If you pass an optional array reference, every element of it will get prefixed onto 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

Prints your debugging message to STDERR — but only if the debugging level is greater than or equal to the $debuging_level. The debugging level argument is optional and defaults to a level of 1. Selective, as she should be. 💅

RETURNS

TRUE (1) for positive results, and FALSE (0) for anything else.

🫶 `_error( )`

EXAMPLE

$self->_error( $error_message_string );

DESCRIPTION

Prints your error message to STDERR no matter what the debugging level is. Zero chill, zero filtering, the message gets through. 🚨

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 🐛

Pls bestie, email the author with any bug reports. Put the name of the module in the subject line so it doesn't get lost in the inbox. 🙏

✨ AUTHOR ✨

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

📜 COPYRIGHT AND LICENSE 📜

Legal text time, so I'm keeping it exactly as written — no edits, no vibes-based paraphrasing, periodt.

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

and that's a wrap on part 2, bestie 🫶 this page came to you courtesy of perl v5.28.0, dated 2018-10-27, and it lives under UI::Di...Backend(3pm) in the user-contributed perl docs. go build something iconic with it. 💖✨🎀

📦 where this page comes from

ubuntu jammy: libui-dialog-perl 1.21-0.1 · LGPL-2.1-or-later
ubuntu noble: libui-dialog-perl 1.21-0.1 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

UI::Di...Backend(3pm)

💖 UI::Dialog::Backend 💖

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 ABSTRACT 🦋

🎀 DESCRIPTION 🎀

🌈 EXPORT 🌈

⭐ INHERITS ⭐

👑 BACKEND EXTENSIONS 👑

🐚 nautilus

📺 xosd

🔔 notify_send

💅 STATE METHODS 💅

🔧 attr( )

🚦 state( )

📦 ra( )

📝 rs( )

🔢 rv( )

🎀 CALLBACK FUNCTIONS 🎀

⏮️ PRE

⏭️ POST

✅ OK

❌ CANCEL

🆘 ESC

💡 HELP

🎁 EXTRA

🛠️ UTILITY METHODS 🛠️

🔔 beep( )

🧼 clear( )

📜 word_wrap( )

🗂️ gen_tempfile_name( )

🎲 gen_random_string( )

🧚 WIDGET WRAPPER METHODS 🧚

📁 fselect( )

📂 dselect( )

💅 BACKEND METHODS 💅

🎀 command_state( )

🦋 command_string( )

🌸 command_array( )

💜 _pre( )

🌈 _post( )

⭐ _merge_attrs( )

🍓 _find_bin( )

🧚 _esc_text( )

🎀 _strip_text( )

🦋 _organize_text( )

🔥 _is_bsd( )

🌸 _list_dir( )

👑 _debug( )

🫶 _error( )

🌈 SEE ALSO 🌈

💜 PERLDOC

💖 MAN FILES

🐛 BUGS 🐛

✨ AUTHOR ✨

📜 COPYRIGHT AND LICENSE 📜

🎀 `command_state( )`

🦋 `command_string( )`

🌸 `command_array( )`

💜 `_pre( )`

🌈 `_post( )`

⭐ `_merge_attrs( )`

🍓 `_find_bin( )`

🧚 `_esc_text( )`

🎀 `_strip_text( )`

🦋 `_organize_text( )`

🔥 `_is_bsd( )`

🌸 `_list_dir( )`

👑 `_debug( )`

🫶 `_error( )`