FileBrowser

A directory browser that shows one folder at a time and reports the file the user opens to onActivate.

See also: FilePicker to pick a single file.

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

// In a terminal, FileBrowser reads the local disk:
FileBrowser(
  initialDirectory: Directory.current.path,
  onActivate: (entry) => openFile(entry.path),
)

// In the browser there is no disk to list, so pass a source, as this demo
// does. MemoryFileSource holds a fixed tree; implement FileSource to list
// data your app already has.
FileBrowser(
  source: MemoryFileSource([
    '/my_app/lib/app.dart',
    '/my_app/pubspec.yaml',
    '/my_app/README.md',
  ]),
  initialDirectory: '/my_app',
  onActivate: (entry) => openFile(entry.path),
)

Details

Up and Down move the cursor; PageUp, PageDown, Home, and End jump. Enter, Right, or a click opens the entry under the cursor: a folder opens in place, and any other entry is passed to onActivate. Left or Backspace, or a click on the .. (parent) row, goes up a level. Ctrl+C copies the selected entry’s path (see copySelection and copyOptions).

Folders are listed before other entries, and each group is sorted by name, ignoring case. filter narrows the listing by text and shows or hides hidden entries such as dot-files. A FileBrowserController moves the cursor, opens another directory, and re-reads the current one.

It lists directories from source: the local disk by default on native platforms. A browser embed passes one, such as a MemoryFileSource. A directory that can’t be listed shows the error in place of its entries.

Constructors

FileBrowser()

Parameter	Type	Default	Description
initialDirectory:	String	required	The directory shown when the browser first mounts. Changing it later does not navigate; call FileBrowserController.openDirectory instead.
source:	FileSource?	—	Where directories are read from. Defaults to the local disk on native platforms; in the browser, pass one, such as a MemoryFileSource. A new source takes effect at the next directory read: opening a directory, a filter.showHidden change, or FileBrowserController.reload.
controller:	FileBrowserController?	—	External selection and visible-range controller.
focusNode:	FocusNode?	—	Focus node used for keyboard navigation.
autofocus:	bool	false	Whether the browser should request focus when mounted.
semanticLabel:	String	'Files'	Semantic label (the accessibility name; not rendered) for the browser.
maxVisible:	int	12	Maximum visible rows before the list scrolls.
filter:	FileBrowserFilterDescriptor	const FileBrowserFilterDescriptor()	Narrows the listing: query keeps entries whose name and type (such as directory) contain its characters in order, ignoring case, and showHidden includes hidden entries such as dot-files.
entryFilter:	FileEntryFilter?	—	Optional predicate that hides entries: return false to skip one. It runs on the entries of the directory that pass the filter.showHidden rule. More
copySelection:	bool	true	Whether Ctrl+C (and the semantic copy action) copies the selected entry to the clipboard.
copyOptions:	FileBrowserCopyOptions	const FileBrowserCopyOptions()	What Ctrl+C copies: the entry’s full path (the default) or only its name, and the clipboard write policy.
onActivate:	void Function(FileEntry entry)?	—	Called when the user opens an entry that isn’t a directory, with Enter, Right, or a click on its row. Opening a directory navigates into it instead.
onDirectoryChanged:	void Function(String directory)?	—	Called with the new directory after the user opens a folder or goes up a level. FileBrowserController.openDirectory notifies the controller’s listeners instead.
onCopy:	void Function(FileBrowserCopyResult result)?	—	Called after a copy attempt completes.

• entryFilter: A different function applies at once to the entries already read, without reading the directory again, and the selected entry stays selected while it is still listed. So a closure written inline in build is fine, and one that captures state, such as a “Dart files only” toggle, takes effect on the rebuild that changes it.

Source

FileBrowser is defined in packages/fleury/lib/src/catalog/file_browser.dart.

Category: Inputs & controls · All widgets

Live demo

filebrowser_example.dart

Restart Run Expand

Example · editable Revert Format

class _FileBrowserExampleState extends State<_FileBrowserExample> {
  // The browser has no disk to list, so this demo browses a project held in
  // memory. In a terminal, leave out `source` to browse the local disk.
  final _project = MemoryFileSource([
    '/my_app/.gitignore',
    '/my_app/README.md',
    '/my_app/pubspec.yaml',
    '/my_app/bin/run_app.dart',
    '/my_app/lib/app.dart',
    '/my_app/lib/src/status_panel.dart',
    '/my_app/lib/src/theme.dart',
    '/my_app/test/app_test.dart',
    '/my_app/web/index.html',
    '/my_app/web/main.dart',
  ]);
  String _status = 'Enter opens · Backspace goes up';

  @override
  Widget build(BuildContext context) => Column(
    crossAxisAlignment: CrossAxisAlignment.stretch,
    children: [
      Expanded(
        child: FileBrowser(
          source: _project,
          initialDirectory: '/my_app',
          autofocus: true,
          maxVisible: 8,
          onActivate: (entry) =>
              setState(() => _status = 'opened ${entry.path}'),
        ),
      ),
      Text(_status, style: const CellStyle(dim: true)),
    ],
  );
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs ⛶ Expand