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();
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();
Styling
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:
All of the elements in a file chooser window are assigned 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. |
Releases & Development Snapshots
Releases
You can subscribe to the atom feed to be notified of project releases.
The most recently released version of the package is 4.0.1.
4.0.1 Release (2024-07-09Z)
- Update com.io7m.xoanon:com.io7m.xoanon:1.0.1 → 2.0.0
- Switch to using development versions of JavaFX, but not exposing them as a transitive dependency.
The compiled artifacts for the release (and all previous releases) are available on Maven Central.
Maven Modules
<dependency> <group>com.io7m.jwheatsheaf</group> <artifactId>com.io7m.jwheatsheaf.api</artifactId> <version>4.0.1</version> </dependency><dependency> <group>com.io7m.jwheatsheaf</group> <artifactId>com.io7m.jwheatsheaf.examples</artifactId> <version>4.0.1</version> </dependency><dependency> <group>com.io7m.jwheatsheaf</group> <artifactId>com.io7m.jwheatsheaf.filter.glob</artifactId> <version>4.0.1</version> </dependency><dependency> <group>com.io7m.jwheatsheaf</group> <artifactId>com.io7m.jwheatsheaf.oxygen</artifactId> <version>4.0.1</version> </dependency><dependency> <group>com.io7m.jwheatsheaf</group> <artifactId>com.io7m.jwheatsheaf.tests</artifactId> <version>4.0.1</version> </dependency><dependency> <group>com.io7m.jwheatsheaf</group> <artifactId>com.io7m.jwheatsheaf.ui</artifactId> <version>4.0.1</version> </dependency>
Previous Releases
The changelogs for the most recent previous releases are as follows:
4.0.0 Release (2024-05-16Z)
- Require JDK 17 (Backwards incompatible)
- Fix a silently failing OK button (Tickets: 34)
- Update org.openjfx:javafx-controls 19 → 20.
- Update org.openjfx:javafx-fxml 19 → 20.
- Update org.openjfx:javafx-graphics 19 → 20.
- Update org.openjfx:javafx-swing 19 → 20.
- Update org.junit.jupiter:junit-jupiter-api 5.9.1 → 5.9.2.
- Update org.junit.jupiter:junit-jupiter-engine 5.9.1 → 5.9.2.
- Update nl.jqno.equalsverifier:equalsverifier 3.12.3 → 3.14.1.
- Update org.slf4j:slf4j-api 2.0.6 → 2.0.7.
- Update ch.qos.logback:logback-classic 1.4.5 → 1.4.6.
- Update org.mockito:mockito-core 4.10.0 → 5.3.0.
- Update com.github.marschall:memoryfilesystem 2.4.0 → 2.5.0.
- Update com.github.marschall:memoryfilesystem 2.6.0 → 2.6.1.
- Update com.io7m.primogenitor:com.io7m.primogenitor.support 7.5.0 → 7.7.0.
- Update org.junit.jupiter:junit-jupiter-api 5.9.2 → 5.9.3.
- Update org.junit.jupiter:junit-jupiter-engine 5.9.2 → 5.9.3.
- Refactored test suite to use xoanon instead of TestFX.
- File choosers no longer require a Stage argument. (Backwards incompatible)
- Update org.mockito:mockito-core:5.8.0 → 5.12.0.
- Update com.io7m.jaffirm:com.io7m.jaffirm.core:4.0.0 → 4.0.1
- Update com.io7m.junreachable:com.io7m.junreachable.core:4.0.0 → 4.0.2
- Update nl.jqno.equalsverifier:equalsverifier:3.15.5 → 3.16.1
- Update org.slf4j:slf4j-api:2.0.10 → 2.0.13
- Update ch.qos.logback:logback-classic:1.4.14 → 1.5.6
- Update com.github.marschall:memoryfilesystem:2.7.0 → 2.8.0
- Update org.junit:junit-bom:5.10.1 → 5.10.2
- Update org.immutables:value:2.10.0 → 2.10.1
- Update org.openjfx:javafx-controls:21.0.3 → 22.0.1
- Update org.openjfx:javafx-fxml:21.0.3 → 22.0.1
- Update org.openjfx:javafx-graphics:21.0.3 → 22.0.1
- Update org.openjfx:javafx-swing:21.0.3 → 22.0.1
- Update com.io7m.xoanon:com.io7m.xoanon.extension:1.0.0 → 1.0.1
- Require JDK 21. (Backwards incompatible)
3.0.0 Release (2021-05-18Z)
- Allow the escape key to close file choosers (Tickets: 14)
- Allow for specifying an initial filename in choosers (Tickets: 15)
- Allow for specifying custom dialog titles (Tickets: 8)
- Make the default filters part of the public API (Tickets: 10)
- Add an optional home directory button (Tickets: 12)
- Enable sorting of directory items (Tickets: 22)
- Allow for setting a default file filter (Tickets: 9)
- Add support for glob-based filters (Tickets: 19)
- Improve filename field behaviour (Tickets: 28)
- Allow for including ".." in directory listings (Tickets: 23)
- Improve "select directly" dialog behaviour (Tickets: 29)
- Fix the size formatter (Tickets: 30)
- Use the default filesystem by default (Tickets: 21)
- Add the ability to specify custom strings (Tickets: 7)
- Add the ability to confirm file selections (Tickets: 17)
2.0.1 Release (2020-04-10Z)
- Enable CheckStyle to enforce code style
2.0.0 Release (2020-04-04Z)
- Move implementation classes in the ui module into an internal non-exported package (Backwards incompatible)
Development Snapshots
At the time of writing, the current unstable development version of the package is 4.0.1-SNAPSHOT.
Development snapshots may be available in the Central Portal Snapshots repository. Snapshots are published to this repository every time the project is built by the project's continuous integration system, but snapshots do expire after around ninety days and so may or may not be available depending on when a build of the package was last triggered.
Manual
This project does not have any user manuals or other documentation beyond what might be present on the page above.
Sources
This project uses Git to manage source code.
Repository: https://www.github.com/io7m-com/jwheatsheaf
$ git clone --recursive https://www.github.com/io7m-com/jwheatsheaf
Issues
This project uses GitHub Issues to track issues.
License
Copyright © 2023 Mark Raynsford <code@io7m.com> https://www.io7m.com Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.