A class to take care of the logic involved with the loading/saving of some kind of document. More...

#include <juce_FileBasedDocument.h>

Inheritance diagram for juce::FileBasedDocument:

Collaboration diagram for juce::FileBasedDocument:

[legend]

Public Types
enum	SaveResult { savedOk = 0, userCancelledSave, failedToWriteToFile }
	A set of possible outcomes of one of the save() methods. More...

Public Member Functions
	FileBasedDocument (const String &fileExtension, const String &fileWildCard, const String &openFileDialogTitle, const String &saveFileDialogTitle)
	Creates a FileBasedDocument. More...

	~FileBasedDocument () override
	Destructor. More...

void	addChangeListener (ChangeListener *listener)
	Registers a listener to receive change callbacks from this broadcaster. More...

virtual void	changed ()
	Called to indicate that the document has changed and needs saving. More...

void	dispatchPendingMessages ()
	If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...

const File &	getFile () const
	Returns the file that this document was last successfully saved or loaded from. More...

bool	hasChangedSinceSaved () const
	Returns true if the changed() method has been called since the file was last saved or loaded. More...

Result	loadFrom (const File &fileToLoadFrom, bool showMessageOnFailure, bool showWaitCursor=true)
	Tries to open a file. More...

void	loadFromAsync (const File &fileToLoadFrom, bool showMessageOnFailure, std::function< void(Result)> callback)
	Tries to open a file. More...

Result	loadFromUserSpecifiedFile (bool showMessageOnFailure)
	Asks the user for a file and tries to load it. More...

void	loadFromUserSpecifiedFileAsync (bool showMessageOnFailure, std::function< void(Result)> callback)
	Asks the user for a file and tries to load it. More...

void	removeAllChangeListeners ()
	Removes all listeners from the list. More...

void	removeChangeListener (ChangeListener *listener)
	Unregisters a listener from the list. More...

SaveResult	save (bool askUserForFileIfNotSpecified, bool showMessageOnFailure)
	Tries to save the document to the last file it was saved or loaded from. More...

SaveResult	saveAs (const File &newFile, bool warnAboutOverwritingExistingFiles, bool askUserForFileIfNotSpecified, bool showMessageOnFailure, bool showWaitCursor=true)
	Tries to save the document to a specified file. More...

void	saveAsAsync (const File &newFile, bool warnAboutOverwritingExistingFiles, bool askUserForFileIfNotSpecified, bool showMessageOnFailure, std::function< void(SaveResult)> callback)
	Tries to save the document to a specified file. More...

SaveResult	saveAsInteractive (bool warnAboutOverwritingExistingFiles)
	Prompts the user for a filename and tries to save to it. More...

void	saveAsInteractiveAsync (bool warnAboutOverwritingExistingFiles, std::function< void(SaveResult)> callback)
	Prompts the user for a filename and tries to save to it. More...

void	saveAsync (bool askUserForFileIfNotSpecified, bool showMessageOnFailure, std::function< void(SaveResult)> callback)
	Tries to save the document to the last file it was saved or loaded from. More...

SaveResult	saveIfNeededAndUserAgrees ()
	If the file needs saving, it'll ask the user if that's what they want to do, and save it if they say yes. More...

void	saveIfNeededAndUserAgreesAsync (std::function< void(SaveResult)> callback)
	If the file needs saving, it'll ask the user if that's what they want to do, and save it if they say yes. More...

void	sendChangeMessage ()
	Causes an asynchronous change message to be sent to all the registered listeners. More...

void	sendSynchronousChangeMessage ()
	Sends a synchronous change message to all the registered listeners. More...

void	setChangedFlag (bool hasChanged)
	Sets the state of the 'changed' flag. More...

void	setFile (const File &newFile)
	Sets the file that this document thinks it was loaded from. More...

Protected Member Functions
virtual String	getDocumentTitle ()=0
	Overload this to return the title of the document. More...

virtual File	getLastDocumentOpened ()=0
	This is used for dialog boxes to make them open at the last folder you were using. More...

virtual File	getSuggestedSaveAsFile (const File &defaultFile)
	This is called by saveAsInteractiveAsync() to allow you to optionally customise the filename that the user is presented with in the save dialog. More...

virtual Result	loadDocument (const File &file)=0
	This method should try to load your document from the given file. More...

virtual void	loadDocumentAsync (const File &file, std::function< void(Result)> callback)
	This method should try to load your document from the given file, then call the provided callback on the message thread, passing the result of the load. More...

virtual Result	saveDocument (const File &file)=0
	This method should try to write your document to the given file. More...

