Skip to content

Latest commit

 

History

History
300 lines (228 loc) · 11.6 KB

README.md

File metadata and controls

300 lines (228 loc) · 11.6 KB

jwheatsheaf

Maven Central Maven Central (snapshot) Codecov Java Version

com.io7m.jwheatsheaf

JVM Platform Status
OpenJDK (Temurin) Current Linux Build (OpenJDK (Temurin) Current, Linux)
OpenJDK (Temurin) LTS Linux Build (OpenJDK (Temurin) LTS, Linux)
OpenJDK (Temurin) Current Windows Build (OpenJDK (Temurin) Current, Windows)
OpenJDK (Temurin) LTS Windows Build (OpenJDK (Temurin) LTS, Windows)

jwheatsheaf

An alternative to JavaFX's FileChooser that aims to be feature-compatible, if not fully API-compatible.

Features

  • Configurable, styleable (CSS), consistent, non-native JavaFX file chooser.
  • Compatible with any JSR 203 filesystem.
  • Directory creation.
  • Configurable, extensible file/directory filtering.
  • Simple case-insensitive directory searching.
  • Written in pure Java 21.
  • OSGi ready
  • JPMS ready
  • ISC license
  • High-coverage automated test suite

Motivation

JavaFX provides FileChooser and DirectoryChooser classes that delegate to the operating system's default file chooser implementation on each platform. This is in contrast to the file chooser abstractions available in Swing, which provides a single non-native file chooser that behaves identically on all platforms. While native file choosers do have certain benefits, it also means that the file choosers in JavaFX applications cannot be easily styled to match the rest of the application. It also means that applications, for better or worse, behave slightly differently on each platform. The purpose of the jwheatsheaf package is to provide a configurable, styleable, consistent, non-native file chooser implementation analogous to the JFileChooser class.

Building

$ mvn clean verify

Note: The above will run the test suite, and this will take over your keyboard and mouse for the duration of the test suite run. If you don't want to run the tests, use the skipTests propery:

$ mvn -DskipTests=true clean verify

Usage

The simplest possible code that can open a file chooser and select at most one file:

final Window mainWindow = ...;

final var configuration =
  JWFileChooserConfiguration.builder()
    .build();

final var choosers = JWFileChoosers.create();
final var chooser = choosers.create(configuration);
final List<Path> selected = chooser.showAndWait();

The above code will open a modal file chooser that can choose files from the default Java NIO filesystem, and will return the selected files (if any) in selected.

Configuration

The JWFileChooserConfiguration class comes with numerous configuration parameters, with the FileSystem parameter being the only mandatory parameter.

Filtering

A list of file filters can be passed to file choosers via the fileFilters configuration parameter. File choosers are always equipped with a file filter that displays all files (in other words, does no filtering) even if an empty list is passed in fileFilters. The list of file filters will appear in the menu at the bottom of file chooser dialogs, allowing the user to select one to filter results.

final var configuration =
  JWFileChooserConfiguration.builder()
    .addFileFilters(new ExampleFilterRejectAll())
    .addFileFilters(new ExampleFilterXML())
    .build();

Glob Filtering

The com.io7m.jwheatsheaf.filter.glob module provides a convenient system for constructing rule-based filters for files.

A Glob Filter consists of rules evaluated in declaration order against incoming filenames.

A filter rule must be one of INCLUDE, EXCLUDE, INCLUDE_AND_HALT, or EXCLUDE_AND_HALT. The incoming file names are matched against the patterns given in the filter rules. The patterns are given in PathMatcher glob syntax.

A file is included or excluded based on the result of the last rule that matched the file.

The INCLUDE rule marks a file as included if the pattern matches the file name. Evaluation of other rules continues if the pattern matches.

The EXCLUDE rule marks a file as excluded if the pattern matches the file name. Evaluation of other rules continues if the pattern matches.

The INCLUDE_AND_HALT rule marks a file as included if the pattern matches the file name. Evaluation of other rules halts if the pattern matches.

The EXCLUDE_AND_HALT rule marks a file as excluded if the pattern matches the file name. Evaluation of other rules halts if the pattern matches.

If no rules are specified at all, no files are included. If no rules match at all for a given file, the file is not included.

