Creates a dialog box to choose a file or directory to load or save. More...

#include <juce_FileChooser.h>

Collaboration diagram for FileChooser:

[legend]

Public Member Functions
	FileChooser (const String &dialogBoxTitle, const File &initialFileOrDirectory=File(), const String &filePatternsAllowed=String(), bool useOSNativeDialogBox=true, bool treatFilePackagesAsDirectories=false)
	Creates a FileChooser. More...

	~FileChooser ()
	Destructor. More...

bool	browseForDirectory ()
	Shows a dialog box to choose a directory. More...

bool	browseForFileToOpen (FilePreviewComponent *previewComponent=nullptr)
	Shows a dialog box to choose a file to open. More...

bool	browseForFileToSave (bool warnAboutOverwritingExistingFiles)
	Shows a dialog box to choose a file to save. More...

bool	browseForMultipleFilesOrDirectories (FilePreviewComponent *previewComponent=nullptr)
	Same as browseForFileToOpen, but allows the user to select multiple files and directories. More...

bool	browseForMultipleFilesToOpen (FilePreviewComponent *previewComponent=nullptr)
	Same as browseForFileToOpen, but allows the user to select multiple files. More...

File	getResult () const
	Returns the last file that was chosen by one of the browseFor methods. More...

const Array< File > &	getResults () const noexcept
	Returns a list of all the files that were chosen during the last call to a browse method. More...

bool	showDialog (int flags, FilePreviewComponent *previewComponent)
	Runs a dialog box for the given set of option flags. More...

Static Private Member Functions
static bool	isPlatformDialogAvailable ()

static void	showPlatformDialog (Array< File > &results, const String &title, const File &file, const String &filters, bool selectsDirectories, bool selectsFiles, bool isSave, bool warnAboutOverwritingExistingFiles, bool selectMultipleFiles, bool treatFilePackagesAsDirs, FilePreviewComponent *previewComponent)

Private Attributes
String	filters

Array< File >	results

const File	startingFile

String	title

const bool	treatFilePackagesAsDirs

const bool	useNativeDialogBox

Detailed Description

Creates a dialog box to choose a file or directory to load or save.

To use a FileChooser:

create one (as a local stack variable is the neatest way)
call one of its browseFor.. methods
if this returns true, the user has selected a file, so you can retrieve it with the getResult() method.

e.g.

void loadMooseFile()
{
    FileChooser myChooser ("Please select the moose you want to load...",
                           File::getSpecialLocation (File::userHomeDirectory),
                           "*.moose");
    if (myChooser.browseForFileToOpen())
    {
        File mooseFile (myChooser.getResult());
        loadMoose (mooseFile);
    }
}

Constructor & Destructor Documentation

◆ FileChooser()

FileChooser::FileChooser	(	const String &	dialogBoxTitle,
		const File &	initialFileOrDirectory = `File()`,
		const String &	filePatternsAllowed = `String()`,
		bool	useOSNativeDialogBox = `true`,
		bool	treatFilePackagesAsDirectories = `false`
	)

Creates a FileChooser.

After creating one of these, use one of the browseFor... methods to display it.

Parameters

dialogBoxTitle	a text string to display in the dialog box to tell the user what's going on
initialFileOrDirectory	the file or directory that should be selected when the dialog box opens. If this parameter is set to File(), a sensible default directory will be used instead.
filePatternsAllowed	a set of file patterns to specify which files can be selected - each pattern should be separated by a comma or semi-colon, e.g. "" or ".jpg;*.gif". An empty string means that all files are allowed
useOSNativeDialogBox	if true, then a native dialog box will be used if possible; if false, then a Juce-based browser dialog box will always be used
treatFilePackagesAsDirectories	if true, then the file chooser will allow the selection of files inside packages when invoked on OS X and when using native dialog boxes.

See also: browseForFileToOpen, browseForFileToSave, browseForDirectory

◆ ~FileChooser()

FileChooser::~FileChooser ( )

Destructor.

Member Function Documentation

◆ browseForDirectory()

bool FileChooser::browseForDirectory ( )

Shows a dialog box to choose a directory.

This will display the dialog box modally, using an "open directory" mode, so it will only allow directories to be returned, not files.

Returns: true if the user chose a directory and pressed 'ok', in which case, use the getResult() method to find out what they chose. Returns false if they cancelled instead.

See also: browseForFileToOpen, browseForFileToSave

◆ browseForFileToOpen()

bool FileChooser::browseForFileToOpen ( FilePreviewComponent * previewComponent = nullptr )

Shows a dialog box to choose a file to open.

This will display the dialog box modally, using an "open file" mode, so that it won't allow non-existent files or directories to be chosen.