virtual void	saveDocumentAsync (const File &file, std::function< void(Result)> callback)
	This method should try to write your document to the given file, then call the provided callback on the message thread, passing the result of the write. More...

virtual void	setLastDocumentOpened (const File &file)=0
	This is used for dialog boxes to make them open at the last folder you were using. More...

Private Member Functions
void	callListeners ()

Private Attributes
std::atomic< bool >	anyListeners { false }

ChangeBroadcasterCallback	broadcastCallback

ListenerList< ChangeListener >	changeListeners

std::unique_ptr< Pimpl >	pimpl

Detailed Description

A class to take care of the logic involved with the loading/saving of some kind of document.

There's quite a lot of tedious logic involved in writing all the load/save/save-as functions you need for documents that get saved to a file, so this class attempts to abstract most of the boring stuff.

Your subclass should just implement all the pure virtual methods, and you can then use the higher-level public methods to do the load/save dialogs, to warn the user about overwriting files, etc.

The document object keeps track of whether it has changed since it was last saved or loaded, so when you change something, call its changed() method. This will set a flag so it knows it needs saving, and will also broadcast a change message using the ChangeBroadcaster base class.

See also: ChangeBroadcaster

@tags{GUI}

Member Enumeration Documentation

◆ SaveResult

enum juce::FileBasedDocument::SaveResult

A set of possible outcomes of one of the save() methods.

Enumerator
savedOk	indicates that a file was saved successfully.
userCancelledSave	indicates that the user aborted the save operation.
failedToWriteToFile	indicates that it tried to write to a file but this failed.

Constructor & Destructor Documentation

◆ FileBasedDocument()

juce::FileBasedDocument::FileBasedDocument	(	const String &	fileExtension,
		const String &	fileWildCard,
		const String &	openFileDialogTitle,
		const String &	saveFileDialogTitle
	)

Creates a FileBasedDocument.

Parameters

fileExtension	the extension to use when loading/saving files, e.g. ".doc"
fileWildCard	the wildcard to use in file dialogs, e.g. "*.doc"
openFileDialogTitle	the title to show on an open-file dialog, e.g. "Choose a file to open.."
saveFileDialogTitle	the title to show on an save-file dialog, e.g. "Choose a file to save as.."

◆ ~FileBasedDocument()

juce::FileBasedDocument::~FileBasedDocument ( )

override

Destructor.

Member Function Documentation

◆ addChangeListener()

void juce::ChangeBroadcaster::addChangeListener ( ChangeListener * listener )

inherited

Registers a listener to receive change callbacks from this broadcaster.

Trying to add a listener that's already on the list will have no effect.

◆ callListeners()

void juce::ChangeBroadcaster::callListeners ( )

privateinherited

◆ changed()

virtual void juce::FileBasedDocument::changed ( )

virtual

Called to indicate that the document has changed and needs saving.

This method will also trigger a change message to be sent out using the ChangeBroadcaster base class.

After calling the method, the hasChangedSinceSaved() method will return true, until it is reset either by saving to a file or using the setChangedFlag() method.

See also: hasChangedSinceSaved, setChangedFlag

◆ dispatchPendingMessages()

void juce::ChangeBroadcaster::dispatchPendingMessages ( )

inherited

If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

For thread-safety reasons, you must only call this method on the main message thread.

◆ getDocumentTitle()

virtual String juce::FileBasedDocument::getDocumentTitle ( )

protectedpure virtual

Overload this to return the title of the document.

This is used in message boxes, filenames and file choosers, so it should be something sensible.

◆ getFile()

const File& juce::FileBasedDocument::getFile ( ) const

Returns the file that this document was last successfully saved or loaded from.

When the document object is created, this will be set to File().

It is changed when one of the load or save methods is used, or when setFile() is used to explicitly set it.

◆ getLastDocumentOpened()

virtual File juce::FileBasedDocument::getLastDocumentOpened ( )

protectedpure virtual

This is used for dialog boxes to make them open at the last folder you were using.

getLastDocumentOpened() and setLastDocumentOpened() are used to store the last document that was used - you might want to store this value in a static variable, or even in your application's properties. It should be a global setting rather than a property of this object.

This method works very well in conjunction with a RecentlyOpenedFilesList object to manage your recent-files list.

As a default value, it's ok to return File(), and the document object will use a sensible one instead.

See also: RecentlyOpenedFilesList

◆ getSuggestedSaveAsFile()

virtual File juce::FileBasedDocument::getSuggestedSaveAsFile ( const File & defaultFile )

protectedvirtual

This is called by saveAsInteractiveAsync() to allow you to optionally customise the filename that the user is presented with in the save dialog.

