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

#include "juce_FileChooser.h"

Classes
class	Native

class	NonNative

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.

	~FileChooser ()
	Destructor.

void	launchAsync (int flags, std::function< void(const FileChooser &)>, FilePreviewComponent *previewComponent=nullptr)
	Use this method to launch the file browser window asynchronously.

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

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

URL	getURLResult () const
	Returns the last document that was chosen by one of the browseFor methods.

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

Static Public Member Functions
static bool	isPlatformDialogAvailable ()
	Returns if a native filechooser is currently available on this platform.

static void	registerCustomMimeTypeForFileExtension (const String &mimeType, const String &fileExtension)
	Associate a particular file-extension to a mime-type.

Friends
class	NonNative

class	Native

Detailed Description

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

std::unique_ptr<FileChooser> myChooser;
 
void loadMooseFile()
{
    myChooser = std::make_unique<FileChooser> ("Please select the moose you want to load...",
                                               File::getSpecialLocation (File::userHomeDirectory),
                                               "*.moose");
 
    auto folderChooserFlags = FileBrowserComponent::openMode | FileBrowserComponent::canSelectDirectories;
 
    myChooser->launchAsync (folderChooserFlags, [this] (const FileChooser& chooser)
    {
        File mooseFile (chooser.getResult());
 
        loadMoose (mooseFile);
    });
}

@tags{GUI}

Definition at line 55 of file juce_FileChooser.h.

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

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

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". 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
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.
parentComponent	An 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

Definition at line 100 of file juce_FileChooser.cpp.

◆ ~FileChooser()

juce::FileChooser::~FileChooser ( )

Destructor.

Definition at line 121 of file juce_FileChooser.cpp.

Member Function Documentation

◆ 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, on 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

Definition at line 240 of file juce_FileChooser.cpp.

◆ 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, on 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

Definition at line 229 of file juce_FileChooser.cpp.

◆ 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

Definition at line 251 of file juce_FileChooser.cpp.

◆ getURLResults()

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

noexcept

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

Definition at line 284 of file juce_FileChooser.h.

◆ isPlatformDialogAvailable()

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

Definition at line 272 of file juce_FileChooser_linux.cpp.

◆ launchAsync()

void juce::FileChooser::launchAsync	(	int	flags,
		std::function< void(const FileChooser &)>	callback,
		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 cancelled or a file is selected. To abort the file selection, simply delete the FileChooser object.

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

Definition at line 180 of file juce_FileChooser.cpp.

◆ registerCustomMimeTypeForFileExtension()

void juce::FileChooser::registerCustomMimeTypeForFileExtension	(	const String &	mimeType,
		const String &	fileExtension
	)

static

Associate a particular file-extension to a mime-type.

On Android, JUCE needs to convert common file extensions to mime-types when using wildcard filters in native file chooser dialog boxes. JUCE has an extensive conversion table to convert between the most common file-types and mime-types transparently, but some more obscure file-types may be missing. Use this method to register your own mime-type to file extension conversions. Please contact the JUCE team if you think that a common mime-type/file-extension entry is missing in JUCE's internal tables. Does nothing on other platforms.

Definition at line 273 of file juce_FileChooser.cpp.

Friends And Related Symbol Documentation

◆ Native

friend class Native

friend

Definition at line 344 of file juce_FileChooser.h.

◆ NonNative

friend class NonNative