File chooser

VisUI provides a file chooser 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");

//chooser creation
fileChooser = new FileChooser(Mode.OPEN);
fileChooser.setSelectionMode(SelectionMode.DIRECTORIES);
fileChooser.setListener(new FileChooserAdapter() {
	@Override
	public void selected (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());
	}
});

Favorites storage

Favorites must be persistent so they have to be saved to a preferences file. If not changed file chooser will use default that may cause sharing favorites with other applications using VisUI. To avoid that call:

FileChooser.setFavoritesPrefsName(String name)

Where name is your program package for example: com.seriouscompay.seriousprogram

If you don't do it, you will get warning printed to console.

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

Listener can be set and changed by calling:

chooser.setListener(FileChooserListener listener)

Listener has two selected(...) methods:

public void selected (Array<FileHandle> files);
public void selected (FileHandle file);

It is because single or multiple files can be selected. Both of them are always called after file selection, you should choose what you need. If you need multiple files use first one, if user can only select one file use second one.

When user selects multiple files (multi selection have to be enabled first) and you will use selected(FileHandle), you will only get first file from selected files list.

Filter

File list showed in chooser can by 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).