juce/source/src/utilities/juce_FileBasedDocument.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_FILEBASEDDOCUMENT_JUCEHEADER__
  27 #define __JUCE_FILEBASEDDOCUMENT_JUCEHEADER__
  28
  29 #include "../io/files/juce_File.h"
  30 #include "../events/juce_ChangeBroadcaster.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     A class to take care of the logic involved with the loading/saving of some kind
  36     of document.
  37
  38     There's quite a lot of tedious logic involved in writing all the load/save/save-as
  39     functions you need for documents that get saved to a file, so this class attempts
  40     to abstract most of the boring stuff.
  41
  42     Your subclass should just implement all the pure virtual methods, and you can
  43     then use the higher-level public methods to do the load/save dialogs, to warn the user
  44     about overwriting files, etc.
  45
  46     The document object keeps track of whether it has changed since it was last saved or
  47     loaded, so when you change something, call its changed() method. This will set a
  48     flag so it knows it needs saving, and will also broadcast a change message using the
  49     ChangeBroadcaster base class.
  50
  51     @see ChangeBroadcaster
  52 */
  53 class JUCE_API FileBasedDocument  : public ChangeBroadcaster
  54 {
  55 public:
  56     /** Creates a FileBasedDocument.
  57
  58         @param fileExtension            the extension to use when loading/saving files, e.g. ".doc"
  59         @param fileWildCard             the wildcard to use in file dialogs, e.g. "*.doc"
  60         @param openFileDialogTitle      the title to show on an open-file dialog, e.g. "Choose a file to open.."
  61         @param saveFileDialogTitle      the title to show on an save-file dialog, e.g. "Choose a file to save as.."
  62     */
  63     FileBasedDocument (const String& fileExtension,
  64                        const String& fileWildCard,
  65                        const String& openFileDialogTitle,
  66                        const String& saveFileDialogTitle);
  67
  68     /** Destructor. */
  69     virtual ~FileBasedDocument();
  70
  71     //==============================================================================
  72     /** Returns true if the changed() method has been called since the file was
  73         last saved or loaded.
  74
  75         @see resetChangedFlag, changed
  76     */
  77     bool hasChangedSinceSaved() const                           { return changedSinceSave; }
  78
  79     /** Called to indicate that the document has changed and needs saving.
  80
  81         This method will also trigger a change message to be sent out using the
  82         ChangeBroadcaster base class.
  83
  84         After calling the method, the hasChangedSinceSaved() method will return true, until
  85         it is reset either by saving to a file or using the resetChangedFlag() method.
  86
  87         @see hasChangedSinceSaved, resetChangedFlag
  88     */
  89     virtual void changed();
  90
  91     /** Sets the state of the 'changed' flag.
  92
  93         The 'changed' flag is set to true when the changed() method is called - use this method
  94         to reset it or to set it without also broadcasting a change message.
  95
  96         @see changed, hasChangedSinceSaved
  97     */
  98     void setChangedFlag (bool hasChanged);
  99
 100     //==============================================================================
 101     /** Tries to open a file.
 102
 103         If the file opens correctly, the document's file (see the getFile() method) is set
 104         to this new one; if it fails, the document's file is left unchanged, and optionally
 105         a message box is shown telling the user there was an error.
 106
 107         @returns true if the new file loaded successfully
 108         @see loadDocument, loadFromUserSpecifiedFile
 109     */
 110     bool loadFrom (const File& fileToLoadFrom,
 111                    bool showMessageOnFailure);
 112
 113     /** Asks the user for a file and tries to load it.
 114
 115         This will pop up a dialog box using the title, file extension and
 116         wildcard specified in the document's constructor, and asks the user
 117         for a file. If they pick one, the loadFrom() method is used to
 118         try to load it, optionally showing a message if it fails.
 119
 120         @returns    true if a file was loaded; false if the user cancelled or if they
 121                     picked a file which failed to load correctly
 122         @see loadFrom
 123     */
 124     bool loadFromUserSpecifiedFile (bool showMessageOnFailure);
 125
 126     //==============================================================================
 127     /** A set of possible outcomes of one of the save() methods
 128     */
 129     enum SaveResult
 130     {
 131         savedOk = 0,            /**< indicates that a file was saved successfully. */
 132         userCancelledSave,      /**< indicates that the user aborted the save operation. */
 133         failedToWriteToFile     /**< indicates that it tried to write to a file but this failed. */
 134     };
 135
 136     /** Tries to save the document to the last file it was saved or loaded from.
 137
 138         This will always try to write to the file, even if the document isn't flagged as
 139         having changed.
 140
 141         @param askUserForFileIfNotSpecified     if there's no file currently specified and this is
 142                                                 true, it will prompt the user to pick a file, as if
 143                                                 saveAsInteractive() was called.
 144         @param showMessageOnFailure             if true it will show a warning message when if the
 145                                                 save operation fails
 146         @see saveIfNeededAndUserAgrees, saveAs, saveAsInteractive
 147     */
 148     SaveResult save (bool askUserForFileIfNotSpecified,
 149                      bool showMessageOnFailure);
 150
 151     /** If the file needs saving, it'll ask the user if that's what they want to do, and save
 152         it if they say yes.
 153
 154         If you've got a document open and want to close it (e.g. to quit the app), this is the
 155         method to call.
 156
 157         If the document doesn't need saving it'll return the value savedOk so
 158         you can go ahead and delete the document.
 159
 160         If it does need saving it'll prompt the user, and if they say "discard changes" it'll
 161         return savedOk, so again, you can safely delete the document.
 162
 163         If the user clicks "cancel", it'll return userCancelledSave, so if you can abort the
 164         close-document operation.
 165
 166         And if they click "save changes", it'll try to save and either return savedOk, or
 167         failedToWriteToFile if there was a problem.
 168
 169         @see save, saveAs, saveAsInteractive
 170     */
 171     SaveResult saveIfNeededAndUserAgrees();
 172
 173     /** Tries to save the document to a specified file.
 174
 175         If this succeeds, it'll also change the document's internal file (as returned by
 176         the getFile() method). If it fails, the file will be left unchanged.
 177
 178         @param newFile                      the file to try to write to
 179         @param warnAboutOverwritingExistingFiles    if true and the file exists, it'll ask
 180                                             the user first if they want to overwrite it
 181         @param askUserForFileIfNotSpecified if the file is non-existent and this is true, it'll
 182                                             use the saveAsInteractive() method to ask the user for a
 183                                             filename
 184         @param showMessageOnFailure         if true and the write operation fails, it'll show
 185                                             a message box to warn the user
 186         @see saveIfNeededAndUserAgrees, save, saveAsInteractive
 187     */
 188     SaveResult saveAs (const File& newFile,
 189                        bool warnAboutOverwritingExistingFiles,
 190                        bool askUserForFileIfNotSpecified,
 191                        bool showMessageOnFailure);
 192
 193     /** Prompts the user for a filename and tries to save to it.
 194
 195         This will pop up a dialog box using the title, file extension and
 196         wildcard specified in the document's constructor, and asks the user
 197         for a file. If they pick one, the saveAs() method is used to try to save
 198         to this file.
 199
 200         @param warnAboutOverwritingExistingFiles    if true and the file exists, it'll ask
 201                                             the user first if they want to overwrite it
 202         @see saveIfNeededAndUserAgrees, save, saveAs
 203     */
 204     SaveResult saveAsInteractive (bool warnAboutOverwritingExistingFiles);
 205
 206     //==============================================================================
 207     /** Returns the file that this document was last successfully saved or loaded from.
 208
 209         When the document object is created, this will be set to File::nonexistent.
 210
 211         It is changed when one of the load or save methods is used, or when setFile()
 212         is used to explicitly set it.
 213     */
 214     const File& getFile() const                             { return documentFile; }
 215
 216     /** Sets the file that this document thinks it was loaded from.
 217
 218         This won't actually load anything - it just changes the file stored internally.
 219
 220         @see getFile
 221     */
 222     void setFile (const File& newFile);
 223
 224
 225 protected:
 226     //==============================================================================
 227     /** Overload this to return the title of the document.
 228
 229         This is used in message boxes, filenames and file choosers, so it should be
 230         something sensible.
 231     */
 232     virtual const String getDocumentTitle() = 0;
 233
 234     /** This method should try to load your document from the given file.
 235
 236         If it fails, it should return an error message. If it succeeds, it should return
 237         an empty string.
 238     */
 239     virtual const String loadDocument (const File& file) = 0;
 240
 241     /** This method should try to write your document to the given file.
 242
 243         If it fails, it should return an error message. If it succeeds, it should return
 244         an empty string.
 245     */
 246     virtual const String saveDocument (const File& file) = 0;
 247
 248     /** This is used for dialog boxes to make them open at the last folder you
 249         were using.
 250
 251         getLastDocumentOpened() and setLastDocumentOpened() are used to store
 252         the last document that was used - you might want to store this value
 253         in a static variable, or even in your application's properties. It should
 254         be a global setting rather than a property of this object.
 255
 256         This method works very well in conjunction with a RecentlyOpenedFilesList
 257         object to manage your recent-files list.
 258
 259         As a default value, it's ok to return File::nonexistent, and the document
 260         object will use a sensible one instead.
 261
 262         @see RecentlyOpenedFilesList
 263     */
 264     virtual const File getLastDocumentOpened() = 0;
 265
 266     /** This is used for dialog boxes to make them open at the last folder you
 267         were using.
 268
 269         getLastDocumentOpened() and setLastDocumentOpened() are used to store
 270         the last document that was used - you might want to store this value
 271         in a static variable, or even in your application's properties. It should
 272         be a global setting rather than a property of this object.
 273
 274         This method works very well in conjunction with a RecentlyOpenedFilesList
 275         object to manage your recent-files list.
 276
 277         @see RecentlyOpenedFilesList
 278     */
 279     virtual void setLastDocumentOpened (const File& file) = 0;
 280
 281
 282 private:
 283     //==============================================================================
 284     File documentFile;
 285     bool changedSinceSave;
 286     String fileExtension, fileWildcard, openFileDialogTitle, saveFileDialogTitle;
 287
 288     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (FileBasedDocument);
 289 };
 290
 291
 292 #endif   // __JUCE_FILEBASEDDOCUMENT_JUCEHEADER__