FileSelect(3pm)

💖 FileSelect — the Tk widget for choosing files 💖

okay so bestie, welcome to FileSelect(3pm), from the User Contributed Perl Documentation squad. It's the <pink>Tk::FileSelect</pink> widget, it's giving "let the user pick a file," and honestly? It ate. Let's go. ✨

---

✨ NAME ✨

Tk::FileSelect — a widget for choosing files 🗂️

---

🌸 SYNOPSIS 🌸

use Tk::FileSelect;

$FSref = $top->FileSelect(-directory => $start_dir);
              $top            - a window reference, e.g. MainWindow->new
              $start_dir      - the starting point for the FileSelect
$file = $FSref->Show;
              Executes the fileselector until either a filename is
              accepted or the user hits Cancel. Returns the filename
              or the empty string, respectively, and unmaps the
              FileSelect.
$FSref->configure(option => value[, ...])
              Please see the Populate subroutine as the configuration
              list changes rapidly.

So like, <hotpink>$top</hotpink> is your window reference (think MainWindow->new, you know the vibe), <hotpink>$start_dir</hotpink> is where the FileSelect starts out. Then Show runs the whole thing until somebody accepts a filename or hits Cancel — it hands you back the filename, or an empty string if they bailed, and it unmaps the FileSelect. 💅 And for configure? Go read the <mint>Populate</mint> subroutine because that config list changes rapidly, no cap. 🫶

---

🦋 DESCRIPTION 🦋

This module pops up a <yellow>Fileselector box</yellow>, and it's lowkey a whole layout:

• a directory entry up top 🌟
• a list of directories in the current directory
• a list of files in the current directory
• an entry for entering/modifying a file name
• an accept button
• a cancel button

You can type a starting directory straight into the directory entry. Hit <hotpink>Return</hotpink> and the listboxes get updated, slay. Double-clicking any directory shows you its contents. Single-clicking a file brings it into the file entry so you can think about it, and double-clicking a file pops down the file selector and calls the optional command with the complete path for the selected file. Hitting return in the file selector box or pressing the accept button also works. Periodt. ✨

NOTE the file selector box will only then get destroyed if the file name is not zero length. If you want to take care of that yourself, change the if(length(.. in sub accept_file. 👑

---

💜 AUTHORS 💜

Based on original FileSelect by Klaus Lichtenwalder, Lichtenwalder@ACM.org, Datapat GmbH, Munich, April 22, 1995 — adapted by Frederick L. Wagner, derf@ti.com, Texas Instruments Incorporated, Dallas, 21Jun95. Icons, both of them. 👑

---

🌈 HISTORY 🌈

950621 — the following changes were made:

• Rewrote Tk stuff to take advantage of new Compound widget module, so FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2 subwidgets. 💅
• Moved entry labels (from to the left of) to above the entry fields.
• Caller is now able to control these aspects of widget, in both FileSelect (new) and configure:

(Please see subroutine Populate for details, as these options change rapidly!)

• I changed from Double-Button-1 to Button-1 in the Files listbox, to work with multiple mode in addition to browse mode. I also made some name changes (LastPath --> saved_path, ...).
• The show method is not yet updated.
• The topLevel stuff is not done yet. I took it out while I toy with the idea of FileSelect as a subwidget. Then the 'normal' topLevel thing with Buttons along the bottom could be build on top of it.
• By request of Henry Katz <katz@fs09.webo.dg.com>, I added the functionality of using the Directory entry as a filter. So, if you want to only see the *.c files, you add a .c (the *'s already there :) and hit return. 🎀

95/10/17, SOL, LUCC. lusol@Lehigh.EDU

• Allow either file or directory names to be accepted. 🗂️
• Require double click to move into a new directory rather than a single click. This allows a single click to select a directory name so it can be accepted.
• Add -verify list option so that standard Perl file test operators (like -d and -x) can be specified for further name validation. The default value is the special value '!-d' (not a directory), so any name can be selected as long as it's not a directory — after all, this IS FileSelect! 😭

For example:

$fs->configure(-verify => ['-d', [\&verify_code, $P1, $P2, ... $Pn]]);

ensures that the selected name is a directory. Further, if an element of the list is an array reference, the first element is a code reference to a subroutine and the remaining optional elements are its parameters. The subroutine is called like this:

&verify_code($cd, $leaf, $P1, $P2, ... $Pn);

where $cd is the current directory, $leaf is a directory or file name, and $P1 .. $Pn are your optional parameters. The subroutine should return <green>TRUE</green> if success or <red>FALSE</red> if failure.

961008 — derf@ti.com :

By request of Jim Stern <js@world.northgrum.com> and Brad Vance <bvance@ti.com>, I updated the Accept and Show functions to support selection of multiple files. I also corrected a typo in the -verify code. 🔥

---

⭐ SEE ALSO ⭐

Tk::getOpenFile, Tk::FBox. go read those too bestie, iykyk 🦋

---

okay that's the whole page, and for the cute sign-off: this lil doc is from perl v5.40.1, dated 2025-04-13, and yeah it's the FileSelect(3pm) page 💖 ✨🎀🫶