JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::FileChooser Class Reference

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

#include <juce_FileChooser.h>

Collaboration diagram for juce::FileChooser:

Classes

struct  Pimpl
 

Public Member Functions

 FileChooser (const String &dialogBoxTitle, const File &initialFileOrDirectory=File(), const String &filePatternsAllowed=String(), bool useOSNativeDialogBox=true, bool treatFilePackagesAsDirectories=false, Component *parentComponent=nullptr)
 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...
 
Array< FilegetResults () const noexcept
 Returns a list of all the files that were chosen during the last call to a browse method. More...
 
URL getURLResult () const
 Returns the last document that was chosen by one of the browseFor methods. More...
 
const Array< URL > & getURLResults () const noexcept
 Returns a list of all the files that were chosen during the last call to a browse method. More...
 
void launchAsync (int flags, std::function< void(const FileChooser &)>, FilePreviewComponent *previewComponent=nullptr)
 Use this method to launch the file browser window asynchronously. More...
 
bool showDialog (int flags, FilePreviewComponent *previewComponent)
 Runs a dialog box for the given set of option flags. More...
 

Static Public Member Functions

static bool isPlatformDialogAvailable ()
 Returns if a native filechooser is currently available on this platform. More...
 

Private Member Functions

PimplcreatePimpl (int, FilePreviewComponent *)
 
void finished (const Array< URL > &)
 

Static Private Member Functions

static PimplshowPlatformDialog (FileChooser &, int, FilePreviewComponent *)
 

Private Attributes

std::function< void(const FileChooser &)> asyncCallback
 
String filters
 
Componentparent
 
std::unique_ptr< Pimplpimpl
 
Array< URLresults
 
File startingFile
 
String title
 
const bool treatFilePackagesAsDirs
 
const bool useNativeDialogBox
 

Friends

class Native
 
class NonNative
 

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...",
"*.moose");
if (myChooser.browseForFileToOpen())
{
File mooseFile (myChooser.getResult());
loadMoose (mooseFile);
}
}

{GUI}

Constructor & Destructor Documentation

◆ FileChooser()

juce::FileChooser::FileChooser ( const String dialogBoxTitle,
const File initialFileOrDirectory = File(),
const String filePatternsAllowed = String(),
bool  useOSNativeDialogBox = true,
bool  treatFilePackagesAsDirectories = false,
Component parentComponent = nullptr 
)

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(), a sensible default directory will be used instead. When using native dialogs, not all platforms will actually select the file. For example, on macOS, when initialFileOrDirectory is a file, only the parent directory of initialFileOrDirectory will be used as the initial directory of the native file chooser.

Note: On iOS when saving a file, a user will not be able to change a file name, so it may be a good idea to include at least a valid file name in initialFileOrDirectory. When no filename is found, "Untitled" will be used.

Also, if you pass an already existing file on iOS, that file will be automatically copied to the destination chosen by user and if it can be previewed, its preview will be presented in the dialog too. You will still be able to write into this file copy, since its URL will be returned by getURLResult(). This can be useful when you want to save e.g. an image, so that you can pass a (temporary) file with low quality preview and after the user picks the destination, you can write a high quality image into the copied file. If you create such a temporary file, you need to delete it yourself, once it is not needed anymore.

Parameters
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". The native MacOS file browser only supports wildcard that specify extensions, so "*.jpg" is OK but "myfilename*" will not work. 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
treatFilePackagesAsDirectoriesif true, then the file chooser will allow the selection of files inside packages when invoked on OS X and when using native dialog boxes.
parentComponentAn optional component which should be the parent for the file chooser. If this is a nullptr then the FileChooser will be a top-level window. AUv3s on iOS must specify this parameter as opening a top-level window in an AUv3 is forbidden due to sandbox restrictions.
See also
browseForFileToOpen, browseForFileToSave, browseForDirectory

◆ ~FileChooser()

juce::FileChooser::~FileChooser ( )

Destructor.

Member Function Documentation

◆ browseForDirectory()

bool juce::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 juce::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 juce::StandalonePluginHolder::askUserToLoadState().

◆ browseForFileToSave()

bool juce::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 juce::StandalonePluginHolder::askUserToSaveState().

