HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Modulebrick-2.10Haskell2010

Brick.Widgets.FileBrowser

This module provides a file browser widget that allows users to navigate directory trees, search for files and directories, and select entries of interest. For a complete working demonstration of this module, see programs/FileBrowserDemo.hs.

To use this module:

File browsers have a built-in user-configurable function to limit the entries displayed that defaults to showing all files. For example, an application might want to limit the browser to just directories and XML files. That is accomplished by setting the filter with setFileBrowserEntryFilter and some examples are provided in this module: fileTypeMatch and fileExtensionMatch.

File browsers are styled using the provided collection of attribute names, so add those to your attribute map to get the appearance you want. File browsers also make use of a List internally, so the List attributes will affect how the list appears.

File browsers catch IOExceptions when changing directories. If a call to setWorkingDirectory triggers an IOException while reading the working directory, the resulting IOException is stored in the file browser and is accessible with fileBrowserException. The setWorkingDirectory function clears the exception field if the working directory is read successfully. The caller is responsible for deciding when and whether to display the exception to the user. In the event that an IOException is raised as described here, the file browser will always present .. as a navigation option to allow the user to continue navigating up the directory tree. It does this even if the current or parent directory does not exist or cannot be read, so it is always safe to present a file browser for any working directory. Bear in mind that the .. entry is always subjected to filtering and searching.

  • 4 types
  • 60 values
  • Packagebrick-2.10
  • Exports64
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourceFileBrowser.hs

Types

4 declarations
datadata FileBrowser n
#

A file browser's state. Embed this in your application state and transform it with handleFileBrowserEvent and the functions included in this module.

Instances1Named
datadata FileInfo
#

Information about a file entry in the browser.

Constructors

Instances2Eq, Show
  • Eq FileInfoDefined in brick-2.10 · Brick.Widgets.FileBrowser
  • Show FileInfoDefined in brick-2.10 · Brick.Widgets.FileBrowser

Making a new file browser

3 declarations
valuenewFileBrowser
  1. :: (FileInfo -> Bool)

    The function used to determine what kinds of entries can be selected (see handleFileBrowserEvent). A good default is selectNonDirectories. This can be changed at 'any time with fileBrowserSelectable or its 'corresponding lens.

  2. -> n

    The resource name associated with the browser's entry listing.

  3. -> Maybe FilePath

    The initial working directory that the browser displays. If not provided, this defaults to the executable's current working directory.

  4. -> IO (FileBrowser n)
#

Make a new file browser state. The provided resource name will be used to render the List viewport of the browser.

By default, the browser will show all files and directories in its working directory. To change that behavior, see setFileBrowserEntryFilter.

valueselectNonDirectories :: FileInfo -> Bool
#

A file entry selector that permits selection of all file entries except directories. Use this if you want users to be able to navigate directories in the browser. If you want users to be able to select only directories, use selectDirectories.

valueselectDirectories :: FileInfo -> Bool
#

A file entry selector that permits selection of directories only. This prevents directory navigation and only supports directory selection.

Manipulating a file browser's state

4 declarations
valuesetWorkingDirectory :: FilePath -> FileBrowser n -> IO (FileBrowser n)
#

Set the working directory of the file browser. This scans the new directory and repopulates the browser while maintaining any active search string and/or entry filtering.

If the directory scan raises an IOException, the exception is stored in the browser and is accessible with fileBrowserException. If no exception is raised, the exception field is cleared. Regardless of whether an exception is raised, .. is always presented as a valid option in the browser.

valueupdateFileBrowserSearch
  1. :: (Maybe Text -> Maybe Text)

    The search transformation. Nothing indicates that search mode should be off; Just indicates that it should be on and that the provided search string should be used.

  2. -> FileBrowser n

    The browser to modify.

  3. -> FileBrowser n
#

Modify the file browser's active search string. This causes the browser's displayed entries to change to those in its current directory that match the search string, if any. If a search string is provided, it is matched case-insensitively anywhere in file or directory names.

valuesetFileBrowserEntryFilter
  1. :: Maybe (FileInfo -> Bool)
  2. -> FileBrowser n
  3. -> FileBrowser n
#

Set the filtering function used to determine which entries in the browser's current directory appear in the browser. Nothing indicates no filtering, meaning all entries will be shown. Just indicates a function that should return True for entries that should be permitted to appear.

