iwidgets::fileselectionbox(1)

🌸 iwidgets::fileselectionbox 🌸

okay bestie, so this is the manual page for iwidgets::fileselectionbox — it lives in [incr Widgets], section 1. It's a whole file selection box widget, and yes she is giving main character energy the entire time. Let's get into it. 💅

---

💖 NAME 💖

iwidgets::fileselectionbox — create and manipulate a file selection box widget. that's the whole job description. iconic. ✨

---

📜 SYNOPSIS 📜

iwidgets::fileselectionbox pathName ?options?

---

🧬 INHERITANCE 🧬

her family tree, fr fr:

itk::Widget <- iwidgets::Fileselectionbox

---

✨ STANDARD OPTIONS ✨

these are the standard options she inherits, no extra lore needed:

• activeBackground
• background
• borderWidth
• cursor
• foreground
• highlightColor
• highlightThickness
• insertBackground
• insertBorderWidth
• insertOffTime
• insertOnTime
• insertWidth
• selectBackground
• selectBorderWidth
• selectForeground

See the "options" manual entry for details on the standard options. go read it, i'll wait. 🫶

---

🔗 ASSOCIATED OPTIONS 🔗

these ones come along for the ride from her component widgets:

• textBackground, textFont — see the "entryfield" widget manual entry for details on these.
• labelFont — see the "labeledwidget" widget manual entry for details on this one.
• activeRelief, elementBorderWidth, jumptroughColor — see the "scrollbar" widget class manual entry for details on these.
• textBackground, textFont — see the "scrolledlistbox" widget manual entry for details on these. (yes, same two names again, that's literally how the page lists it, no cap 💀)

---

🎀 WIDGET-SPECIFIC OPTIONS 🎀

okay this is the good part. every one of her very own options, all 23 of them, no skips, no shortcuts:

• -automount (Name: automount, Class: Automount, Command-Line Switch: -automount) — specifies a list of directory prefixes to ignore. typically you'd use it like this:

-automount {export tmp_mnt}

• -childsitepos (Name: childSitePos, Class: Position, Command-Line Switch: -childsitepos) — specifies the position of the child site in the selection box: n, s, e, w, top, bottom, or center. the default is s.

and then, sitting right here in the page like a lil bonus fact, we also get this: specifies a Tcl command procedure which is called when a file list item is double clicked. typically this occurs when mouse button 1 is double clicked over a file name. 🖱️✨

• -directory (Name: directory, Class: Directory, Command-Line Switch: -directory) — specifies the initial default directory. the default is the present working directory.
• -dirsearchcommand (Name: dirSearchCommand, Class: Command, Command-Line Switch: -dirsearchcommand) — specifies a Tcl command to be executed to perform a directory search. the command will receive the current working directory and filter mask as arguments. the command should return a list of files which will be placed into the directory list.
• -dirslabel (Name: dirsLabel, Class: Text, Command-Line Switch: -dirslabel) — specifies the text of the label for the directory list. the default is "Directories".
• -dirson (Name: dirsOn, Class: DirsOn, Command-Line Switch: -dirson) — specifies whether or not to display the directory list. the value may be given in any of the forms acceptable to Tcl_GetBoolean. the default is true.
• -filesearchcommand (Name: fileSearchCommand, Class: Command, Command-Line Switch: -filesearchcommand) — specifies a Tcl command to be executed to perform a file search. the command will receive the current working directory and filter mask as arguments. the command should return a list of files which will be placed into the file list.
• -fileslabel (Name: filesLabel, Class: Text, Command-Line Switch: -fileslabel) — specifies the text of the label for the files list. the default is "Files".
• -fileson (Name: filesOn, Class: FilesOn, Command-Line Switch: -fileson) — specifies whether or not to display the files list. the value may be given in any of the forms acceptable to Tcl_GetBoolean. the default is true.
• -filetype (Name: fileType, Class: FileType, Command-Line Switch: -filetype) — specify the type of files which may appear in the file list: regular, directory, or any. the default is regular.
• -filtercommand (Name: filterCommand, Class: Command, Command-Line Switch: -filtercommand) — specifies a Tcl command to be executed upon hitting the Return key in the filter entry widget.
• -filterlabel (Name: filterLabel, Class: Text, Command-Line Switch: -filterlabel) — specifies the text of the label for the filter entry field. the default is "Filter".
• -filteron (Name: filterOn, Class: FilterOn, Command-Line Switch: -filteron) — specifies whether or not to display the filter entry. the value may be given in any of the forms acceptable to Tcl_GetBoolean. the default is true.
• -height (Name: height, Class: Height, Command-Line Switch: -height) — specifies the height of the selection box. the value may be specified in any of the forms acceptable to Tk_GetPixels. the default is 360 pixels.
• -invalid (Name: invalid, Class: Command, Command-Line Switch: -invalid) — command to be executed should the filter contents be proven invalid. the default is {bell}. 🔔
• -mask (Name: mask, Class: Mask, Command-Line Switch: -mask) — specifies the initial file mask string. the default is "*".
• -nomatchstring (Name: noMatchString, Class: NoMatchString, Command-Line Switch: -nomatchstring) — specifies the string to be displayed in the files list should no files match the mask. the default is "".
• -selectdirommand (Name: selectDirCommand, Class: Command, Command-Line Switch: -selectdirommand) — specifies a Tcl command to be executed following selection of a directory in the directory list. (yes that switch spelling is what's printed on the page, i am NOT touching it, that's the rule 🫡)
• -selectfileommand (Name: selectFileCommand, Class: Command, Command-Line Switch: -selectfileommand) — specifies a Tcl command to be executed following selection of a file in the files list. (same situation, same energy 💀)
• -selectioncommand (Name: selectionCommand, Class: Command, Command-Line Switch: -selectioncommand) — specifies a Tcl command to be executed upon hitting the Return key in the selection entry widget.
• -selectionlabel (Name: selectionLabel, Class: Text, Command-Line Switch: -selectionlabel) — specifies the text of the label for the selection entry field. the default is "Selection".
• -selectionon (Name: selectionOn, Class: SelectionOn, Command-Line Switch: -selectionon) — specifies whether or not to display the selection entry. the value may be given in any of the forms acceptable to Tcl_GetBoolean. the default is true.
• -width (Name: width, Class: Width, Command-Line Switch: -width) — specifies the width of the selection box. the value may be specified in any of the forms acceptable to Tk_GetPixels. the default is 470 pixels.

---

🌈 DESCRIPTION 🌈

the iwidgets::fileselectionbox command creates a file selection box similar to the OSF/Motif standard Xmfileselectionbox composite widget. she's composed of directory and file scrolled lists, plus filter and selection entry fields. bindings are in place such that selecting a directory list item loads the filter entry field, and selecting a file list item loads the selection entry field. and options exist to control the appearance and actions of the widget, because of course they do. 💅

---

🛠️ METHODS 🛠️

the iwidgets::fileselectionbox command creates a new Tcl command whose name is pathName. this command may be used to invoke various operations on the widget. general form, bestie:

pathName option ?arg arg ...?

option and the args determine the exact behavior of the command. the following commands are possible for fileselectionbox widgets:

---

💅 WIDGET-SPECIFIC METHODS 💅

• pathName cget option — returns the current value of the configuration option given by option. option may have any of the values accepted by the iwidgets::fileselectionbox command.
• pathName childsite — returns the child site widget path name.
• pathName configure ?option? ?value option value ...? — query or modify the configuration options of the widget. if no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). if option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). if one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. option may have any of the values accepted by the iwidgets::fileselectionbox command.
• pathName filter — update the current contents of the file selection box based on the current filter entry field value.
• pathName get — returns the current value of the selection entry widget.

