Curses:...rogress(3)

💅 Curses::UI::Dialog::Progress — bestie's guide to progress dialogs

okay so real talk, this page is from the User Contributed Perl Documentation section of the manual, and we're about to make a progress bar make sense. i promise it's not scary.

---

✨ NAME ✨

Curses::UI::Dialog::Progress — literally just: create and manipulate progress dialogs 🎀

🦋 CLASS HIERARCHY 🦋

so here's the family tree, and yes it's giving royal lineage 👑

Curses::UI::Widget
   |
   +----Curses::UI::Container
           |
           +----Curses::UI::Window
                   |
                   +----Curses::UI::Dialog::Progress

like, Dialog::Progress is the baby at the bottom and it inherited everything. main character energy fr.

🌸 SYNOPSIS 🌸

here's the whole vibe, copy-paste style:

use Curses::UI;
my $cui = new Curses::UI;
my $win = $cui->add('window_id', 'Window');

# The hard way.
# -------------
my $dialog = $win->add(
    'mydialog', 'Dialog::Progress',
-max       => 100,
    -message   => 'Some message',
);

$dialog->pos(10);
$dialog->message('Some other message');
$dialog->draw();

$win->delete('mydialog');

# The easy way (see Curses::UI documentation).
# --------------------------------------------
$cui->progress(
-max       => 100,
    -message   => 'Some message',
);
$cui->setprogress(10, 'Some other message');
$cui->noprogress;

so there's the hard way (you build the dialog yourself, you draw it, you delete it — very DIY, very "i did my own nails" 💅) and the easy way where the $cui object handles it for you. pick your fighter.

💖 DESCRIPTION 💖

lowkey the biggest plot twist: Curses::UI::Dialog::Progress is not really a dialog. the user can't interact with it at all — like, there's no buttons, no clicking, nothing. it's merely a way of presenting progress information to the user of your program. it's a vibe, not a conversation. 🫶

also there's a short demo in the distribution at exampes/demo-Curses::UI::Dialog::Progress — go look at it, it's cute.

⭐ OPTIONS ⭐

okay here's where people get lost, so let's go one by one, no cap:

• -title < TEXT > — sets the title of the dialog window to TEXT. that's it. that's the whole thing. slay. 👑
• -message < TEXT > — this sets the initial message shown to TEXT. important caveat bestie: it's displayed using a Curses::UI::Label, so it cannot contain any newline (\n) characters. like, zero. don't even try. 😭
• -nomessage < BOOLEAN > — if BOOLEAN is true, the dialog window will not contain a message label at all. by default -nomessage has a false value, so the label is there unless you say otherwise.
• -min < VALUE > — one of the progressbar control options ✨
• -max < VALUE > — one of the progressbar control options ✨
• -pos < VALUE > — one of the progressbar control options ✨
• -nopercentage < BOOLEAN > — one of the progressbar control options ✨
• -nocenterline < BOOLEAN > — one of the progressbar control options ✨

those last five (-min, -max, -pos, -nopercentage, -nocenterline) are all the progressbar crew — they control the progressbar of the dialog, and for the full explanation you gotta see Curses::UI::Progressbar. i'm not gonna pretend i know more than the source, iykyk.

🔥 METHODS 🔥

• new ( OPTIONS ) — standard method 🌈
• layout ( ) — standard method 🌈
• draw ( BOOLEAN ) — standard method 🌈

those three are standard methods, and Curses::UI::Container has the explanation for them. go read it, it's fine.

• pos ( VALUE ) — updates the position of the progressbar to SCALAR. ⚠️ heads up: you have to call draw afterwards to actually see the change. no draw, no show. 💀
• message ( TEXT ) — updates the message of the progress dialog to TEXT. same deal: you have to call draw to see it change. the whole thing is very "nothing happens until you hit draw" and honestly that's just how it is. 🙈

🌈 SEE ALSO 🌈

go be nosy, these are the related ones:

• Curses::UI
• Curses::UI::Container
• Curses::UI::Progressbar

🎀 AUTHOR 🎀

copyright (c) 2001-2002 Maurice Makaay. all rights reserved. 👑

maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de) — email him, he's lovely probably.

this package is free software and is provided "as is" without express or implied warranty. it may be used, redistributed and/or modified under the same terms as perl itself. 🫶

---

and that's the page!! this doc shipped with perl v5.42.2 and was dated 2023-07-03 — so it's a little vintage, but the vibes are timeless. bye bestie, go draw your progress bar 💜🧚✨