The defaultFile parameter is an initial suggestion based on what the class knows about the current document - you can return a variation on this file with a different extension, etc, or just return something completely different.

◆ hasChangedSinceSaved()

bool juce::FileBasedDocument::hasChangedSinceSaved ( ) const

Returns true if the changed() method has been called since the file was last saved or loaded.

See also: setChangedFlag, changed

◆ loadDocument()

virtual Result juce::FileBasedDocument::loadDocument ( const File & file )

protectedpure virtual

This method should try to load your document from the given file.

Returns: a Result object to indicate the whether there was an error.

◆ loadDocumentAsync()

virtual void juce::FileBasedDocument::loadDocumentAsync	(	const File &	file,
		std::function< void(Result)>	callback
	)

protectedvirtual

This method should try to load your document from the given file, then call the provided callback on the message thread, passing the result of the load.

By default, this will synchronously call through to loadDocument.

For longer-running load operations, you may wish to override this function to run the load on a background thread, and then to call the callback later on the message thread to signal that the load has completed.

◆ loadFrom()

Result juce::FileBasedDocument::loadFrom	(	const File &	fileToLoadFrom,
		bool	showMessageOnFailure,
		bool	showWaitCursor = `true`
	)

Tries to open a file.

If the file opens correctly the document's file (see the getFile() method) is set to this new one; if it fails, the document's file is left unchanged, and optionally a message box is shown telling the user there was an error.

Returns: A result indicating whether the new file loaded successfully, or the error message if it failed.

See also: loadDocument, loadFromUserSpecifiedFile

◆ loadFromAsync()

void juce::FileBasedDocument::loadFromAsync	(	const File &	fileToLoadFrom,
		bool	showMessageOnFailure,
		std::function< void(Result)>	callback
	)

Tries to open a file.

The callback is called with the result indicating whether the new file loaded successfully, or the error message if it failed.

If the file opens correctly the document's file (see the getFile() method) is set to this new one; if it fails, the document's file is left unchanged, and optionally a message box is shown telling the user there was an error.

See also: loadDocumentAsync, loadFromUserSpecifiedFileAsync

◆ loadFromUserSpecifiedFile()

Result juce::FileBasedDocument::loadFromUserSpecifiedFile ( bool showMessageOnFailure )

Asks the user for a file and tries to load it.

This will pop up a dialog box using the title, file extension and wildcard specified in the document's constructor, and asks the user for a file. If they pick one, the loadFrom() method is used to try to load it, optionally showing a message if it fails.

Returns: a result indicating success; This will be a failure message if the user cancelled or if they picked a file which failed to load correctly

See also: loadFrom

◆ loadFromUserSpecifiedFileAsync()

void juce::FileBasedDocument::loadFromUserSpecifiedFileAsync	(	bool	showMessageOnFailure,
		std::function< void(Result)>	callback
	)

Asks the user for a file and tries to load it.

This will pop up a dialog box using the title, file extension and wildcard specified in the document's constructor, and asks the user for a file. If they pick one, the loadFrom() method is used to try to load it, optionally showing a message if it fails. The result of the operation is provided in the callback function.

See also: loadFrom

◆ removeAllChangeListeners()

void juce::ChangeBroadcaster::removeAllChangeListeners ( )

inherited

Removes all listeners from the list.

◆ removeChangeListener()

void juce::ChangeBroadcaster::removeChangeListener ( ChangeListener * listener )

inherited

Unregisters a listener from the list.

If the listener isn't on the list, this won't have any effect.

◆ save()

SaveResult juce::FileBasedDocument::save	(	bool	askUserForFileIfNotSpecified,
		bool	showMessageOnFailure
	)

Tries to save the document to the last file it was saved or loaded from.

This will always try to write to the file, even if the document isn't flagged as having changed.

Parameters

askUserForFileIfNotSpecified	if there's no file currently specified and this is true, it will prompt the user to pick a file, as if saveAsInteractive() was called.
showMessageOnFailure	if true it will show a warning message when if the save operation fails

See also: saveIfNeededAndUserAgrees, saveAs, saveAsInteractive

◆ saveAs()

SaveResult juce::FileBasedDocument::saveAs	(	const File &	newFile,
		bool	warnAboutOverwritingExistingFiles,
		bool	askUserForFileIfNotSpecified,
		bool	showMessageOnFailure,
		bool	showWaitCursor = `true`
	)

Tries to save the document to a specified file.

If this succeeds, it'll also change the document's internal file (as returned by the getFile() method). If it fails, the file will be left unchanged.

Parameters

