X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..d58526d55433162cef8ad2ed7f422689862c3019:/interface/wx/docview.h diff --git a/interface/wx/docview.h b/interface/wx/docview.h index a0788b0a26..f27dc3ef4e 100644 --- a/interface/wx/docview.h +++ b/interface/wx/docview.h @@ -64,15 +64,14 @@ public: wxDocTemplate(wxDocManager* manager, const wxString& descr, const wxString& filter, const wxString& dir, const wxString& ext, const wxString& docTypeName, - const wxString& viewTypeName, - wxClassInfo* docClassInfo = NULL, - wxClassInfo* viewClassInfo = NULL, - long flags = wxDEFAULT_TEMPLATE_FLAGS); + const wxString& viewTypeName, wxClassInfo* docClassInfo = 0, + wxClassInfo* viewClassInfo = 0, + long flags = wxTEMPLATE_VISIBLE); /** Destructor. */ - ~wxDocTemplate(); + virtual ~wxDocTemplate(); /** Creates a new instance of the associated document class. If you have @@ -83,73 +82,118 @@ public: This function calls InitDocument() which in turns calls wxDocument::OnCreate(). */ - wxDocument* CreateDocument(const wxString& path, long flags = 0); + virtual wxDocument* CreateDocument(const wxString& path, long flags = 0); /** - Creates a new instance of the associated view class. If you have not - supplied a wxClassInfo parameter to the template constructor, you will - need to override this function to return an appropriate view instance. + Creates a new instance of the associated view class. + + If you have not supplied a wxClassInfo parameter to the template + constructor, you will need to override this function to return an + appropriate view instance. + + If the new view initialization fails, it must call + wxDocument::RemoveView() for consistency with the default behaviour of + this function. */ - wxView* CreateView(wxDocument* doc, long flags = 0); + virtual wxView* CreateView(wxDocument* doc, long flags = 0); + + /** + This function implements the default (very primitive) format detection + which checks if the extension is that of the template. + + @param path + The path to be checked against the template. + */ + virtual bool FileMatchesTemplate(const wxString& path); /** Returns the default file extension for the document data, as passed to the document template constructor. */ - wxString GetDefaultExtension(); + wxString GetDefaultExtension() const; /** Returns the text description of this template, as passed to the document template constructor. */ - wxString GetDescription(); + wxString GetDescription() const; /** Returns the default directory, as passed to the document template constructor. */ - wxString GetDirectory(); + wxString GetDirectory() const; + + /** + Returns the run-time class information that allows document + instances to be constructed dynamically, as passed to the document + template constructor. + */ + wxClassInfo* GetDocClassInfo() const; /** Returns a pointer to the document manager instance for which this template was created. */ - wxDocManager* GetDocumentManager(); + wxDocManager* GetDocumentManager() const; /** Returns the document type name, as passed to the document template constructor. */ - wxString GetDocumentName(); + virtual wxString GetDocumentName() const; /** Returns the file filter, as passed to the document template constructor. */ - wxString GetFileFilter(); + wxString GetFileFilter() const; /** Returns the flags, as passed to the document template constructor. */ - long GetFlags(); + long GetFlags() const; + + /** + Returns the run-time class information that allows view instances + to be constructed dynamically, as passed to the document template + constructor. + */ + wxClassInfo* GetViewClassInfo() const; /** Returns the view type name, as passed to the document template constructor. */ - wxString GetViewName(); + virtual wxString GetViewName() const; /** - Initialises the document, calling wxDocument::OnCreate(). This is - called from CreateDocument(). + Initialises the document, calling wxDocument::OnCreate(). + + This is called from CreateDocument(). + + If you override this method, notice that you must @em delete the @a doc + if its initialization fails for consistency with the default behaviour. + + @param doc + The document to initialize. + @param path + The associated file path. + @param flags + Flags passed to CreateDocument(). + @return + @true if the initialization was successful or @false if it failed + in which case @a doc should be deleted by this function. */ - bool InitDocument(wxDocument* doc, const wxString& path, long flags = 0); + virtual bool InitDocument(wxDocument* doc, + const wxString& path, + long flags = 0); /** Returns @true if the document template can be shown in user dialogs, @false otherwise. */ - bool IsVisible(); + bool IsVisible() const; /** Sets the default file extension. @@ -258,26 +302,28 @@ public: Constructor. Create a document manager instance dynamically near the start of your application before doing any document or view operations. - @a flags is currently unused. - If @a initialize is @true, the Initialize() function will be called to create a default history list object. If you derive from wxDocManager, you may wish to call the base constructor with @false, and then call Initialize() in your own constructor, to allow your own Initialize() or OnCreateFileHistory functions to be called. + + @param flags + Currently unused. + @param initialize + Indicates whether Initialize() should be called by this ctor. */ - wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS, - bool initialize = true); + wxDocManager(long flags = 0, bool initialize = true); /** Destructor. */ - ~wxDocManager(); + virtual ~wxDocManager(); /** Sets the current view. */ - void ActivateView(wxView* doc, bool activate = true); + virtual void ActivateView(wxView* doc, bool activate = true); /** Adds the document to the list of documents. @@ -288,7 +334,7 @@ public: Adds a file to the file history list, if we have a pointer to an appropriate file menu. */ - void AddFileToHistory(const wxString& filename); + virtual void AddFileToHistory(const wxString& filename); /** Adds the template to the document manager's template list. @@ -301,32 +347,57 @@ public: bool CloseDocuments(bool force = true); /** - Creates a new document in a manner determined by the @a flags - parameter, which can be: - - - wxDOC_NEW - Creates a fresh document. - - wxDOC_SILENT - Silently loads the given document file. + Creates a new document. + + This function can either create a document corresponding to a new + file or to an already existing one depending on whether @c wxDOC_NEW is + specified in the @a flags. + + By default, this function asks the user for the type of document to + open and the path to its file if it's not specified, i.e. if @a path is + empty. Specifying @c wxDOC_SILENT flag suppresses any prompts and means + that the @a path must be non-empty and there must be a registered + document template handling the extension of this file, otherwise a + warning message is logged and the function returns @NULL. Notice that + @c wxDOC_SILENT can be combined with @c wxDOC_NEW, however in this case + the @a path must still be specified, even if the file with this path + typically won't exist. + + Finally notice that if this document manager was configured to allow + only a limited number of simultaneously opened documents using + SetMaxDocsOpen(), this function will try to close the oldest existing + document if this number was reached before creating a new document. + And if closing the old document fails (e.g. because it was vetoed by + user), this function fails as well. + + @param path + Path to a file or an empty string. If the path is empty, the user + will be asked to select it (thus, this is incompatible with the use + of @c wxDOC_SILENT). The file should exist unless @a flags includes + @c wxDOC_NEW. + @param flags + By default, none. May include @c wxDOC_NEW to indicate that the new + document corresponds to a new file and not an existing one and + @c wxDOC_SILENT to suppress any dialogs asking the user about the + file path and type. + @return a new document object or @NULL on failure. + */ + virtual wxDocument* CreateDocument(const wxString& path, long flags = 0); - If wxDOC_NEW is present, a new document will be created and returned, - possibly after asking the user for a template to use if there is more - than one document template. If wxDOC_SILENT is present, a new document - will be created and the given file loaded into it. If neither of these - flags is present, the user will be presented with a file selector for - the file to load, and the template to use will be determined by the - extension (Windows) or by popping up a template choice list (other - platforms). + /** + Creates an empty new document. - If the maximum number of documents has been reached, this function will - delete the oldest currently loaded document before creating a new one. - */ - wxDocument* CreateDocument(const wxString& path, long flags); + This is equivalent to calling CreateDocument() with @c wxDOC_NEW flags + and without the file name. + */ + wxDocument *CreateNewDocument(); /** Creates a new view for the given document. If more than one view is allowed for the document (by virtue of multiple templates mentioning the same document type), a choice of view is presented to the user. */ - wxView* CreateView(wxDocument* doc, long flags); + virtual wxView* CreateView(wxDocument* doc, long flags = 0); /** Removes the template from the list of templates. @@ -337,24 +408,24 @@ public: Appends the files in the history list to all menus managed by the file history object. */ - void FileHistoryAddFilesToMenu(); + virtual void FileHistoryAddFilesToMenu(); /** Appends the files in the history list to the given @a menu only. */ - void FileHistoryAddFilesToMenu(wxMenu* menu); + virtual void FileHistoryAddFilesToMenu(wxMenu* menu); /** Loads the file history from a config object. @see wxConfigBase */ - void FileHistoryLoad(const wxConfigBase& config); + virtual void FileHistoryLoad(const wxConfigBase& config); /** Removes the given menu from the list of menus managed by the file history object. */ - void FileHistoryRemoveMenu(wxMenu* menu); + virtual void FileHistoryRemoveMenu(wxMenu* menu); /** Saves the file history into a config object. This must be called @@ -362,7 +433,7 @@ public: @see wxConfigBase */ - void FileHistorySave(wxConfigBase& resourceFile); + virtual void FileHistorySave(wxConfigBase& resourceFile); /** Use this menu for appending recently-visited document filenames, for @@ -372,40 +443,40 @@ public: @note You can add multiple menus using this function, to be managed by the file history object. */ - void FileHistoryUseMenu(wxMenu* menu); + virtual void FileHistoryUseMenu(wxMenu* menu); /** Given a path, try to find template that matches the extension. This is only an approximate method of finding a template for creating a document. */ - wxDocTemplate* FindTemplateForPath(const wxString& path); + virtual wxDocTemplate* FindTemplateForPath(const wxString& path); /** Returns the document associated with the currently active view (if any). */ - wxDocument* GetCurrentDocument(); + wxDocument* GetCurrentDocument() const; /** Returns the currently active view */ - wxView* GetCurrentView(); + virtual wxView* GetCurrentView() const; /** Returns a reference to the list of documents. */ - wxList GetDocuments(); + wxList& GetDocuments(); /** Returns a pointer to file history. */ - wxFileHistory* GetFileHistory(); + virtual wxFileHistory* GetFileHistory() const; /** Returns the number of files currently stored in the file history. */ - size_t GetHistoryFilesCount(); + virtual size_t GetHistoryFilesCount() const; /** Returns the directory last selected by the user when opening a file. @@ -416,12 +487,12 @@ public: /** Returns the number of documents that can be open simultaneously. */ - int GetMaxDocsOpen(); + int GetMaxDocsOpen() const; /** Returns a reference to the list of associated templates. */ - wxList GetTemplates(); + wxList& GetTemplates(); /** Initializes data; currently just calls OnCreateFileHistory(). @@ -439,7 +510,7 @@ public: The bottom line: if you're not deriving from Initialize(), forget it and construct wxDocManager with no arguments. */ - bool Initialize(); + virtual bool Initialize(); /** Return a string containing a suitable default name for a new document. @@ -447,13 +518,13 @@ public: string @b unnamed but can be overridden in the derived classes to do something more appropriate. */ - wxString MakeNewDocumentName(); + virtual wxString MakeNewDocumentName(); /** A hook to allow a derived class to create a different type of file history. Called from Initialize(). */ - wxFileHistory* OnCreateFileHistory(); + virtual wxFileHistory* OnCreateFileHistory(); /** Closes and deletes the currently active document. @@ -508,9 +579,9 @@ public: This function is used in CreateDocument(). */ - wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates, - int noTemplates, wxString& path, - long flags, bool save); + virtual wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates, + int noTemplates, wxString& path, + long flags, bool save = false); /** Returns a document template by asking the user (if there is more than @@ -527,8 +598,9 @@ public: will have to choose from is sorted or not when shown the choice box dialog. Default is @false. */ - wxDocTemplate* SelectDocumentType(wxDocTemplate** templates, - int noTemplates, bool sort = false); + virtual wxDocTemplate* SelectDocumentType(wxDocTemplate** templates, + int noTemplates, + bool sort = false); /** Returns a document template by asking the user (if there is more than @@ -548,8 +620,8 @@ public: will have to choose from is sorted or not when shown the choice box dialog. Default is @false. */ - wxDocTemplate* SelectViewType(wxDocTemplate** templates, - int noTemplates, bool sort = false); + virtual wxDocTemplate* SelectViewType(wxDocTemplate** templates, + int noTemplates, bool sort = false); /** Sets the directory to be displayed to the user when opening a file. @@ -559,11 +631,12 @@ public: /** Sets the maximum number of documents that can be open at a time. By - default, this is 10,000. If you set it to 1, existing documents will be - saved and deleted when the user tries to open or create a new one - (similar to the behaviour of Windows Write, for example). Allowing - multiple documents gives behaviour more akin to MS Word and other - Multiple Document Interface applications. + default, this is @c INT_MAX, i.e. the number of documents is unlimited. + If you set it to 1, existing documents will be saved and deleted when + the user tries to open or create a new one (similar to the behaviour of + Windows Write, for example). Allowing multiple documents gives + behaviour more akin to MS Word and other Multiple Document Interface + applications. */ void SetMaxDocsOpen(int n); @@ -632,7 +705,7 @@ public: /** Destructor. Removes itself from the document's list of views. */ - ~wxView(); + virtual ~wxView(); /** Call this from your view frame's wxDocChildFrame::OnActivate() member @@ -671,7 +744,7 @@ public: uses notebook pages instead of frames and this is why this method returns a wxWindow and not a wxFrame. */ - wxWindow* GetFrame(); + wxWindow* GetFrame() const; /** Gets the name associated with the view (passed to the wxDocTemplate @@ -688,8 +761,7 @@ public: /** Called when the filename has changed. The default implementation - constructs a suitable title and sets the title of the view frame (if - any). + constructs a suitable title and sets the title of the view frame (if any). */ virtual void OnChangeFilename(); @@ -737,7 +809,7 @@ public: /** Override this function to render the view on the given device context. */ - virtual void OnDraw(wxDC* dc); + virtual void OnDraw(wxDC* dc) = 0; /** Called when the view should be updated. @@ -751,13 +823,13 @@ public: application-specific information for making updating more efficient. */ - virtual void OnUpdate(wxView* sender, wxObject* hint); + virtual void OnUpdate(wxView* sender, wxObject* hint = 0); /** Associates the given document with the view. Normally called by the framework. */ - void SetDocument(wxDocument* doc); + virtual void SetDocument(wxDocument* doc); /** Sets the frame associated with this view. The application should call @@ -822,12 +894,12 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); + const wxString& name = wxFrameNameStr); /** Destructor. */ - ~wxDocChildFrame(); + virtual ~wxDocChildFrame(); /** Returns the document associated with this frame. @@ -844,7 +916,7 @@ public: override (but still call) this function in order to set the keyboard focus for your subwindow. */ - void OnActivate(wxActivateEvent event); + void OnActivate(wxActivateEvent& event); /** Closes and deletes the current view and document. @@ -904,22 +976,20 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); + const wxString& name = wxFrameNameStr); /** Destructor. */ - ~wxDocParentFrame(); + virtual ~wxDocParentFrame(); /** Used in two-step construction. */ - bool Create(wxDocManager* manager, wxFrame* parent, - wxWindowID id, const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); + bool Create(wxDocManager* manager, wxFrame* parent, wxWindowID id, + const wxString& title, const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 541072960, + const wxString& name = wxFrameNameStr); /** Returns the associated document manager object. @@ -968,12 +1038,12 @@ public: Constructor. Define your own default constructor to initialize application-specific data. */ - wxDocument(); + wxDocument(wxDocument* parent = 0); /** Destructor. Removes itself from the document manager. */ - ~wxDocument(); + virtual ~wxDocument(); /** If the view is not already in the list of views, adds the view and @@ -981,6 +1051,22 @@ public: */ virtual bool AddView(wxView* view); + /** + Returns true if the document hasn't been modified since the last time + it had been saved. + + Notice that this function returns @false if the document had been never + saved at all, so it may be also used to test whether it makes sense to + save the document: if it returns @true, there is nothing to save but if + @false is returned, it can be saved, even if it might be not modified + (this can be used to create an empty document file by the user). + + @see IsModified(), GetDocumentSaved() + + @since 2.9.0 + */ + bool AlreadySaved() const; + /** Closes the document, by calling OnSaveModified() and then (if this returned @true) OnCloseDocument(). This does not normally delete the @@ -1003,12 +1089,12 @@ public: @see wxCommandProcessor */ - wxCommandProcessor* GetCommandProcessor() const; + virtual wxCommandProcessor* GetCommandProcessor() const; /** Gets a pointer to the associated document manager. */ - wxDocManager* GetDocumentManager() const; + virtual wxDocManager* GetDocumentManager() const; /** Gets the document type name for this document. See the comment for @@ -1016,17 +1102,24 @@ public: */ wxString GetDocumentName() const; + /** + Return true if this document had been already saved. + + @see IsModified() + */ + bool GetDocumentSaved() const; + /** Gets a pointer to the template that created the document. */ - wxDocTemplate* GetDocumentTemplate() const; + virtual wxDocTemplate* GetDocumentTemplate() const; /** Intended to return a suitable window for using as a parent for document-related dialog boxes. By default, uses the frame associated with the first view. */ - wxWindow* GetDocumentWindow() const; + virtual wxWindow* GetDocumentWindow() const; /** Gets the filename associated with this document, or "" if none is @@ -1056,12 +1149,15 @@ public: */ virtual wxString GetUserReadableName() const; + //@{ /** Returns the list whose elements are the views on the document. @see GetFirstView() */ - wxList GetViews() const; + wxList& GetViews(); + const wxList& GetViews() const; + //@} /** Returns @true if the document has been modified since the last save, @@ -1102,17 +1198,37 @@ public: virtual void OnChangedViewList(); /** + This virtual function is called when the document is being closed. + The default implementation calls DeleteContents() (an empty - implementation) and sets the modified flag to @false. Override this to - supply additional behaviour when the document is closed with Close(). + implementation) and sets the modified flag to @false. You can override + it to supply additional behaviour when the document is closed with + Close(). + + Notice that previous wxWidgets versions used to call this function also + from OnNewDocument(), rather counter-intuitively. This is no longer the + case since wxWidgets 2.9.0. */ virtual bool OnCloseDocument(); /** Called just after the document object is created to give it a chance to - initialize itself. The default implementation uses the template - associated with the document to create an initial view. If this - function returns @false, the document is deleted. + initialize itself. + + The default implementation uses the template associated with the + document to create an initial view. + + For compatibility reasons, this method may either delete the document + itself if its initialization fails or not do it in which case it is + deleted by caller. It is recommended to delete the document explicitly + in this function if it can't be initialized. + + @param path + The associated file path. + @param flags + Flags passed to CreateDocument(). + @return + @true if the initialization was successful or @false if it failed. */ virtual bool OnCreate(const wxString& path, long flags); @@ -1208,15 +1324,23 @@ public: Sets the pointer to the template that created the document. Should only be called by the framework. */ - void SetDocumentTemplate(wxDocTemplate* templ); + virtual void SetDocumentTemplate(wxDocTemplate* templ); /** Sets the filename for this document. Usually called by the framework. + Calls OnChangeFilename() which in turn calls wxView::OnChangeFilename() for + all views if @a notifyViews is @true, + */ + void SetFilename(const wxString& filename, bool notifyViews = false); + + /** If @a notifyViews is @true, wxView::OnChangeFilename() is called for all views. + + @since 2.9.0 */ - void SetFilename(const wxString& filename, bool notifyViews = false); + virtual void OnChangeFilename(bool notifyViews); /** Sets the title for this document. The document title is used for an @@ -1230,7 +1354,7 @@ public: view. @a hint represents optional information to allow a view to optimize its update. */ - void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL); + virtual void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL); protected: /** @@ -1329,23 +1453,23 @@ public: /** Destructor. */ - ~wxFileHistory(); + virtual ~wxFileHistory(); /** Adds a file to the file history list, if the object has a pointer to an appropriate file menu. */ - void AddFileToHistory(const wxString& filename); + virtual void AddFileToHistory(const wxString& filename); /** Appends the files in the history list, to all menus managed by the file history object. */ - void AddFilesToMenu(); + virtual void AddFilesToMenu(); /** Appends the files in the history list, to the given menu only. */ - void AddFilesToMenu(wxMenu* menu); + virtual void AddFilesToMenu(wxMenu* menu); /** Returns the base identifier for the range used for appending items. @@ -1355,17 +1479,17 @@ public: /** Returns the number of files currently stored in the file history. */ - size_t GetCount() const; + virtual size_t GetCount() const; /** Returns the file at this index (zero-based). */ - wxString GetHistoryFile(size_t index) const; + virtual wxString GetHistoryFile(size_t index) const; /** Returns the maximum number of files that can be stored. */ - int GetMaxFiles() const; + virtual int GetMaxFiles() const; /** Returns the list of menus that are managed by this file history object. @@ -1380,17 +1504,17 @@ public: @see wxConfigBase */ - void Load(const wxConfigBase& config); + virtual void Load(const wxConfigBase& config); /** Removes the specified file from the history. */ - void RemoveFileFromHistory(size_t i); + virtual void RemoveFileFromHistory(size_t i); /** Removes this menu from the list of those managed by this object. */ - void RemoveMenu(wxMenu* menu); + virtual void RemoveMenu(wxMenu* menu); /** Saves the file history into the given config object. This must be @@ -1398,7 +1522,7 @@ public: @see wxConfigBase */ - void Save(wxConfigBase& config); + virtual void Save(wxConfigBase& config); /** Sets the base identifier for the range used for appending items. @@ -1411,28 +1535,7 @@ public: with filenames that are already in the history when this function is called, as this is not done automatically. */ - void UseMenu(wxMenu* menu); - - /** - A character array of strings corresponding to the most recently opened - files. - */ - char** m_fileHistory; - - /** - The number of files stored in the history array. - */ - size_t m_fileHistoryN; - - /** - The maximum number of files to be stored and displayed on the menu. - */ - size_t m_fileMaxFiles; - - /** - The file menu used to display the file history list (if enabled). - */ - wxMenu* m_fileMenu; + virtual void UseMenu(wxMenu* menu); }; @@ -1441,7 +1544,7 @@ public: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_file */ +/** @addtogroup group_funcmacro_file */ //@{ /**