JUCE
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
Public Types | Public Member Functions | Protected Member Functions | List of all members
FileBasedDocument Class Referenceabstract

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

Inherits ChangeBroadcaster.

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.
 
virtual ~FileBasedDocument ()
 Destructor.
 
bool hasChangedSinceSaved () const
 Returns true if the changed() method has been called since the file was last saved or loaded.
 
virtual void changed ()
 Called to indicate that the document has changed and needs saving.
 
void setChangedFlag (bool hasChanged)
 Sets the state of the 'changed' flag.
 
Result loadFrom (const File &fileToLoadFrom, bool showMessageOnFailure)
 Tries to open a file.
 
Result loadFromUserSpecifiedFile (bool showMessageOnFailure)
 Asks the user for a file and tries to load it.
 
SaveResult save (bool askUserForFileIfNotSpecified, bool showMessageOnFailure)
 Tries to save the document to the last file it was saved or loaded from.
 
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.
 
SaveResult saveAs (const File &newFile, bool warnAboutOverwritingExistingFiles, bool askUserForFileIfNotSpecified, bool showMessageOnFailure)
 Tries to save the document to a specified file.
 
SaveResult saveAsInteractive (bool warnAboutOverwritingExistingFiles)
 Prompts the user for a filename and tries to save to it.
 
const FilegetFile () const
 Returns the file that this document was last successfully saved or loaded from.
 
void setFile (const File &newFile)
 Sets the file that this document thinks it was loaded from.
 
- Public Member Functions inherited from ChangeBroadcaster
 ChangeBroadcaster () noexcept
 Creates an ChangeBroadcaster.
 
virtual ~ChangeBroadcaster ()
 Destructor.
 
void addChangeListener (ChangeListener *listener)
 Registers a listener to receive change callbacks from this broadcaster.
 
void removeChangeListener (ChangeListener *listener)
 Unregisters a listener from the list.
 
void removeAllChangeListeners ()
 Removes all listeners from the list.
 
void sendChangeMessage ()
 Causes an asynchronous change message to be sent to all the registered listeners.
 
void sendSynchronousChangeMessage ()
 Sends a synchronous change message to all the registered listeners.
 
void dispatchPendingMessages ()
 If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.
 

Protected Member Functions

virtual String getDocumentTitle ()=0
 Overload this to return the title of the document.
 
virtual Result loadDocument (const File &file)=0
 This method should try to load your document from the given file.
 
virtual Result saveDocument (const File &file)=0
 This method should try to write your document to the given file.
 
virtual File getLastDocumentOpened ()=0
 This is used for dialog boxes to make them open at the last folder you were using.
 
virtual void setLastDocumentOpened (const File &file)=0
 This is used for dialog boxes to make them open at the last folder you were using.
 

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

Member Enumeration Documentation

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::FileBasedDocument ( const String fileExtension,
const String fileWildCard,
const String openFileDialogTitle,
const String saveFileDialogTitle 
)

Creates a FileBasedDocument.

Parameters
fileExtensionthe extension to use when loading/saving files, e.g. ".doc"
fileWildCardthe wildcard to use in file dialogs, e.g. "*.doc"
openFileDialogTitlethe title to show on an open-file dialog, e.g. "Choose a file to open.."
saveFileDialogTitlethe title to show on an save-file dialog, e.g. "Choose a file to save as.."
virtual FileBasedDocument::~FileBasedDocument ( )
virtual

Destructor.

Member Function Documentation

bool FileBasedDocument::hasChangedSinceSaved ( ) const

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

See Also
setChangedFlag, changed
virtual void 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
void 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
Result FileBasedDocument::loadFrom ( const File fileToLoadFrom,
bool  showMessageOnFailure 
)

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
Result 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
SaveResult 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
askUserForFileIfNotSpecifiedif there's no file currently specified and this is true, it will prompt the user to pick a file, as if saveAsInteractive() was called.
showMessageOnFailureif true it will show a warning message when if the save operation fails
See Also
saveIfNeededAndUserAgrees, saveAs, saveAsInteractive
SaveResult 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
SaveResult FileBasedDocument::saveAs ( const File newFile,
bool  warnAboutOverwritingExistingFiles,
bool  askUserForFileIfNotSpecified,
bool  showMessageOnFailure 
)

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
newFilethe file to try to write to
warnAboutOverwritingExistingFilesif true and the file exists, it'll ask the user first if they want to overwrite it
askUserForFileIfNotSpecifiedif the file is non-existent and this is true, it'll use the saveAsInteractive() method to ask the user for a filename
showMessageOnFailureif true and the write operation fails, it'll show a message box to warn the user
See Also
saveIfNeededAndUserAgrees, save, saveAsInteractive
SaveResult 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
warnAboutOverwritingExistingFilesif true and the file exists, it'll ask the user first if they want to overwrite it
See Also
saveIfNeededAndUserAgrees, save, saveAs
const File& 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::nonexistent.

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

void 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
virtual String 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.

virtual Result 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.
virtual Result 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.
virtual File 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::nonexistent, and the document object will use a sensible one instead.

See Also
RecentlyOpenedFilesList
virtual void 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

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