◆ browseForMultipleFilesOrDirectories()

bool juce::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 juce::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.

◆ createPimpl()

Pimpl* juce::FileChooser::createPimpl ( int  ,
FilePreviewComponent  
)
private

◆ finished()

void juce::FileChooser::finished ( const Array< URL > &  )
private

◆ getResult()

File juce::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).

On mobile platforms, the file browser may return a URL instead of a local file. Therefore, om mobile platforms, you should call getURLResult() instead.

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

See also
getURLResult, getResults

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

◆ getResults()

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

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

On mobile platforms, the file browser may return a URL instead of a local file. Therefore, om mobile platforms, you should call getURLResults() instead.

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

See also
getURLResults, getResult

◆ getURLResult()

URL juce::FileChooser::getURLResult ( ) const

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

Use this method if you are using the FileChooser on a mobile platform which may return a URL to a remote document. If a local file is chosen then you can convert this file to a JUCE File class via the URL::getLocalFile method.

Note: On iOS you must use the returned URL object directly (you are also allowed to copy- or move-construct another URL from the returned URL), rather than just storing the path as a String and then creating a new URL from that String. This is because the returned URL contains internally a security bookmark that is required to access the files pointed by it. Then, once you stop dealing with the file pointed by the URL, you should dispose that URL object, so that the security bookmark can be released by the system (only a limited number of such URLs is allowed).

See also
getResult, URL::getLocalFile

◆ getURLResults()

const Array<URL>& juce::FileChooser::getURLResults ( ) const
inlinenoexcept

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

Use this method if you are using the FileChooser on a mobile platform which may return a URL to a remote document. If a local file is chosen then you can convert this file to a JUCE File class via the URL::getLocalFile method.

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

Note: On iOS you must use the returned URL object directly (you are also allowed to copy- or move-construct another URL from the returned URL), rather than just storing the path as a String and then creating a new URL from that String. This is because the returned URL contains internally a security bookmark that is required to access the files pointed by it. Then, once you stop dealing with the file pointed by the URL, you should dispose that URL object, so that the security bookmark can be released by the system (only a limited number of such URLs is allowed).

See also
getResults, URL::getLocalFile

◆ isPlatformDialogAvailable()

static bool juce::FileChooser::isPlatformDialogAvailable ( )
static

Returns if a native filechooser is currently available on this platform.

Note: On iOS this will only return true if you have iCloud permissions and code-signing enabled in the Projucer and have added iCloud containers to your app in Apple's online developer portal. Additionally, the user must have installed the iCloud app on their device and used the app at leat once.

◆ launchAsync()

void juce::FileChooser::launchAsync ( int  flags,
std::function< void(const FileChooser &)>  ,
FilePreviewComponent previewComponent = nullptr 
)

Use this method to launch the file browser window asynchronously.

This will create a file browser dialog based on the settings in this structure and will launch it modally, returning immediately.

You must specify a callback which is called when the file browser is canceled or a file is selected. To abort the file selection, simply delete the FileChooser object.

You can use the ModalCallbackFunction::create method to wrap a lambda into a modal Callback object.

You must ensure that the lifetime of the callback object is longer than the lifetime of the file-chooser.

◆ showDialog()

bool juce::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 Pimpl* juce::FileChooser::showPlatformDialog ( FileChooser ,
int  ,
FilePreviewComponent  
)
staticprivate

Friends And Related Function Documentation

◆ Native

friend class Native
friend

◆ NonNative

friend class NonNative
friend

Member Data Documentation

◆ asyncCallback

std::function<void (const FileChooser&)> juce::FileChooser::asyncCallback
private

◆ filters

String juce::FileChooser::filters
private

◆ parent

Component* juce::FileChooser::parent
private

◆ pimpl

std::unique_ptr<Pimpl> juce::FileChooser::pimpl
private

◆ results

Array<URL> juce::FileChooser::results
private

◆ startingFile

File juce::FileChooser::startingFile
private

◆ title

String juce::FileChooser::title
private

◆ treatFilePackagesAsDirs

const bool juce::FileChooser::treatFilePackagesAsDirs
private

◆ useNativeDialogBox

const bool juce::FileChooser::useNativeDialogBox
private

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