X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..d5e3081bba2bf1ea8700a20bdee345d2fec8f6a7:/interface/wx/docview.h diff --git a/interface/wx/docview.h b/interface/wx/docview.h index a0788b0a26..dcb80c1f28 100644 --- a/interface/wx/docview.h +++ b/interface/wx/docview.h @@ -258,16 +258,18 @@ 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. @@ -301,25 +303,42 @@ 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. - - 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). - - If the maximum number of documents has been reached, this function will - delete the oldest currently loaded document before creating a new one. + 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. */ - wxDocument* CreateDocument(const wxString& path, long flags); + wxDocument *CreateDocument(const wxString& path, long flags = 0); /** Creates a new view for the given document. If more than one view is @@ -559,11 +578,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); @@ -1102,9 +1122,16 @@ 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();