Curses:...ebrowser(3)

✨ Curses::UI::Dialog::Filebrowser — the file picker of ur dreams ✨

okay so this page is straight out of the User Contributed Perl Documentation, and honestly? it's a whole vibe. it's Curses::UI::Dialog::Filebrowser, and yes the header abbreviates it as Curses:...ebrowser(3) because apparently even the manpage headers are a little dramatic 💅

---

🎀 NAME 🎀

Curses::UI::Dialog::Filebrowser — literally just: create and manipulate filebrowser dialogs. that's the whole job bestie 🫶

---

🌸 CLASS HIERARCHY 🌸

it's giving royal family tree, so let's respect the lineage:

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

so Filebrowser is a Window is a Container is a Widget. it ate and left no crumbs 👑

---

✨ SYNOPSIS ✨

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

# The hard way.
# -------------
my $dialog = $win->add(
    'mydialog', 'Dialog::Filebrowser'
);
$dialog->focus;
my $file = $dialog->get();
$win->delete('mydialog');

# The easy way (see Curses::UI documentation).
# --------------------------------------------
$file = $cui->filebrowser();
$file = $cui->loadfilebrowser();
$file = $cui->savefilebrowser();

so like… you can do it manually (the hard way, building the dialog urself, focusing it, getting the file, deleting it — very DIY main character energy), OR you can just use $cui->filebrowser(), $cui->loadfilebrowser(), or $cui->savefilebrowser() and let the library carry you. no cap, the easy way is the way 🦋

---

💖 DESCRIPTION 💖

Curses::UI::Dialog::Filebrowser is, surprise surprise, a filebrowser dialog 💀 this type of dialog is used to select a file — and we mean anywhere on the filesystem. like, the whole filesystem. go off.

if you want a short demo, check out exampes/demo-Curses::UI::Dialog::Filebrowser in the distribution (yes, that's spelled exactly like that in the original — keeping it real, fr fr 🍓).

---

🔥 OPTIONS 🔥

• -title < TEXT > — sets the title of the dialog window to TEXT. ur window, ur name, ur rules 💅
• -path < PATH > — sets the path to start with to PATH. but plot twist: if this path doesn't exist, the filebrowser will start in the rootdirectory. rude but okay 😭
• -file < FILE > — sets the filename to start with to FILE. a little head start, we love to see it 🌈
• -editfilename < BOOLEAN > — if BOOLEAN has a true value, the user may edit the filename. this is, for example, useful for a filebrowser that's used to select a filename to save to. by default this option is set to false. so like, it's off unless u say otherwise, periodt ⭐
• -show_hidden < BOOLEAN > — if BOOLEAN has a true value, hidden files (the filename starts with a dot) will also be shown. by default this option is set to false. the dotfiles are lowkey being gatekept unless u flip this 🔍
• -mask < ARRAYREF > — if -mask is defined, a filemask popupbox will be added to the filebrowser dialog window, and this popupbox will filter the list of files that's displayed, using a regular expression (case insensitive). the ARRAYREF contains a list of array references, and each array reference has two elements: a regexp and a description. here's an example -mask:

my $mask = [
    [ '.',        'All files (*)'       ],
    [ '\.txt$',   'Text files (*.txt)'  ]
    [ 'howto',    'HOWTO documentation' ],
    [ 'core',     'Core files'          ],
];

(the original example is written exactly like this, commas and all — copying character for character, bestie 🫶)

• -mask_selected < INDEX > — normally the first mask in the list of masks will be made active upon creation of the filebrowser. but if u want another mask to be active, use the -mask_selected option and set this value to the index of the mask u want active. for example: if u wanted the "howto" mask in the above example to be active, u'd use the value 2 for -mask_selected. iconic index behavior 💅

---

🧚 METHODS 🧚

• new ( OPTIONS )
• layout ( )
• draw ( BOOLEAN )
• focus ( )

these are standard methods, bestie — see Curses::UI::Container for an explanation of these. not me making u read another manpage, but it's for ur own good 😭

• get ( ) — this method will return the complete path to the file that was selected using the filebrowser. and if no file was selected? it returns an undefined value. no file, no path, no problem 💀

---

🌟 SPECIAL BINDINGS 🌟

• escape — this will invoke the cancel button, so the filebrowser widget returns without selecting any file. the ol' dip out gracefully move 🏃‍♀️💨
• ~ — if the directory- or filelistbox of the dialog window has the focus and the tilde (~) button is pressed, the filebrowser will chdir to the homedirectory of the current user. home sweet home 🎀

---

💜 SEE ALSO 💜

Curses::UI, Curses::UI::Container, Curses::UI::Buttonbox

(go read them, they're the supporting cast and they understood the assignment 🫶)

---

👑 AUTHOR 👑

Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.

Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)

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 yeah — free software, no warranty, use/redistribute/modify under the same terms as perl itself. the legal text said it best, and I'm not about to paraphrase a license 😌

---

and that's the page!! footer says perl v5.42.2 dated 2023-07-03, so shoutout to perl v5.42.2 and that 2023-07-03 timestamp for making this whole thing official 💖✨ slay, fr fr 🦋