newFile	the file to try to write to
warnAboutOverwritingExistingFiles	if true and the file exists, it'll ask the user first if they want to overwrite it
askUserForFileIfNotSpecified	if the file is non-existent and this is true, it'll use the saveAsInteractive() method to ask the user for a filename
showMessageOnFailure	if true and the write operation fails, it'll show a message box to warn the user
showWaitCursor	if true, the 'wait' mouse cursor will be showin during saving

See also: saveIfNeededAndUserAgrees, save, saveAsInteractive

◆ saveAsAsync()

void juce::FileBasedDocument::saveAsAsync	(	const File &	newFile,
		bool	warnAboutOverwritingExistingFiles,
		bool	askUserForFileIfNotSpecified,
		bool	showMessageOnFailure,
		std::function< void(SaveResult)>	callback
	)

Tries to save the document to a specified file.

If this succeeds, it'll also change the document's internal file (as returned by the getFile() method). If it fails, the file will be left unchanged.

Parameters

newFile	the file to try to write to
warnAboutOverwritingExistingFiles	if true and the file exists, it'll ask the user first if they want to overwrite it
askUserForFileIfNotSpecified	if the file is non-existent and this is true, it'll use the saveAsInteractive() method to ask the user for a filename
showMessageOnFailure	if true and the write operation fails, it'll show a message box to warn the user
callback	called with the result of the save operation

See also: saveIfNeededAndUserAgreesAsync, saveAsync, saveAsInteractiveAsync

◆ saveAsInteractive()

SaveResult juce::FileBasedDocument::saveAsInteractive ( bool warnAboutOverwritingExistingFiles )

Prompts the user for a filename and tries to save to it.

This will pop up a dialog box using the title, file extension and wildcard specified in the document's constructor, and asks the user for a file. If they pick one, the saveAs() method is used to try to save to this file.

Parameters

warnAboutOverwritingExistingFiles if true and the file exists, it'll ask the user first if they want to overwrite it

See also: saveIfNeededAndUserAgrees, save, saveAs

◆ saveAsInteractiveAsync()

void juce::FileBasedDocument::saveAsInteractiveAsync	(	bool	warnAboutOverwritingExistingFiles,
		std::function< void(SaveResult)>	callback
	)

Prompts the user for a filename and tries to save to it.

This will pop up a dialog box using the title, file extension and wildcard specified in the document's constructor, and asks the user for a file. If they pick one, the saveAs() method is used to try to save to this file.

Parameters

warnAboutOverwritingExistingFiles	if true and the file exists, it'll ask the user first if they want to overwrite it
callback	called with the result of the save operation

See also: saveIfNeededAndUserAgreesAsync, saveAsync, saveAsAsync

◆ saveAsync()

void juce::FileBasedDocument::saveAsync	(	bool	askUserForFileIfNotSpecified,
		bool	showMessageOnFailure,
		std::function< void(SaveResult)>	callback
	)

Tries to save the document to the last file it was saved or loaded from.

This will always try to write to the file, even if the document isn't flagged as having changed.

Parameters

askUserForFileIfNotSpecified	if there's no file currently specified and this is true, it will prompt the user to pick a file, as if saveAsInteractive() was called.
showMessageOnFailure	if true it will show a warning message when if the save operation fails
callback	called after the save operation with the result

See also: saveIfNeededAndUserAgrees, saveAs, saveAsInteractive

◆ saveDocument()

virtual Result juce::FileBasedDocument::saveDocument ( const File & file )

protectedpure virtual

This method should try to write your document to the given file.

Returns: a Result object to indicate the whether there was an error.

◆ saveDocumentAsync()

virtual void juce::FileBasedDocument::saveDocumentAsync	(	const File &	file,
		std::function< void(Result)>	callback
	)

protectedvirtual

This method should try to write your document to the given file, then call the provided callback on the message thread, passing the result of the write.

By default, this will synchronously call through to saveDocument.

For longer-running save operations, you may wish to override this function to run the save on a background thread, and then to call the callback later on the message thread to signal that the save has completed.

◆ saveIfNeededAndUserAgrees()

SaveResult juce::FileBasedDocument::saveIfNeededAndUserAgrees ( )

If the file needs saving, it'll ask the user if that's what they want to do, and save it if they say yes.

If you've got a document open and want to close it (e.g. to quit the app), this is the method to call.

If the document doesn't need saving it'll return the value savedOk so you can go ahead and delete the document.

If it does need saving it'll prompt the user, and if they say "discard changes" it'll return savedOk, so again, you can safely delete the document.

If the user clicks "cancel", it'll return userCancelledSave, so if you can abort the close-document operation.

And if they click "save changes", it'll try to save and either return savedOk, or failedToWriteToFile if there was a problem.

