File chooser

VisUI provides a file chooser (source) widget.

Chooser provides quick access to user home and desktop directory, quick access to drives partitions and removable devices. User can add custom favorites that will appear bellow partitions list. Chooser is platform dependent and can be only used on desktop.

File chooser should be created once and reused, if you reuse it will load much faster and it will remember last directory that user browsed.

Simple example

//somewhere during app loading (look below at "Favorites storage" for explanation)
FileChooser.setFavoritesPrefsName("com.your.package.here.filechooser");

//chooser creation
fileChooser = new FileChooser(Mode.OPEN);
fileChooser.setSelectionMode(SelectionMode.DIRECTORIES);
fileChooser.setListener(new FileChooserAdapter() {
	@Override
	public void selected (Array<FileHandle> file) {
		textField.setText(file.file().getAbsolutePath());
	}
});

//button listener
selectFileButton.addListener(new ChangeListener() {
	@Override
	public void changed (ChangeEvent event, Actor actor) {
		//displaying chooser with fade in animation
		getStage().addActor(fileChooser.fadeIn());
	}
});

Preferences storage

File chooser needs to store persistent data such as favorites or recent directories. If not changed, file chooser will use default that may cause sharing preferences with other applications using VisUI. To avoid that call:

FileChooser.setDefaultPrefsName(String name) //for VisUI 1.1.0 and newer
//FileChooser.setFavoritesPrefsName(String name) //deprecated, for VisUI 1.0.2 and older

Where name is your program package for example: com.seriouscompay.seriousprogram.filechooser. Note that this name should be unique, to avoid key collisions you should not use the same name for other preferences of your application. To achieve this in simple way append something like .filechooser to your app package name - like in the example at the start of this paragraph.

If you don't change default name, you will get warning printed to console. This warning cannot be disabled it is likely that setting preferences name will be required in further VisUI versions.

Mode

When creating file chooser you must pass mode that it will use, there are two possibilities Mode.SAVE and Mode.OPEN. It changes chooser texts and behavior, it also displays overwrite warring messages when dialog is in SAVE mode.

Selection mode

The following selection modes are available: FILES, DIRECTORIES, FILES_AND_DIRECTORIES. Please note that if dialog is in DIRECTORIES mode files still will be displayed, if user tries to select file, error message will be showed. Default selection mode is SelectionMode.FILES.

Current directory

Default folder that chooser will display is user home directory, this can be changed by calling:

chooser.setDirectory(String)

chooser.setDirectory(File)

chooser.setDirectory(FileHandle)

String path will be tried to resolved using absolute FileHandle. Same for passing File (dir.getAbsolutePath() is called)

Locale

Since 0.7.0, I18NBundles are used for managing chooser texts, please refer to I18N Guide

Multiple selection

Chooser allow to select multiple files. It is disabled by default, to enable it call:

chooser.setMultiSelectionEnabled(true)

To select multiple files you need to press a key on keyboard, default is Keys.CONTROL_LEFT, to change it call:

chooser.setMultiSelectKey (int)

You can also do group selection on files, default key is Keys.SHIFT_LEFT, to change it call:

setGroupMultiSelectKey (int)

Where int is value from LibGDX Keys class.

Listener

Chooser will fire listener functions when a file (or files) is selected or when a file selection has been canceled.

Listener and its empty implementation: FileChooserAdapater. You can also use StreamingFileChooserListener. If user is able only to select one file you can use SingleFileChooserListener which has more convenient seleced(FileHandle) method.

Listener can be set and changed by calling:

chooser.setListener(FileChooserListener listener)

Filter

File list showed in chooser can be filtered by setting a file filter. To set it call:

chooser.setFilter(FileFilter filter)

Default one filters hidden files, and files that cannot be read (when in OPEN mode) or files that cannot be written to (when in SAVE mode). Custom filters should extend DefaultFileFilter in order to use those rules.

Even if you only want to allow user selecting files, your filter should allow directories so user will be able to navigate in file hierarchy. Use SelectionMode.FILES to limit selection to files only.

TypeFilters

FileTypeFilter allows user to filter file chooser list by given set of extension. If type filter is set for chooser then below file path select box with possible extensions is displayed. If user switches filter rule then only extensions allowed in that rule will be displayed (directories are also displayed of course)

FileTypeFilter typeFilter = new FileTypeFilter(true); //allow "All Types" mode where all files are shown
typeFilter.addRule("Image files (*.png, *.jpg, *.gif)", "png", "jpg", "gif");
typeFilter.addRule("Text files (*.txt)", "txt");
typeFilter.addRule("Audio files (*.mp3, *.wav, *.ogg)", "mp3", "wav", "ogg");
chooser.setFileTypeFilter(typeFilter);

View modes

Chooser out of the box supports two view modes: details (single column of files but with more details) and list (multiple columns of files, less details). There are also additional view modes that supports images thumbnails however in order to be enabled they require setting special FileIconProvider that can supply thumbnails.

vis-ui-contrib library contains working implementation that uses ImgScalr library to supply thumbnails. (see ImgScalrFileChooserIconProvider). While it works quite OK and reasonably fast it may cause (depending on JVM) the heap to grow very quickly when thumbnails are generated even though actual memory usage after generation is low. This can be avoided by using -XX:MaxHeapFreeRatio=70 to make JVM release allocated heap memory quicker. See Javadoc for more details.