As an example, a filter that allows access to .txt and .png files but excludes data.txt:

final var filters =
  new JWFilterGlobFactory();

final var filter =
  filters.create("Text and images (*.txt, *.png)")
    .addRule(INCLUDE, "**/*.txt")
    .addRule(INCLUDE, "**/*.png")
    .addRule(EXCLUDE_AND_HALT, "**/data.txt")
    .build();

Action

By default, file choosers are configured to allow the selection of at most one file. The "OK" button cannot be clicked until one file is selected. Other behaviours can be specified by setting the action for the chooser:

final var configuration =
  JWFileChooserConfiguration.builder()
    .setAction(OPEN_EXISTING_MULTIPLE)
    .build();

Home Directory

If a home directory path is specified (typically a value taken from System.getProperty("user.home")), a button will be displayed in the UI that allows for navigating directly to this path.

final var configuration =
  JWFileChooserConfiguration.builder()
    .setHomeDirectory(someHomeDirectoryPath)
    .build();

Custom Titles

The titles of file chooser dialogs can be adjusted in the configuration. By default, a generic "Please select…" title is used if no other value is specified.

final var configuration =
  JWFileChooserConfiguration.builder()
    .setTitle("Export to PNG…")
    .build();

Custom Strings

Some of the strings in the file chooser UI may be customized on a per-chooser basis. For example, this can be useful for specifying strings such as "Export" instead of "Save" for the "Save" button in the file chooser. To specify custom strings, provide an implementation of JWFileChooserStringOverridesType in the constructor. An abstract implementation is available for convenience.

final var customStrings = 
  new JWFileChooserStringOverridesAbstract() {
    @Override
    public Optional<String> buttonSave()
    {
      return Optional.of("Export");
    }
  };

final var configuration =
  JWFileChooserConfiguration.builder()
    .setStringOverrides(customStrings)
    .build();

Confirmation

The file chooser can optionally prompt for confirmation of the selection of files when in CREATE mode.

final var configuration =
  JWFileChooserConfiguration.builder()
    .setAction(CREATE)
    .setConfirmFileSelection(true)
    .build();

Confirmation

Recent Items

The file chooser can display a list of recently used items. It is the responsibility of applications using the file chooser to save and otherwise manage this list between application runs; the jwheatsheaf file chooser simply displays whatever list of paths is passed in:

final var configuration =
  JWFileChooserConfiguration.builder()
    .setRecentFiles(List.of(
      Paths.get("/tmp/x"),
      Paths.get("/tmp/y"),
      Paths.get("/tmp/z"),
    ))
    .build();

Directory Creation

The file chooser contains a button that allows for the creation of new directories. This can be disabled.

final var configuration =
  JWFileChooserConfiguration.builder()
    .setAllowDirectoryCreation(false)
    .build();

Icons

The file chooser provides a JWFileImageSetType interface that allows for defining the icons used by the user interface. Users wishing to use custom icon sets should implement this interface and pass in an instance to the configuration:

final var configuration =
  JWFileChooserConfiguration.builder()
    .setFileImageSet(new CustomIcons())
    .build();

The jwheatsheaf file chooser is styleable via CSS. By default, the file chooser applies no styling and uses whatever is the default for the application. A custom stylesheet and icon set can be supplied via the JWFileChooserConfiguration class, allowing for very different visuals:

Basic light theme

Olive theme

All of the elements in a file chooser window are assigned CSS identifiers.

CSS identifiers

Identifier Description
fileChooserPathMenu The path menu used to select directory ancestors.
fileChooserUpButton The button used to move to the parent directory.
fileChooserHomeButton The button used to move to the home directory.
fileChooserCreateDirectoryButton The button used to create directories.
fileChooserSelectDirectButton The button used to enter paths directly.
fileChooserSearchField The search field used to filter the directory table.
fileChooserDirectoryTable The table that shows the contents of the current directory.
fileChooserSourceList The list view that shows the recent items and the filesystem roots.
fileChooserNameField The field that shows the selected file name.
fileChooserFilterMenu The menu that allows for selecting file filters.
fileChooserCancelButton The cancel button.
fileChooserOKButton The confirmation button.
fileChooserProgress The indeterminate progress indicator shown during I/O operations.