JUCE
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
Public Member Functions | List of all members
FileChooser Class Reference

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

Public Member Functions

 FileChooser (const String &dialogBoxTitle, const File &initialFileOrDirectory=File::nonexistent, const String &filePatternsAllowed=String::empty, bool useOSNativeDialogBox=true)
 Creates a FileChooser.
 
 ~FileChooser ()
 Destructor.
 
bool browseForFileToOpen (FilePreviewComponent *previewComponent=nullptr)
 Shows a dialog box to choose a file to open.
 
bool browseForMultipleFilesToOpen (FilePreviewComponent *previewComponent=nullptr)
 Same as browseForFileToOpen, but allows the user to select multiple files.
 
bool browseForFileToSave (bool warnAboutOverwritingExistingFiles)
 Shows a dialog box to choose a file to save.
 
bool browseForDirectory ()
 Shows a dialog box to choose a directory.
 
bool browseForMultipleFilesOrDirectories (FilePreviewComponent *previewComponent=nullptr)
 Same as browseForFileToOpen, but allows the user to select multiple files and directories.
 
bool showDialog (int flags, FilePreviewComponent *previewComponent)
 Runs a dialog box for the given set of option flags.
 
File getResult () const
 Returns the last file that was chosen by one of the browseFor methods.
 
const Array< File > & getResults () const noexcept
 Returns a list of all the files that were chosen during the last call to a browse method.
 

Detailed Description

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

To use a FileChooser:

e.g.

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

Constructor & Destructor Documentation

FileChooser::FileChooser ( const String dialogBoxTitle,
const File initialFileOrDirectory = File::nonexistent,
const String filePatternsAllowed = String::empty,
bool  useOSNativeDialogBox = true 
)

Creates a FileChooser.

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

Parameters
dialogBoxTitlea text string to display in the dialog box to tell the user what's going on
initialFileOrDirectorythe file or directory that should be selected when the dialog box opens. If this parameter is set to File::nonexistent, a sensible default directory will be used instead.
filePatternsAlloweda 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
useOSNativeDialogBoxif true, then a native dialog box will be used if possible; if false, then a Juce-based browser dialog box will always be used
See Also
browseForFileToOpen, browseForFileToSave, browseForDirectory
FileChooser::~FileChooser ( )

Destructor.

Member Function Documentation

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
previewComponentan 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 StandaloneFilterWindow::loadState().

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.

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
warnAboutOverwritingExistingFilesif 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 StandaloneFilterWindow::saveState().

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

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
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 StandaloneFilterWindow::loadState(), and StandaloneFilterWindow::saveState().

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

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

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