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

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

👑 UI::Di...Dialog(3pm) — the perl doc, but make it make sense 💅

okay bestie, welcome to User Contributed Perl Documentation ✨ this is the UI::Di...Dialog(3pm) manual page and it's lowkey a whole saga, so part 1 starts now and we're not even done yet 🫶

🌸 NAME 🌸

UI::Dialog::Backend::CDialog — it's the backend for the console dialog(1) variant. yes, that's the whole vibe. the console one. periodt. 💖

✨ SYNOPSIS ✨

here's how you actually get it going, no cap:

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

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

that's it. that's the whole entrance. iconic behavior honestly 🎀

🦋 ABSTRACT 🦋

UI::Dialog::Backend::CDialog is the UI::Dialog backend for the console dialog variant. here's the tea tho: when you use this module through UI::Dialog or any other loader module, only the compatible methods are ever accessible. but when you use this module directly in your app (like the SYNOPSIS example up there) you get access to all the options and features of the real dialog(1) application. so like, full menu, not the kids' menu. 😌

💜 DESCRIPTION 💜

there are basically two versions of the console dialog program, and they're giving sibling energy:

  • one has support for colours and extra widgets ✨
  • the other has neither 💀

you can read all about the colour support in the TEXT MARKUP section. go off, king. 👑

🧚 EXPORT 🧚

None

literally nothing. it exports nothing. humble of it. 💅

🌈 INHERITS 🌈

UI::Dialog::Backend

that's the parent. the ancestry. the bloodline. 🫶

💖 CONSTRUCTOR 💖

new( @options )

EXAMPLE

my $d = new( title => 'Default Title', backtitle => 'Backtitle',
             width => 65, height => 20, listheight => 5 );

DESCRIPTION

this is the Class Constructor method. it takes a list of key => value pairs and uses them as the defaults when you're interacting with the various widgets. it's basically setting the whole mood for the object. 🎀

RETURNS

a blessed object reference of the UI::Dialog::Backend::CDialog class. blessed, as in holy, as in iconic. ⭐

OPTIONS

the (...)'s after each option tell you the default for that option. an * means it's supported by all the widget methods on a per-use policy, defaulting to the values you decided during object creation. iykyk. 🦋

  • debug = 0,1,2 (0)
  • literal = 0,1 (0)
  • backtitle = "backtitle" ('') *
  • title = "title" ('') *
  • height = \d+ (0) *
  • width = \d+ (0) *
  • beepbefore = 0,1 (0) *
  • beepafter = 0,1 (0) *

🔥 WIDGET METHODS 🔥

this is the main character section, bestie. buckle up. 🌸

yesno( )

EXAMPLE

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

DESCRIPTION

shows the end user a message box with two buttons: yes and no. it's giving binary. it's giving decision paralysis. it's giving slay. 💅

RETURNS

TRUE (1) for a response of YES, or FALSE (0) for literally anything else. anything. even cancel. especially cancel. 😭

msgbox( )

EXAMPLE

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

DESCRIPTION

pesent the end user with a message box that has an OK button. just a lil message. a vibe. a moment. ✨

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

pesent 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. yes that's milliseconds, no i will not be calling it that, the manpage said thousandths and i respect the manpage. 🫶

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

gives the end user a text input field that doesn't reveal the input (except to the script, obviously, the script sees everything 👀) plus a message.

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

gives the end user a text input field and a message. the visible version. the public-facing one. 💖

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

gives the end user a simple scrolling box containing the contents of the given text file. cozy. scrollable. no notes. 🎀

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

gives the user a selectable list. pick one. that's the whole assignment. 🦋

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

gives the user a selectable checklist. multiple picks allowed, unlike menu. we love options. 🫶

RETURNS

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

form( )

EXAMPLE

my @data = $d->form( text => 'Select one:',
                     list => [ [ 'tag1', 1, 1 ], [ 'item1', 1, 10, 10, 10 ],
                               [ 'tag2', 2, 1 ], [ 'item2', 2, 10, 10, 10 ],
                               [ 'tag3', 3, 1 ], [ 'item3', 3, 10, 10, 10 ] ]
                   );

DESCRIPTION

gives the user a selectable and potentially editable form. fill it in, bestie. make it yours. 💅

RETURNS

an ARRAY of the form data 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

gives the user a selectable radiolist. one at a time, like a true radio. no shuffling. no sharing. 🎀

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

gives the user a file selection widget preset with the given path. it'll take a file, it'll take a directory, it's flexible like that. 🌈

RETURNS

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

dselect( )

EXAMPLE

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

DESCRIPTION

gives the user a file selection widget preset with the given path. unlike fselect() this widget will only return a directory selection. it's the picky one. it has standards. 👑

RETURNS

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

calendar( )

EXAMPLE

