Project icon

com.io7m.jwheatsheaf

Build status Maven Central Codacy Codecov

The jwheatsheaf package provides a configurable JavaFX non-native file chooser dialog component capable of traversing any Java NIO filesystem.

Contents

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 11.
  • OSGi-ready
  • JPMS-ready
  • ISC license
  • High-coverage automated test suite

Releases

The current release is 1.0.3.

Source code and binaries are available from the repository.

Documentation

Documentation for the 1.0.3 release is available for reading online.

Documentation for current and older releases is archived in the repository.

User documentation

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.

Usage

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

 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.

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:

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:

Directory Creation

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

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:

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:

Basic light theme

Olive theme

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.
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.

JavaDoc

See the JavaDoc for more information.

Maven

The following is a complete list of the project's modules expressed as Maven dependencies:

<dependency>
  <groupId>com.io7m.jwheatsheaf</groupId>
  <artifactId>com.io7m.jwheatsheaf</artifactId>
  <version>1.0.3</version>
</dependency>

<dependency>
  <groupId>com.io7m.jwheatsheaf</groupId>
  <artifactId>com.io7m.jwheatsheaf.api</artifactId>
  <version>1.0.3</version>
</dependency>

<dependency>
  <groupId>com.io7m.jwheatsheaf</groupId>
  <artifactId>com.io7m.jwheatsheaf.documentation</artifactId>
  <version>1.0.3</version>
</dependency>

<dependency>
  <groupId>com.io7m.jwheatsheaf</groupId>
  <artifactId>com.io7m.jwheatsheaf.examples</artifactId>
  <version>1.0.3</version>
</dependency>

<dependency>
  <groupId>com.io7m.jwheatsheaf</groupId>
  <artifactId>com.io7m.jwheatsheaf.oxygen</artifactId>
  <version>1.0.3</version>
</dependency>

<dependency>
  <groupId>com.io7m.jwheatsheaf</groupId>
  <artifactId>com.io7m.jwheatsheaf.tests</artifactId>
  <version>1.0.3</version>
</dependency>

<dependency>
  <groupId>com.io7m.jwheatsheaf</groupId>
  <artifactId>com.io7m.jwheatsheaf.ui</artifactId>
  <version>1.0.3</version>
</dependency>

Each release of the project is made available on Maven Central within ten minutes of the release announcement.

Changes

Subscribe to the releases atom feed.

2020-03-29 Release: com.io7m.jwheatsheaf 1.0.3
2020-03-29 Change: Show the full paths of files/directories in tooltips (tickets: 5 )
2020-03-28 Release: com.io7m.jwheatsheaf 1.0.2
2020-03-28 Change: Ensure CSS stylesheets are passed to any dialogs opened by the chooser (tickets: 4 )
2020-03-28 Release: com.io7m.jwheatsheaf 1.0.1
2020-03-28 Change: Add missing package exports to module descriptors
2020-03-28 Release: com.io7m.jwheatsheaf 1.0.0
2020-03-28 Change: Initial public release

Sources

This project uses Git to manage source code.

Repository: https://github.com/io7m/jwheatsheaf

$ git clone https://github.com/io7m/jwheatsheaf

License

Copyright © 2020 Mark Raynsford <code@io7m.com> http://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.

Bug Tracker

The project uses GitHub Issues to track issues.