Curses::UI(3)

📦
version 0.9609 · 6 versions
, in alpine 3.24

💅 Curses::UI(3) — the manual page you didn't know you needed 💅

okay bestie, so this is the Curses::UI manpage from the User Contributed Perl Documentation. It's giving object-oriented curses framework realness. Let's get into it. 🎀

🌸 NAME 🌸

Curses::UI — A curses based OO user interface framework

🎀 VERSION 🎀

Version 0.9609 — periodt, that's the version. ✨

🦋 SYNOPSIS 🦋

okay so here's the whole vibe in one go:

use Curses::UI;

# create a new C::UI object
my $cui = Curses::UI->new( -clear_on_exit => 1,
                           -debug => $debug, );

# this is where we gloss over setting up all the widgets and data
# structures :)

# start the event loop
$cui->mainloop;

Like, that's literally it. You create a C::UI object, set up your widgets and data structures (which we're glossing over here, bestie, because that's the whole point of the examples directory), and then you call mainloop to start the event loop. Slay. 🔥

🔥 DESCRIPTION 🔥

okay so Curses::UI is this object-oriented user interface framework for Perl. No cap.

It's got your basic widgets (like buttons and text areas), more "advanced" widgets (like UI tabs and a fully-functional basic text editor), and some higher-level classes like pre-fab error dialogues. It's giving main character energy. 👑

If you want more introductory material, you gotta check out Curses::UI::Tutorial and the "examples" directory of the source distribution. iykyk.

✨ CONSTRUCTOR ✨

Create a new Curses::UI object:

my $cui = Curses::UI->new( OPTIONS );