See also: save, saveAs, saveAsInteractive

◆ saveIfNeededAndUserAgreesAsync()

void juce::FileBasedDocument::saveIfNeededAndUserAgreesAsync ( std::function< void(SaveResult)> callback )

If the file needs saving, it'll ask the user if that's what they want to do, and save it if they say yes.

If you've got a document open and want to close it (e.g. to quit the app), this is the method to call.

If the document doesn't need saving the callback will be called with the value savedOk so you can go ahead and delete the document.

If it does need saving it'll prompt the user, and if they say "discard changes" the callback will be called with savedOk, so again, you can safely delete the document.

If the user clicks "cancel", the callback will be called with userCancelledSave, so you can abort the close-document operation.

And if they click "save changes", it'll try to save and the callback will be called with either savedOk, or failedToWriteToFile if there was a problem.

See also: saveAsync, saveAsAsync, saveAsInteractiveAsync

◆ sendChangeMessage()

void juce::ChangeBroadcaster::sendChangeMessage ( )

inherited

Causes an asynchronous change message to be sent to all the registered listeners.

The message will be delivered asynchronously by the main message thread, so this method will return immediately. To call the listeners synchronously use sendSynchronousChangeMessage().

Referenced by juce::SelectedItemSet< SelectableItemType >::changed().

◆ sendSynchronousChangeMessage()

void juce::ChangeBroadcaster::sendSynchronousChangeMessage ( )

inherited

Sends a synchronous change message to all the registered listeners.

This will immediately call all the listeners that are registered. For thread-safety reasons, you must only call this method on the main message thread.

See also: dispatchPendingMessages

Referenced by juce::SelectedItemSet< SelectableItemType >::changed().

◆ setChangedFlag()

void juce::FileBasedDocument::setChangedFlag ( bool hasChanged )

Sets the state of the 'changed' flag.

The 'changed' flag is set to true when the changed() method is called - use this method to reset it or to set it without also broadcasting a change message.

See also: changed, hasChangedSinceSaved

◆ setFile()

void juce::FileBasedDocument::setFile ( const File & newFile )

Sets the file that this document thinks it was loaded from.

This won't actually load anything - it just changes the file stored internally.

See also: getFile

◆ setLastDocumentOpened()

virtual void juce::FileBasedDocument::setLastDocumentOpened ( const File & file )

protectedpure virtual

This is used for dialog boxes to make them open at the last folder you were using.

getLastDocumentOpened() and setLastDocumentOpened() are used to store the last document that was used - you might want to store this value in a static variable, or even in your application's properties. It should be a global setting rather than a property of this object.

This method works very well in conjunction with a RecentlyOpenedFilesList object to manage your recent-files list.

See also: RecentlyOpenedFilesList

Member Data Documentation

◆ anyListeners

std::atomic<bool> juce::ChangeBroadcaster::anyListeners { false }

privateinherited

◆ broadcastCallback

ChangeBroadcasterCallback juce::ChangeBroadcaster::broadcastCallback

privateinherited

◆ changeListeners

ListenerList<ChangeListener> juce::ChangeBroadcaster::changeListeners

privateinherited

◆ pimpl

std::unique_ptr<Pimpl> juce::FileBasedDocument::pimpl

private

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

juce_FileBasedDocument.h

Public Types

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ SaveResult

Constructor & Destructor Documentation

◆ FileBasedDocument()

◆ ~FileBasedDocument()

Member Function Documentation

◆ addChangeListener()

◆ callListeners()

◆ changed()

◆ dispatchPendingMessages()

◆ getDocumentTitle()

◆ getFile()

◆ getLastDocumentOpened()

◆ getSuggestedSaveAsFile()

◆ hasChangedSinceSaved()

◆ loadDocument()

◆ loadDocumentAsync()

◆ loadFrom()

◆ loadFromAsync()

◆ loadFromUserSpecifiedFile()

◆ loadFromUserSpecifiedFileAsync()

◆ removeAllChangeListeners()

◆ removeChangeListener()

◆ save()

◆ saveAs()

◆ saveAsAsync()

◆ saveAsInteractive()

◆ saveAsInteractiveAsync()

◆ saveAsync()

◆ saveDocument()

◆ saveDocumentAsync()

◆ saveIfNeededAndUserAgrees()

◆ saveIfNeededAndUserAgreesAsync()

◆ sendChangeMessage()

◆ sendSynchronousChangeMessage()

◆ setChangedFlag()

◆ setFile()

◆ setLastDocumentOpened()

Member Data Documentation

◆ anyListeners

◆ broadcastCallback

◆ changeListeners

◆ pimpl