my $date = $d->calendar( text => 'Pick a date...',
                         day => 1, month => 1, year => 1970 );
my ($m,$d,$y) = split(/\//,$date);

# or alternatively...

$d->calendar( text => 'Pick a date...',
              day => 1, month => 1, year => 1970 );
($m,$d,$y) = $d->ra();

DESCRIPTION

gives the user a calendar widget preset with the given date, or if none is specified, it uses the current date. time is a construct anyway but the calendar widget disagrees. 📅✨

RETURNS

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

timebox( )

EXAMPLE

my $time = $d->timebox( text => 'What time?' );
my ($h,$m,$s) = split(/\:/,$time);

# or alternatively...

$d->timebox( text => 'What time?',
             hour => 10, minute => 01, second => 01 );
my ($h,$m,$s) = $d->ra();

DESCRIPTION

gives the user a time widget preset with the current time. clock in, bestie. ⏰

RETURNS

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

tailbox( )

EXAMPLE

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

DESCRIPTION

gives the end user a scrolling box containing the contents of the given text file. the contents of the window is constantly updated in a similar manner to that of the unix tail(1) command. yes it's live. yes it's giving live-stream energy. 🔥

RETURNS

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

gauge_start( )

EXAMPLE

$d->gauge_start( text => 'gauge...', percentage => 1 );

DESCRIPTION

displays a meter bar to the user. this get's the widget realized but requires the use of the other gauge_*() methods for functionality. so like, it's a group project and gauge_start() did its part. the rest is on you. 😭

RETURNS

TRUE (1) if the widget loaded fine, or FALSE (0) for anything else.

gauge_inc( )

EXAMPLE

$d->gauge_inc( 1 );

DESCRIPTION

increment the meter by the given amount. up up up. 📈

RETURNS

TRUE (1) if the widget incremented fine, or FALSE (0) for anything else.

gauge_dec( )

EXAMPLE

$d->gauge_dec( 1 );

DESCRIPTION

decrement the meter by the given amount. down down down. 📉

RETURNS

TRUE (1) if the widget incremented fine, or FALSE (0) for anything else.

gauge_set( )

EXAMPLE

$d->gauge_set( 99 );

DESCRIPTION

set the meter bar to the given amount. just straight up assign it. no growth arc, just a number. 🎯

RETURNS

TRUE (1) if the widget set fine, or FALSE (0) for anything else.

gauge_text( )

EXAMPLE

$d->gauge_text( 'string' );

DESCRIPTION

set the meter bar message to the given string. give it a voice. give it a caption. 🎀

RETURNS

TRUE (1) if the widget set fine, or FALSE (0) for anything else.

gauge_stop( )

EXAMPLE

$d->gauge_stop();

DESCRIPTION

end the meter bar widget process. okay so here's a real flaw, straight from the manpage: one of the flaws with gdialog is that the gauge widget does not close properly and requies the end user to close the gauge window when 100% has been reached. this is the second reason why the author is glad gdialog is going the way of the dodo. 💀 rip gdialog, you were a menace.

RETURNS

TRUE (1) if the widget closed fine, or FALSE (0) for anything else.

🫶 SEE ALSO 🫶

PERLDOC

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

MAN FILES

🙈 BUGS 🙈

please email the author with any bug reports. include the name of the module in the subject line. help a dev out. 📧

🌟 AUTHOR 🌟

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

part 1 done bestie, don't go anywhere — more is coming 💖

okay bestie, we've reached the legal era of this page and honestly it's giving grown-up energy ✨ so let's be respectful for like two seconds 💅

Copyright (C) 2004-2016 Kevin C. Krinke <kevin@krinke.ca>

That's the whole copyright vibe, no cap — the years are 2004-2016, the name is Kevin C. Krinke, and the email is literally kevin@krinke.ca. Put some respect on it 🫶

🌸 the LGPL situation 🌸

So this library is free software, and the way that works is: 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. Choose your fighter, both are valid 🎀

This library is distributed in the hope that it will be useful, but — and this is the part where the lawyers start yelling, so listen up bestie — it comes with NO WARRANTY WHATSOEVER 😭 not even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. It's giving "we hope for the best, we promise nothing" and honestly? iconic. Go read the GNU Lesser General Public License for the full details if you want the whole saga.

You should have received a copy of the GNU Lesser General Public License along with this library. If somehow you did not 🙈 you're supposed to write to the Free Software Foundation, Inc., at 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA — and yes, that address is copied exactly, don't come for me, that's what the page says 💌

🦋 and that's the whole page, bestie 🦋

You made it to the very end of the UI::Di...Dialog(3pm) manual — highkey a main character moment 👑

This version is from perl v5.28.0, dated 2018-10-27, filed under UI::Di...Dialog(3pm) in the User Contributed Perl Documentation. Slay, read, repeat. 💖✨

📦 where this page comes from