Note that this applies the filter after setting it by updating the listed entries to reflect the result of the filter. That is unlike setting the filter with the fileBrowserEntryFilterL lens directly, which just sets the filter but does not (and cannot) update the listed entries.

Actions

11 declarations
valueactionFileBrowserBeginSearch :: EventM n (FileBrowser n) ()
#

Handle a Vty input event. Note that event handling can cause a directory change so the caller should be aware that fileBrowserException may need to be checked after handling an event in case an exception was triggered while scanning the working directory.

Events handled regardless of mode:

Events handled only in normal mode:

Events handled only in search mode:

  • Esc, Ctrl-C: cancel search mode

  • Text input: update search string

Handling events

2 declarations
valuemaybeSelectCurrentEntry :: EventM n (FileBrowser n) ()
#

If the browser's current entry is selectable according to fileBrowserSelectable, add it to the selection set and return. If not, and if the entry is a directory or a symlink targeting a directory, set the browser's current path to the selected directory.

Otherwise, return the browser state unchanged.

Rendering

1 declaration
valuerenderFileBrowser
  1. :: (Show n, Ord n)
  2. => Bool

    Whether the file browser has input focus.

  3. -> FileBrowser n

    The browser to render.

  4. -> Widget n
#

Render a file browser. This renders a list of entries in the working directory, a cursor to select from among the entries, a header displaying the working directory, and a footer displaying information about the selected entry.

Note that if the most recent file browser operation produced an exception in fileBrowserException, that exception is not rendered by this function. That exception needs to be rendered (if at all) by the calling application.

The file browser is greedy in both dimensions.

Getting information

6 declarations
valuefileBrowserIsSearching :: FileBrowser n -> Bool
#

Returns whether the file browser is in search mode, i.e., the mode in which user input affects the browser's active search string and displayed entries. This is used to aid in event dispatching in the calling program.

valuefileBrowserException :: FileBrowser n -> Maybe IOException
#

The exception status of the latest directory change. If Nothing, the latest directory change was successful and all entries were read. Otherwise, this contains the exception raised by the latest directory change in case the calling application needs to inspect or present the error to the user.

valuefileBrowserSelectable :: FileBrowser n -> FileInfo -> Bool
#

The function that determines what kinds of entries are selectable with in the event handler. Note that if this returns True for an entry, an Enter or Space keypress selects that entry rather than doing anything else; directory changes can only occur if this returns False for directories.

Note that this is a record field so it can be used to change the selection function.

Attributes

11 declarations

Example browser entry filters

2 declarations
valuefileExtensionMatch :: String -> FileInfo -> Bool
#

A filter that matches any directory regardless of name, or any regular file with the specified extension. For example, an extension argument of "xml" would match regular files test.xml and TEST.XML and it will match directories regardless of name.

This matcher also matches symlinks if and only if their targets are directories. This is intended to make it possible to use this matcher to find files with certain extensions, but also support directory traversal via symlinks.

Lenses

8 declarations

Getters

9 declarations

Miscellaneous

1 declaration
valueprettyFileSize
  1. :: Int64

    A file size in bytes.

  2. -> Text
#

Generate a textual abbreviation of a file size, e.g. "10.2M" or "12 bytes".

Utilities

2 declarations
valueentriesForDirectory :: FilePath -> IO [FileInfo]
#

Build a list of file info entries for the specified directory. This function does not catch any exceptions raised by calling makeAbsolute or listDirectory, but it does catch exceptions on a per-file basis. Any exceptions caught when inspecting individual files are stored in the fileInfoFileStatus field of each FileInfo.

The entries returned are all entries in the specified directory except for . and ... Directories are always given first. Entries are sorted in case-insensitive lexicographic order.

This function is exported for those who want to implement their own file browser using the types in this module.

valuegetFileInfo
  1. :: String

    The name of the file to inspect. This filename is only used to set the fileInfoFilename and sanitized filename fields; the actual file to be inspected is referred to by the second argument. This is decomposed so that FileInfos can be used to represent information about entries like .., whose display names differ from their physical paths.

  2. -> FilePath

    The actual full path to the file or directory to inspect.

  3. -> IO FileInfo
#

Build a FileInfo for the specified file and path. If an IOException is raised while attempting to get the file information, the fileInfoFileStatus field is populated with the exception. Otherwise it is populated with the FileStatus for the file.