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

📦
version 1.21 · 3 versions
, in ubuntu jammy, ubuntu noble

💖 UI::Dialog::Backend::ASCII 💖

okay bestie, sit DOWN, because we're talking about UI::Dialog::Backend::ASCII — that's the User Contributed Perl Documentation entry, she's a 3pm page, and she is the last-resort queen of the whole UI::Dialog family. no cap. 🎀

✨ NAME ✨

UI::Dialog::Backend::ASCII — it's the Dialog backend for the native Perl mode of basic text. that's it, that's the whole vibe. 💅

🌸 SYNOPSIS 🌸

use UI::Dialog::Backend::ASCII;
my $d = new UI::Dialog::Backend::ASCII ( backtitle => 'Demo',
                                         title => 'Default' );

$d->msgbox( title => 'Welcome!', text => 'Welcome one and all!' );

🦋 ABSTRACT 🦋

So UI::Dialog::Backend::ASCII is the UI::Dialog backend for the native Perl mode of basic text. and here's the thing bestie, the widgets are very much "rigid" — like, the width and height arguments are completely ignored. not "kinda ignored". completely. they said what they said. 😭

💜 DESCRIPTION 💜

This backend is literally the last resort mechanism. the logic is: if no other dialog variant has been found, then this one gets used instead — described in the original as the most absolute of bargain basement dialog variant interfaces. bargain basement. bin. basement. and honestly? iconic for knowing her lane. 🛍️

🧚 EXPORT 🧚

None

nope. nothing. zero. she gives nothing away. 🙈

⭐ INHERITS ⭐

UI::Dialog::Backend

👑 CONSTRUCTOR 👑

💫 new( @options ) 💫

EXAMPLE

my $d = new UI::Dialog::Backend::ASCII ( title => 'Default Title',
                                         backtitle => 'Backtitle'
                                       );

DESCRIPTION

This is the Class Constructor method. It accepts a list of key => value pairs, and it uses them as the defaults whenever you're interacting with the various widgets. so basically you set the vibe once and she remembers it. 🫶

RETURNS

A blessed object reference of the UI::Dialog::Backend::ASCII class. blessed, fr fr. ✨

OPTIONS

The (...)'s after each option tell you the default for that option. read them, don't skip them, i'm watching. 👀

  • debug — = 0,1,2 (0)
  • literal — = 0,1 (0)
  • backtitle — = "backtitle" ('')
  • title — = "title" ('')
  • nocancel — = 0,1 (0)
  • defaultno — = 0,1 (0)
  • beepbefore — = 0,1 (0)
  • beepafter — = 0,1 (0)
  • extra-button — = 0,1 (0)
  • extra-label — = "extra label" (0)
  • help-button — = 0,1 (0)
  • help-label — = "help label" (0)
  • maxinput — = \d+ (0)
  • autoclear — = 0,1 (0)
  • pager — = "/usr/bin/pager" ('/usr/bin/pager')
  • stty — = "/usr/bin/stty" ('/usr/bin/stty')

🎀 WIDGET METHODS 🎀

🍓 yesno( )

EXAMPLE

if ($d->yesno( text => 'A binary type question?') ) {
    # user pressed yes
} else {
    # user pressed no or cancel
}

DESCRIPTION

You present the end user with a message box that has two buttons: yes and no. that's the whole widget. a binary situation. 💀

RETURNS

TRUE (1) for a response of YES, or FALSE (0) for anything else.

🍓 msgbox( )

EXAMPLE

$d->msgbox( text => 'A simple message' );

DESCRIPTION

You present the end user with a message box that has an OK button. (the original spells it "Pesent" and honestly, slay, typo queen, but you know what it means.) 💖

RETURNS

TRUE (1) for a response of OK, or FALSE (0) for anything else.

🍓 infobox( )

EXAMPLE

$d->infobox( text => 'A simple 6 second message.', timeout => 6000 );

DESCRIPTION

You present the end user with a message box for a limited duration of time. The timeout is specified in thousandths of a second — so like, 1000 = 1 second. math bestie. 🧮

RETURNS

TRUE (1) for a response of OK, or FALSE (0) for anything else.

🍓 password( )

EXAMPLE

my $string = $d->password( text => 'Enter some (hidden) text.' );

DESCRIPTION

You present the end user with a text input field that doesn't reveal the input (except to the script, obviously, the script sees everything, that's the point) plus a message. secret little field. 🤫

RETURNS

a SCALAR if the response is OK, or FALSE (0) for anything else.

🍓 inputbox( )

EXAMPLE

my $string = $d->inputbox( text => 'Please enter some text...',
                           entry => 'this is the input field' );

DESCRIPTION

You present the end user with a text input field and a message. simple. clean. she serves. ✨

RETURNS