where "OPTIONS" is one or more of the following. (Yes, bestie, you can pass multiple. It's not a one-option-only situation. 💅)

  • -clear_on_exit — If true, Curses::UI will call clear on exit. Defaults to false. So like, if you want your terminal to be all clean when you leave, set this to true. Otherwise it's a no from me.
  • -color_support — If true, Curses::UI tries to enable color for the application. Defaults to false. So if you want your app to be colorful and iconic, set this to true. But it's not automatic, you gotta ask for it.
  • -compat — If true, Curses::UI will run in compatibility mode, meaning that only very simple characters will be used for creating the widgets. Defaults to false. So if you're on a terminal that's giving ancient vibes, maybe turn this on. 🧚
  • -keydelay — If set to a positive integer, Curses::UI will track elapsed seconds since the user's last keystroke, preventing timer events from occurring for the specified number of seconds afterwards. By default this option is set to '0' (disabled). So like, if you want to ignore timer events while the user is typing, set this to some number. Otherwise it's zero and disabled.
  • -mouse_support — Curses::UI attempts to auto-discover if mouse support should be enabled or not. This option allows a hard override. Expects a boolean value. So if you want to force mouse support on or off, this is your bestie. Otherwise it'll figure it out itself.
  • -userdata — Takes a scalar (frequently a hashref) as its argument, and stows that scalar inside the Curses::UI object where it can be retrieved with the #userdata method. Handy inside callbacks and the like. So like, you can stash your stuff there. No cap.
  • -default_colors — Directs the underlying Curses library to allow use of default color pairs on terminals. Is preset to true and you almost certainly don't want to twiddle it. See "man use_default_colors" if you think you do. So like, leave it alone unless you know what you're doing.
bestie, I'm serious, don't touch it unless you've read the man page. It's giving "you've been warned". 💀

💀 EVENT HANDLING METHODS 💀

mainloop

The Curses::UI event handling loop. Call once setup is finished to "start" a C::UI program. So like, this is the main character. You set everything up, then you call this, and then your program is alive. Periodt.

mainloopExit

This exits the main loop. So like, when you're done, you call this and it's over. Bye. 👋

schedule_event

Pushes its argument (a coderef) onto the scheduled event stack. So like, you give it a coderef and it schedules it. That's it. That's the whole thing.

🎀 WINDOW/LAYOUT METHODS 🎀

layout

The layout method of Curses::UI tries to find the size of the screen then calls the "layout" method of every contained object (i.e. window or widget). It is not normally necessary to call this method directly. So like, it does the layout thing for you. You probably don't need to call it yourself, but if you do, it's there. 🌈

🌈 CONVENIENCE DIALOG METHODS 🌈

dialog

Use the "dialog" method to show a dialog window. If you only provide a single argument, this argument will be used as the message to show. Example:

$cui->dialog("Hello, world!");

If you want to have some more control over the dialog window, you will have to provide more arguments (for an explanation of the arguments that can be used, see Curses::UI::Dialog::Basic. Example:

my $yes = $cui->dialog(
    -message => "Hello, world?",
    -buttons =3D> ['yes','no'],
    -values  => [1,0],
    -title   => 'Question',
);

if ($yes) {
    # whatever
}
not me copying =3D> exactly as it appears in the original, even though it's giving typo energy 😭 but rules are rules, bestie.

error

The "error" method will create an error dialog. This is basically a Curses::UI::Dialog::Basic, but it has an ASCII-art exclamation sign drawn left to the message. For the rest it's just like "dialog". Example:

$cui->error("It's the end of the\n"
           ."world as we know it!");

So like, it's a dialog but with an exclamation sign. Iconic. 💖

filebrowser

Creates a file browser dialog. For an explanation of the arguments that can be used, see Curses::UI::Dialog::Filebrowser. Example:

my $file = $cui->filebrowser(
    -path => "/tmp",
    -show_hidden => 1,
);

# Filebrowser will return undef
# if no file was selected.
if (defined $file) {
    unless (open F, ">$file") {
        print F "Hello, world!\n";
        close F;
} else {
    $cui->error(qq(Error on writing to "$file":\n$!));
}
yeah, the braces are a little chaotic in this example, but I'm copying it exactly as-is. Not me trying to fix it 😭.

loadfilebrowser, savefilebrowser

These two methods will create file browser dialogs as well. The difference is that these will have the dialogs set up correctly for loading and saving files. Moreover, the save dialog will check if the selected file exists or not. If it does exist, it will show an overwrite confirmation to check if the user really wants to overwrite the selected file. So like, loadfilebrowser is for loading, savefilebrowser is for saving, and the save one will ask before overwriting. Slay. 🫶

status, nostatus

Using these methods it's easy to provide status information for the user of your program. The status dialog is a dialog with only a label on it. The status dialog doesn't really get the focus. It's only used to display some information. If you need more than one status, you can call "status" subsequently. Any existing status dialog will be cleaned up and a new one will be created.

If you are finished, you can delete the status dialog by calling the "nostatus" method. Example:

$cui->status("Saying hello to the world...");
# code for saying "Hello, world!"

$cui->status("Saying goodbye to the world...");
# code for saying "Goodbye, world!"

$cui->nostatus;

So like, it's a little label that says what's happening. Not focusable, just vibes. ✨

progress, setprogress, noprogress

Using these methods it's easy to provide progress information to the user. The progress dialog is a dialog with an optional label on it and a progress bar. Similar to the status dialog, this dialog does not get the focus.

Using the "progress" method, a new progress dialog can be created. This method takes the same arguments as the Curses::IU::Dialog::Progress class.

After that the progress can be set using "setprogress". This method takes one or two arguments. The first argument is the current position of the progressbar. The second argument is the message to show in the label. If one of these arguments is undefined, the current value will be kept.

If you are finished, you can delete the progress dialog by calling the "noprogress" method.

$cui->progress(
    -max => 10,
    -message => "Counting 10 seconds...",
);

for my $second (0..10) {
    $cui->setprogress($second)
    sleep 1;
}

$cui->noprogress;
not me copying the missing semicolon after $cui->setprogress($second) exactly as-is. It's giving "I'm not fixing your code, bestie" energy. 💀

🧚 OTHER METHODS 🧚

leave_curses ( )

Temporarily leaves curses mode and recovers normal terminal mode. So like, if you need to do something outside of curses, you call this, and then you call reset_curses to come back.

reset_curses ( )

Return to curses mode after leave_curses(). So like, it's the comeback kid. 🌟

add ( ID, CLASS, OPTIONS )

The add method of Curses::UI is almost the same as the add method of Curses::UI::Container. The difference is that Curses::UI will only accept classes that are (descendants) of the Curses::UI::Window class. For the rest of the information see Curses::UI::Container. So like, it's the same as the container add, but only for window classes. Periodt.

add_callback ( ID, CODE)

This method lets you add a callback into the mainloop permanently. The code is executed after the input handler has run. So like, you give it an ID and a coderef, and it's added to the mainloop forever. Until you delete it.

delete_callback ( ID )

This method deletes the CODE specified by ID from the mainloop. So like, it's the opposite of add_callback. You give it the ID and it's gone. 🦋

usemodule ( CLASSNAME )

Loads the with CLASSNAME given module. So like, you give it a class name and it loads it. That's it.

userdata ( [ SCALAR ] )

This method will return the user internal data stored in the UI object. If a SCALAR parameter is specified it will also set the current user data to it. So like, you can get or set the userdata. It's giving -userdata option but as a method. 💜

keydelay ( )

This method is used internally to control timer events when the -keydelay option is set, but it can be called directly it to find out if the required amount of time has passed since the user's last action. keydelay() will return 0 if insufficent time has passed, and will return the number of elapsed seconds otherwise. So like, it tells you if the keydelay has passed. No cap.

compat ( [BOOLEAN] )

The -compat option will be set to the BOOLEAN value, unless BOOLEAN is omitted. The method returns the current value for -compat. So like, you can get or set the compat option.

clear_on_exit ( [BOOLEAN] )

The -clear_on_exit option will be set to the BOOLEAN value, unless BOOLEAN is omitted. The method returns the current value for -clear_on_exit. So like, same deal.

color ( )

Returns the currently used Curses::UI::Color object. So like, it gives you the color object. Iconic. 🎨

set_color ( OBJECT )

Replaces the currently used Color object with another. This can be used to fast change all colors in a Curses::UI application. So like, if you want to swap out the colors, this is how you do it. Fast. 🔥

🫶 SEE ALSO 🫶

💀 BUGS 💀

Please report any bugs or feature requests to "bug-curses-ui@rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Curses-UI>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. So like, if you find a bug, report it. Don't just sit there. Bestie. 🙈

👑 AUTHOR 👑

Shawn Boyette "<mdxi@cpan.org>"

See the CREDITS file for additional information. So like, he's the author. Slay. 👑

Copyright 2001-2002 Maurice Makaay; 2003-2006 Marcus Thiesen; 2007, 2008 Shawn Boyette. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

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.

So like, it's free software. You can use it, redistribute it, modify it, under the same terms as Perl itself. But it's provided "as is" without warranty. No cap. 💖

🌸 CLASS LISTING 🌸

Widgets

  • Curses::UI::Buttonbox
  • Curses::UI::Calendar
  • Curses::UI::Checkbox
  • Curses::UI::Label
  • Curses::UI::Listbox
  • Curses::UI::Menubar
  • Curses::UI::MenuListbox (used by Curses::UI::Menubar)
  • Curses::UI::Notebook
  • Curses::UI::PasswordEntry
  • Curses::UI::Popupmenu
  • Curses::UI::Progressbar
  • Curses::UI::Radiobuttonbox
  • Curses::UI::SearchEntry (used by Curses::UI::Searchable)
  • Curses::UI::TextEditor
  • Curses::UI::TextEntry
  • Curses::UI::TextViewer
  • Curses::UI::Window

Dialogs

  • Curses::UI::Dialog::Basic
  • Curses::UI::Dialog::Error
  • Curses::UI::Dialog::Filebrowser
  • Curses::UI::Dialog::Status

Base and Support Classes

  • Curses::UI::Widget
  • Curses::UI::Container
  • Curses::UI::Color
  • Curses::UI::Common
  • Curses::UI::Searchable

And that's the whole page, bestie! This manual page was brought to you by perl v5.42.2, dated 2023-07-03, and the letter C for Curses::UI(3). Stay slay, stay cursed (in the good way), and don't forget to read the examples directory. 💖✨🎀🦋🌸💅🫶😭🔥👑🌈⭐💀🙈🍓🧚💜

📦 where this page comes from