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");

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

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