a SCALAR if the response is OK, or FALSE (0) for anything else.

🍓 textbox( )

EXAMPLE

$d->textbox( path => '/path/to/a/text/file' );

DESCRIPTION

You present the end user with a simple scrolling box containing the contents of the given text file. scroll scroll scroll. 📜

RETURNS

TRUE (1) if the response is OK, or FALSE (0) for anything else.

EXAMPLE

my $selection1 = $d->menu( text => 'Select one:',
                           list => [ 'tag1', 'item1',
                                     'tag2', 'item2',
                                     'tag3', 'item3' ]
                         );

DESCRIPTION

You present the user with a selectable list. pick one bestie. 👑

RETURNS

a SCALAR of the chosen tag if the response is OK, or FALSE (0) for anything else.

🍓 checklist( )

EXAMPLE

my @selection = $d->checklist( text => 'Select one:',
                               list => [ 'tag1', [ 'item1', 0 ],
                                         'tag2', [ 'item2', 1 ],
                                         'tag3', [ 'item3', 1 ] ]
                             );

DESCRIPTION

You present the user with a selectable checklist. multiple picks allowed, go feral. ✅

RETURNS

an ARRAY of the chosen tags if the response is OK, or FALSE (0) for anything else.

🍓 radiolist( )

EXAMPLE

my $selection = $d->radiolist( text => 'Select one:',
                               list => [ 'tag1', [ 'item1', 0 ],
                                         'tag2', [ 'item2', 1 ],
                                         'tag3', [ 'item3', 0 ] ]
                             );

DESCRIPTION

You present the user with a selectable radiolist. it's giving "pick exactly one, we're being serious about it". 🔘

RETURNS

a SCALAR of the chosen tag if the response is OK, or FALSE (0) for anything else.

🍓 fselect( )

EXAMPLE

my $text = $d->fselect( path => '/path/to/a/file/or/directory' );

DESCRIPTION

You present the user with a file selection widget, preset with the given path. 📁

RETURNS

a SCALAR if the response is OK, or FALSE (0) for anything else.

🍓 dselect( )

EXAMPLE

my $text = $d->dselect( path => '/path/to/a/file/or/directory' );

DESCRIPTION

You present the user with a file selection widget, preset with the given path. BUT — and this is the important part — unlike fselect() this widget will only return a directory selection. directories only. no files. she's strict. 📂

RETURNS

a SCALAR if the response is OK, or FALSE (0) for anything else.

🍓 spinner( )

EXAMPLE

print STDOUT "spinner... ";
for (20,40,60,80,100) { print $d->spinner(); sleep(1); }
print STDOUT "\bdone.\n";

DESCRIPTION

It returns the next character in the spin sequence, prefixed with a backspace (\b) character. The spinner is made up of four ASCII characters: | (pipe), \ (back slash), / (forward slash), - (hyphen).

The complete sequence is as follows:

|
/
-
\
|
/
-
\

she's spinning, she's thriving. 🌀

RETURNS

A two character SCALAR.

🍓 draw_gauge( )

EXAMPLE

foreach my $i (20,40,60,80,100) {
  last unless $d->draw_gauge( bar => "-", mark => "|", length => 74,
                              percent => $i );
  sleep(1);
}

foreach my $i (200,500,10000,12000,12345) {
  last unless $d->draw_gauge( bar => "-", mark => "|", length => 74,
                              current => $i, total => 12345 );
  sleep(1);
}

DESCRIPTION

Draws a meter bar with a position indicator. You can specify alternate characters for the meter bar itself (default is "-") and the positional marker (default is "|"), plus an arbitrary length for the bar itself.

There are two different ways to present the bar:

  • specify the percentage to display, or
  • specify the current and total values, and the widget will figure out the percentage for you. she does the math, you do nothing. 💅

RETURNS

None.

🍓 end_gauge( )

EXAMPLE

$d->end_gauge();

DESCRIPTION

Simply prints a newline, for when you're finished with the draw_gauge() widget — because draw_gauge() leaves the cursor sitting at the end of the last line of output. so this one just... tidies up after her. clean girl aesthetic. 🧼

RETURNS

None.

🌈 SEE ALSO 🌈

📚 PERLDOC

  • UI::Dialog
  • UI::Dialog::Backend
  • UI::Dialog::Console

📖 MAN FILES

💀 BUGS 💀

Please email the author with any bug reports. and include the name of the module in the subject line, okay? that's the rule. do it for her. 📧

🫶 AUTHOR 🫶

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

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

and that's the whole page bestie!! this one came to you courtesy of perl v5.28.0, dated 2018-10-27, from the User Contributed Perl Documentation corner of the universe. go forth and build the most bargain-basement-adjacent text dialogs of your dreams. mwah. 💖✨🎀

📦 where this page comes from