Parameters

previewComponent an optional component to display inside the dialog box to show special info about the files that the user is browsing. The component will not be deleted by this object, so the caller must take care of it.

Returns: true if the user selected a file, in which case, use the getResult() method to find out what it was. Returns false if they cancelled instead.

See also: browseForFileToSave, browseForDirectory

Referenced by StandalonePluginHolder::askUserToLoadState().

◆ browseForFileToSave()

bool FileChooser::browseForFileToSave ( bool warnAboutOverwritingExistingFiles )

Shows a dialog box to choose a file to save.

This will display the dialog box modally, using an "save file" mode, so it will allow non-existent files to be chosen, but not directories.

Parameters

warnAboutOverwritingExistingFiles if true, the dialog box will ask the user if they're sure they want to overwrite a file that already exists

Returns: true if the user chose a file and pressed 'ok', in which case, use the getResult() method to find out what the file was. Returns false if they cancelled instead.

See also: browseForFileToOpen, browseForDirectory

Referenced by StandalonePluginHolder::askUserToSaveState().

◆ browseForMultipleFilesOrDirectories()

bool FileChooser::browseForMultipleFilesOrDirectories ( FilePreviewComponent * previewComponent = nullptr )

Same as browseForFileToOpen, but allows the user to select multiple files and directories.

The files that are returned can be obtained by calling getResults(). See browseForFileToOpen() for more info about the behaviour of this method.

◆ browseForMultipleFilesToOpen()

bool FileChooser::browseForMultipleFilesToOpen ( FilePreviewComponent * previewComponent = nullptr )

Same as browseForFileToOpen, but allows the user to select multiple files.

The files that are returned can be obtained by calling getResults(). See browseForFileToOpen() for more info about the behaviour of this method.

◆ getResult()

File FileChooser::getResult ( ) const

Returns the last file that was chosen by one of the browseFor methods.

After calling the appropriate browseFor... method, this method lets you find out what file or directory they chose.

Note that the file returned is only valid if the browse method returned true (i.e. if the user pressed 'ok' rather than cancelling).

If you're using a multiple-file select, then use the getResults() method instead, to obtain the list of all files chosen.

See also: getResults

Referenced by StandalonePluginHolder::askUserToLoadState(), StandalonePluginHolder::askUserToSaveState(), and StandalonePluginHolder::setLastFile().

◆ getResults()

const Array<File>& FileChooser::getResults ( ) const

inlinenoexcept

Returns a list of all the files that were chosen during the last call to a browse method.

This array may be empty if no files were chosen, or can contain multiple entries if multiple files were chosen.

See also: getResult

◆ isPlatformDialogAvailable()

static bool FileChooser::isPlatformDialogAvailable ( )

staticprivate

◆ showDialog()

bool FileChooser::showDialog	(	int	flags,
		FilePreviewComponent *	previewComponent
	)

Runs a dialog box for the given set of option flags.

The flag values used are those in FileBrowserComponent::FileChooserFlags.

Returns: true if the user chose a directory and pressed 'ok', in which case, use the getResult() method to find out what they chose. Returns false if they cancelled instead.

See also: FileBrowserComponent::FileChooserFlags

◆ showPlatformDialog()

static void FileChooser::showPlatformDialog	(	Array< File > &	results,
		const String &	title,
		const File &	file,
		const String &	filters,
		bool	selectsDirectories,
		bool	selectsFiles,
		bool	isSave,
		bool	warnAboutOverwritingExistingFiles,
		bool	selectMultipleFiles,
		bool	treatFilePackagesAsDirs,
		FilePreviewComponent *	previewComponent
	)

staticprivate

Member Data Documentation

◆ filters

String FileChooser::filters

private

◆ results

Array<File> FileChooser::results

private

◆ startingFile

const File FileChooser::startingFile

private

◆ title

String FileChooser::title

private

◆ treatFilePackagesAsDirs

const bool FileChooser::treatFilePackagesAsDirs

private

◆ useNativeDialogBox

const bool FileChooser::useNativeDialogBox

private

The documentation for this class was generated from the following file:

juce_FileChooser.h

Public Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ FileChooser()

◆ ~FileChooser()

Member Function Documentation

◆ browseForDirectory()

◆ browseForFileToOpen()

◆ browseForFileToSave()

◆ browseForMultipleFilesOrDirectories()

◆ browseForMultipleFilesToOpen()

◆ getResult()

◆ getResults()

◆ isPlatformDialogAvailable()

◆ showDialog()

◆ showPlatformDialog()

Member Data Documentation

◆ filters

◆ results

◆ startingFile

◆ title

◆ treatFilePackagesAsDirs

◆ useNativeDialogBox