---

🧩 COMPONENTS 🧩

• dirs (Class: Scrolledlistbox) — the dirs component is the directory list box for the file selection box. see the "scrolledlistbox" widget manual entry for details on the dirs component item.
• files (Class: Scrolledlistbox) — the files component is the file list box for the file selection box. see the "scrolledlistbox" widget manual entry for details on the files component item.
• filter (Class: Entryfield) — the filter component is the entry field for user input of the filter value. see the "entryfield" widget manual entry for details on the filter component item.
• selection (Class: Entryfield) — the selection component is the entry field for user input of the currently selected file value. see the "entryfield" widget manual entry for details on the selection component item.

---

🍓 EXAMPLE 🍓

here's the whole demo, exactly as printed:

package require Iwidgets 4.0 iwidgets::fileselectionbox .fsb pack .fsb
-padx 10 -pady 10 -fill both -expand yes

---

👑 AUTHOR(S) 👑

Mark L. Ulferts 🌟

🔑 KEYWORDS

• fileselectionbox
• widget

---

okay bestie that's literally the whole page 💖 you made it to the end, and honestly? iconic behavior. go forth and select some files, slay ✨

this one's straight from the Tk fam — iwidgets::fileselectionbox(1), filed under Tk in your friendly neighborhood manual set. 🎀

version + date deets live in the footer of the original, so go peek there if you need the receipts 🫶 no cap, this page is done, periodt 💅🌸