Split documentation of non-GUI wxEvent-related classes.

[wxWidgets.git] / interface / wx / docview.h

diff --git a/interface/wx/docview.h b/interface/wx/docview.h
index 3a8bc4fddd0d3bacfc5c636fb216f642f7d9df54..848c987dea0f954a4969657316c2aa1115d41e28 100644 (file)
--- a/interface/wx/docview.h
+++ b/interface/wx/docview.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of various doc/view framework classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of various doc/view framework classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -43,13 +43,13 @@ public:
             A name that should be unique for a given view.
         @param docClassInfo
             A pointer to the run-time document class information as returned by
             A name that should be unique for a given view.
         @param docClassInfo
             A pointer to the run-time document class information as returned by

-            the CLASSINFO() macro, e.g. CLASSINFO(MyDocumentClass). If this is
+            the wxCLASSINFO() macro, e.g. wxCLASSINFO(MyDocumentClass). If this is

             not supplied, you will need to derive a new wxDocTemplate class and
             override the CreateDocument() member to return a new document
             instance on demand.
         @param viewClassInfo
             A pointer to the run-time view class information as returned by the
             not supplied, you will need to derive a new wxDocTemplate class and
             override the CreateDocument() member to return a new document
             instance on demand.
         @param viewClassInfo
             A pointer to the run-time view class information as returned by the

-            CLASSINFO() macro, e.g. CLASSINFO(MyViewClass). If this is not
+            wxCLASSINFO() macro, e.g. wxCLASSINFO(MyViewClass). If this is not

             supplied, you will need to derive a new wxDocTemplate class and
             override the CreateView() member to return a new view instance on
             demand.
             supplied, you will need to derive a new wxDocTemplate class and
             override the CreateView() member to return a new view instance on
             demand.


@@ -60,19 +60,40 @@ public:
             - wxTEMPLATE_INVISIBLE     - The template may not be displayed to
                                          the user in dialogs.
             - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE.
             - wxTEMPLATE_INVISIBLE     - The template may not be displayed to
                                          the user in dialogs.
             - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE.

+
+        @beginWxPerlOnly
+
+        In wxPerl @a docClassInfo and @a viewClassInfo can be either
+        @c Wx::ClassInfo objects or strings containing the name of the
+        perl packages which are to be used as @c Wx::Document and
+        @c Wx::View classes (they must have a constructor named new);
+        as an example:
+
+        - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
+          docTypeName, viewTypeName, docClassInfo, viewClassInfo,
+          flags): will construct document and view objects from the
+          class information.
+        - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
+          docTypeName, viewTypeName, docClassName, viewClassName,
+          flags): will construct document and view objects from perl
+          packages.
+        - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
+          docTypeName, viewTypeName):
+          in this case @c Wx::DocTemplate::CreateDocument() and
+          @c Wx::DocTemplate::CreateView() must be overridden
+        @endWxPerlOnly

     */
     wxDocTemplate(wxDocManager* manager, const wxString& descr,
                   const wxString& filter, const wxString& dir,
                   const wxString& ext, const wxString& docTypeName,
     */
     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.
     */
 
     /**
         Destructor.
     */

-    ~wxDocTemplate();
+    virtual ~wxDocTemplate();

 
     /**
         Creates a new instance of the associated document class. If you have
 
     /**
         Creates a new instance of the associated document class. If you have


@@ -83,73 +104,127 @@ public:
         This function calls InitDocument() which in turns calls
         wxDocument::OnCreate().
     */
         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.
+    */
+    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.

     */
     */

-    wxView* CreateView(wxDocument* doc, long flags = 0);
+    virtual bool FileMatchesTemplate(const wxString& path);

 
     /**
         Returns the default file extension for the document data, as passed to
         the document template constructor.
     */
 
     /**
         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.
     */
 
     /**
         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.
     */
 
     /**
         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.
     */
 
     /**
         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.
     */
 
     /**
         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.
     */
 
     /**
         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.
     */
 
     /**
         Returns the flags, as passed to the document template constructor.
     */

-    long GetFlags();
+    long GetFlags() const;
+
+    /**
+        Returns a reference to the wxPageSetupDialogData associated with the
+        printing operations of this document manager.
+    */
+    //@{
+    wxPageSetupDialogData& GetPageSetupDialogData();
+    const wxPageSetupDialogData& GetPageSetupDialogData() 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.
     */
 
     /**
         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.
     */
 
     /**
         Returns @true if the document template can be shown in user dialogs,
         @false otherwise.
     */

-    bool IsVisible();
+    bool IsVisible() const;

 
     /**
         Sets the default file extension.
 
     /**
         Sets the default file extension.


@@ -274,12 +349,12 @@ public:
     /**
         Destructor.
     */
     /**
         Destructor.
     */

-    ~wxDocManager();
+    virtual ~wxDocManager();

 
     /**
         Sets the current view.
     */
 
     /**
         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.
 
     /**
         Adds the document to the list of documents.


@@ -290,15 +365,55 @@ public:
         Adds a file to the file history list, if we have a pointer to an
         appropriate file menu.
     */
         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.
     */
     void AssociateTemplate(wxDocTemplate* temp);
 
 
     /**
         Adds the template to the document manager's template list.
     */
     void AssociateTemplate(wxDocTemplate* temp);
 

+    /**
+        Search for a particular document template.
+
+        Example:
+        @code
+           // creating a document instance of the specified document type:
+           m_doc = (MyDoc*)docManager->FindTemplate(CLASSINFO(MyDoc))->
+                        CreateDocument(wxEmptyString, wxDOC_SILENT);
+        @endcode
+
+        @param classinfo
+            Class info of a document class for which a wxDocTemplate had been
+            previously created.
+
+        @return
+            Pointer to a wxDocTemplate, or @NULL if none found.
+
+        @since 2.9.2
+     */
+    wxDocTemplate* FindTemplate(const wxClassInfo* classinfo);
+
+    /**
+        Closes the specified document.
+
+        If @a force is @true, the document is closed even if it has unsaved
+        changes.
+
+        @param doc
+            The document to close, must be non-@NULL.
+        @param force
+            If @true, close the document even if wxDocument::Close() returns
+            @false.
+        @return
+            @true if the document was closed or @false if closing it was
+            cancelled by user (only in @a force = @false case).
+     */
+    bool CloseDocument(wxDocument *doc, bool force = false);
+

     /**
         Closes all currently opened documents.
     /**
         Closes all currently opened documents.

+
+        @see CloseDocument()

     */
     bool CloseDocuments(bool force = true);
 
     */
     bool CloseDocuments(bool force = true);
 


@@ -338,14 +453,22 @@ public:
             file path and type.
         @return a new document object or @NULL on failure.
     */
             file path and type.
         @return a new document object or @NULL on failure.
     */

-    wxDocument *CreateDocument(const wxString& path, long flags = 0);
+    virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
+
+    /**
+        Creates an empty new document.
+
+        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.
     */
 
     /**
         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.
 
     /**
         Removes the template from the list of templates.


@@ -356,24 +479,24 @@ public:
         Appends the files in the history list to all menus managed by the file
         history object.
     */
         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.
     */
     /**
         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
     */
 
     /**
         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.
     */
 
     /**
         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
 
     /**
         Saves the file history into a config object. This must be called


@@ -381,7 +504,7 @@ public:
 
         @see wxConfigBase
     */
 
         @see wxConfigBase
     */

-    void FileHistorySave(wxConfigBase& resourceFile);
+    virtual void FileHistorySave(wxConfigBase& resourceFile);

 
     /**
         Use this menu for appending recently-visited document filenames, for
 
     /**
         Use this menu for appending recently-visited document filenames, for


@@ -391,40 +514,40 @@ public:
         @note You can add multiple menus using this function, to be managed by
               the file history object.
     */
         @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.
     */
 
     /**
         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).
     */
 
     /**
         Returns the document associated with the currently active view (if
         any).
     */

-    wxDocument* GetCurrentDocument();
+    wxDocument* GetCurrentDocument() const;

 
     /**
         Returns the currently active view
     */
 
     /**
         Returns the currently active view
     */

-    wxView* GetCurrentView();
+    virtual wxView* GetCurrentView() const;

 
     /**
         Returns a reference to the list of documents.
     */
 
     /**
         Returns a reference to the list of documents.
     */

-    wxList GetDocuments();
+    wxList& GetDocuments();

 
     /**
         Returns a pointer to file history.
     */
 
     /**
         Returns a pointer to file history.
     */

-    wxFileHistory* GetFileHistory();
+    virtual wxFileHistory* GetFileHistory() const;

 
     /**
         Returns the number of files currently stored in the file history.
     */
 
     /**
         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.
 
     /**
         Returns the directory last selected by the user when opening a file.


@@ -435,12 +558,12 @@ public:
     /**
         Returns the number of documents that can be open simultaneously.
     */
     /**
         Returns the number of documents that can be open simultaneously.
     */

-    int GetMaxDocsOpen();
+    int GetMaxDocsOpen() const;

 
     /**
         Returns a reference to the list of associated templates.
     */
 
     /**
         Returns a reference to the list of associated templates.
     */

-    wxList GetTemplates();
+    wxList& GetTemplates();

 
     /**
         Initializes data; currently just calls OnCreateFileHistory().
 
     /**
         Initializes data; currently just calls OnCreateFileHistory().


@@ -458,7 +581,7 @@ public:
         The bottom line: if you're not deriving from Initialize(), forget it
         and construct wxDocManager with no arguments.
     */
         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.
 
     /**
         Return a string containing a suitable default name for a new document.


@@ -466,13 +589,13 @@ public:
         string @b unnamed but can be overridden in the derived classes to do
         something more appropriate.
     */
         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().
     */
 
     /**
         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.
 
     /**
         Closes and deletes the currently active document.


@@ -526,10 +649,20 @@ public:
         choice list is popped up, followed by a file selector.
 
         This function is used in CreateDocument().
         choice list is popped up, followed by a file selector.
 
         This function is used in CreateDocument().

+
+        @beginWxPerlOnly
+        In wxPerl @a templates is a reference to a list of templates.
+        If you override this method in your document manager it must
+        return two values, eg:
+
+        @code
+        (doctemplate, path) = My::DocManager->SelectDocumentPath(...);
+        @endcode
+        @endWxPerlOnly

     */
     */

-    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
 
     /**
         Returns a document template by asking the user (if there is more than


@@ -541,13 +674,18 @@ public:
         @param noTemplates
             Number of templates being pointed to by the templates pointer.
         @param sort
         @param noTemplates
             Number of templates being pointed to by the templates pointer.
         @param sort

-            If more than one template is passed in in templates, then this
+            If more than one template is passed into templates, then this

             parameter indicates whether the list of templates that the user
             will have to choose from is sorted or not when shown the choice box
             dialog. Default is @false.
             parameter indicates whether the list of templates that the user
             will have to choose from is sorted or not when shown the choice box
             dialog. Default is @false.

+
+        @beginWxPerlOnly
+        In wxPerl @a templates is a reference to a list of templates.
+        @endWxPerlOnly

     */
     */

-    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
 
     /**
         Returns a document template by asking the user (if there is more than


@@ -562,13 +700,17 @@ public:
         @param noTemplates
             Number of templates being pointed to by the templates pointer.
         @param sort
         @param noTemplates
             Number of templates being pointed to by the templates pointer.
         @param sort

-            If more than one template is passed in in templates, then this
+            If more than one template is passed into templates, then this

             parameter indicates whether the list of templates that the user
             will have to choose from is sorted or not when shown the choice box
             dialog. Default is @false.
             parameter indicates whether the list of templates that the user
             will have to choose from is sorted or not when shown the choice box
             dialog. Default is @false.

+
+        @beginWxPerlOnly
+        In wxPerl @a templates is a reference to a list of templates.
+        @endWxPerlOnly

     */
     */

-    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.
 
     /**
         Sets the directory to be displayed to the user when opening a file.


@@ -587,6 +729,55 @@ public:
     */
     void SetMaxDocsOpen(int n);
 
     */
     void SetMaxDocsOpen(int n);
 

+
+protected:
+    /**
+        Called when a file selected from the MRU list doesn't exist any more.
+
+        The default behaviour is to remove the file from the MRU (most recently
+        used) files list and the corresponding menu and notify the user about
+        it but this method can be overridden to customize it.
+
+        For example, an application may want to just give an error about the
+        missing file @a filename but not remove it from the file history. Or it
+        could ask the user whether the file should be kept or removed.
+
+        Notice that this method is called only if the file selected by user
+        from the MRU files in the menu doesn't exist, but not if opening it
+        failed for any other reason because in the latter case the default
+        behaviour of removing the file from the MRU list is inappropriate.
+        If you still want to do it, you would need to do it by calling
+        RemoveFileFromHistory() explicitly in the part of the file opening code
+        that may fail.
+
+        @since 2.9.3
+
+        @param n
+            The index of the file in the MRU list, it can be passed to
+            RemoveFileFromHistory() to remove this file from the list.
+        @param filename
+            The full name of the file.
+     */
+    virtual void OnMRUFileNotExist(unsigned n, const wxString& filename);
+
+    /**
+        Create the frame used for print preview.
+
+        This method can be overridden if you need to change the behaviour or
+        appearance of the preview window. By default, a standard wxPreviewFrame
+        is created.
+
+        @since 2.9.1
+
+        @param preview The associated preview object.
+        @param parent The parent window for the frame.
+        @param title The suggested title for the print preview frame.
+        @return A new print preview frame, must not return @NULL.
+    */
+    virtual wxPreviewFrame* CreatePreviewFrame(wxPrintPreviewBase* preview,
+                                               wxWindow* parent,
+                                               const wxString& title);
+

     /**
         The currently active view.
     */
     /**
         The currently active view.
     */


@@ -608,19 +799,16 @@ public:
     */
     wxFileHistory* m_fileHistory;
 
     */
     wxFileHistory* m_fileHistory;
 

-    /**
-        Stores the flags passed to the constructor.
-    */
-    long m_flags;
-

     /**
         The directory last selected by the user when opening a file.
     */
     /**
         The directory last selected by the user when opening a file.
     */

-    wxFileHistory* m_fileHistory;
+    wxString m_lastDirectory;

 
     /**
         Stores the maximum number of documents that can be opened before
 
     /**
         Stores the maximum number of documents that can be opened before

-        existing documents are closed. By default, this is 10,000.
+        existing documents are closed.
+
+        By default, this is @c INT_MAX i.e. practically unlimited.

     */
     int m_maxDocsOpen;
 };
     */
     int m_maxDocsOpen;
 };


@@ -652,7 +840,7 @@ public:
     /**
         Destructor. Removes itself from the document's list of views.
     */
     /**
         Destructor. Removes itself from the document's list of views.
     */

-    ~wxView();
+    virtual ~wxView();

 
     /**
         Call this from your view frame's wxDocChildFrame::OnActivate() member
 
     /**
         Call this from your view frame's wxDocChildFrame::OnActivate() member


@@ -691,7 +879,7 @@ public:
         uses notebook pages instead of frames and this is why this method
         returns a wxWindow and not a wxFrame.
     */
         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
 
     /**
         Gets the name associated with the view (passed to the wxDocTemplate


@@ -708,8 +896,7 @@ public:
 
     /**
         Called when the filename has changed. The default implementation
 
     /**
         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();
 
     */
     virtual void OnChangeFilename();
 


@@ -757,7 +944,7 @@ public:
     /**
         Override this function to render the view on the given device context.
     */
     /**
         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.
 
     /**
         Called when the view should be updated.


@@ -771,13 +958,13 @@ public:
             application-specific information for making updating more
             efficient.
     */
             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.
     */
 
     /**
         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
 
     /**
         Sets the frame associated with this view. The application should call


@@ -826,6 +1013,13 @@ public:
     and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
     classes.
 
     and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
     classes.
 

+    Notice that this class handles ::wxEVT_ACTIVATE event and activates the
+    child view on receiving it. Don't intercept this event unless you want to
+    prevent from this happening.
+
+    The same remark applies to ::wxEVT_CLOSE_WINDOW, as wxDocParentFrame the
+    frame handles this event by trying to close the associated view.
+

     @library{wxcore}
     @category{docview}
 
     @library{wxcore}
     @category{docview}
 


@@ -842,12 +1036,12 @@ public:
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxDEFAULT_FRAME_STYLE,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxDEFAULT_FRAME_STYLE,

-                    const wxString& name = "frame");
+                    const wxString& name = wxFrameNameStr);

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

-    ~wxDocChildFrame();
+    virtual ~wxDocChildFrame();

 
     /**
         Returns the document associated with this frame.
 
     /**
         Returns the document associated with this frame.


@@ -859,18 +1053,6 @@ public:
     */
     wxView* GetView() const;
 
     */
     wxView* GetView() const;
 

-    /**
-        Sets the currently active view to be the frame's view. You may need to
-        override (but still call) this function in order to set the keyboard
-        focus for your subwindow.
-    */
-    void OnActivate(wxActivateEvent event);
-
-    /**
-        Closes and deletes the current view and document.
-    */
-    void OnCloseWindow(wxCloseEvent& event);
-

     /**
         Sets the document for this frame.
     */
     /**
         Sets the document for this frame.
     */


@@ -904,6 +1086,12 @@ public:
     It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
     classes.
 
     It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
     classes.
 

+    Notice that this class processes ::wxEVT_CLOSE_WINDOW event and tries to
+    close all open views from its handler. If all the views can be closed, i.e.
+    if none of them contains unsaved changes or the user decides to not save
+    them, the window is destroyed. Don't intercept this event in your code
+    unless you want to replace this logic.
+

     @library{wxcore}
     @category{docview}
 
     @library{wxcore}
     @category{docview}
 


@@ -924,47 +1112,25 @@ public:
                      const wxPoint& pos = wxDefaultPosition,
                      const wxSize& size = wxDefaultSize,
                      long style = wxDEFAULT_FRAME_STYLE,
                      const wxPoint& pos = wxDefaultPosition,
                      const wxSize& size = wxDefaultSize,
                      long style = wxDEFAULT_FRAME_STYLE,

-                     const wxString& name = "frame");
+                     const wxString& name = wxFrameNameStr);

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

-    ~wxDocParentFrame();
+    virtual ~wxDocParentFrame();

 
     /**
         Used in two-step construction.
     */
 
     /**
         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.
     */
     wxDocManager* GetDocumentManager() const;
 
     /**
         Returns the associated document manager object.
     */
     wxDocManager* GetDocumentManager() const;

-
-    /**
-        Deletes all views and documents. If no user input cancelled the
-        operation, the frame will be destroyed and the application will exit.
-        Since understanding how document/view clean-up takes place can be
-        difficult, the implementation of this function is shown below:
-
-        @code
-        void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event)
-        {
-            if (m_docManager->Clear(!event.CanVeto()))
-            {
-                this->Destroy();
-            }
-            else
-                event.Veto();
-        }
-        @endcode
-    */
-    void OnCloseWindow(wxCloseEvent& event);

 };
 
 
 };
 
 


@@ -973,9 +1139,25 @@ public:
     @class wxDocument
 
     The document class can be used to model an application's file-based data.
     @class wxDocument
 
     The document class can be used to model an application's file-based data.

+

     It is part of the document/view framework supported by wxWidgets, and
     cooperates with the wxView, wxDocTemplate and wxDocManager classes.
 
     It is part of the document/view framework supported by wxWidgets, and
     cooperates with the wxView, wxDocTemplate and wxDocManager classes.
 

+    A normal document is the one created without parent document and is
+    associated with a disk file. Since version 2.9.2 wxWidgets also supports a
+    special kind of documents called <em>child documents</em> which are virtual
+    in the sense that they do not correspond to a file but rather to a part of
+    their parent document. Because of this, the child documents can't be
+    created directly by user but can only be created by the parent document
+    (usually when it's being created itself). They also can't be independently
+    saved. A child document has its own view with the corresponding window.
+    This view can be closed by user but, importantly, is also automatically
+    closed when its parent document is closed. Thus, child documents may be
+    convenient for creating additional windows which need to be closed when the
+    main document is. The docview sample demonstrates this use of child
+    documents by creating a child document containing the information about the
+    parameters of the image opened in the main document.
+

     @library{wxcore}
     @category{docview}
 
     @library{wxcore}
     @category{docview}
 


@@ -987,13 +1169,19 @@ public:
     /**
         Constructor. Define your own default constructor to initialize
         application-specific data.
     /**
         Constructor. Define your own default constructor to initialize
         application-specific data.

+
+        @param parent
+            Specifying a non-@c NULL parent document here makes this document a
+            special <em>child document</em>, see their description in the class
+            documentation. Notice that this parameter exists but is ignored in
+            wxWidgets versions prior to 2.9.1.

     */
     */

-    wxDocument();
+    wxDocument(wxDocument* parent = NULL);

 
     /**
         Destructor. Removes itself from the document manager.
     */
 
     /**
         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
 
     /**
         If the view is not already in the list of views, adds the view and


@@ -1001,6 +1189,22 @@ public:
     */
     virtual bool AddView(wxView* view);
 
     */
     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
     /**
         Closes the document, by calling OnSaveModified() and then (if this
         returned @true) OnCloseDocument(). This does not normally delete the


@@ -1017,18 +1221,30 @@ public:
     */
     virtual bool DeleteAllViews();
 
     */
     virtual bool DeleteAllViews();
 

+    /**
+        Virtual method called from OnCloseDocument().
+
+        This method may be overridden to perform any additional cleanup which
+        might be needed when the document is closed.
+
+        The return value of this method is currently ignored.
+
+        The default version does nothing and simply returns @true.
+     */
+    virtual bool DeleteContents();
+

     /**
         Returns a pointer to the command processor associated with this
         document.
 
         @see wxCommandProcessor
     */
     /**
         Returns a pointer to the command processor associated with this
         document.
 
         @see wxCommandProcessor
     */

-    wxCommandProcessor* GetCommandProcessor() const;
+    virtual wxCommandProcessor* GetCommandProcessor() const;

 
     /**
         Gets a pointer to the associated document manager.
     */
 
     /**
         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
 
     /**
         Gets the document type name for this document. See the comment for


@@ -1036,17 +1252,24 @@ public:
     */
     wxString GetDocumentName() const;
 
     */
     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.
     */
     /**
         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.
     */
 
     /**
         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
 
     /**
         Gets the filename associated with this document, or "" if none is


@@ -1076,12 +1299,27 @@ public:
     */
     virtual wxString GetUserReadableName() const;
 
     */
     virtual wxString GetUserReadableName() const;
 

+    //@{

     /**
         Returns the list whose elements are the views on the document.
 
         @see GetFirstView()
     */
     /**
         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 this document is a child document corresponding to a
+        part of the parent document and not a disk file as usual.
+
+        This method can be used to check whether file-related operations make
+        sense for this document as they only apply to top-level documents and
+        not child ones.
+
+        @since 2.9.2
+     */
+    bool IsChildDocument() const;

 
     /**
         Returns @true if the document has been modified since the last save,
 
     /**
         Returns @true if the document has been modified since the last save,


@@ -1122,17 +1360,37 @@ public:
     virtual void OnChangedViewList();
 
     /**
     virtual void OnChangedViewList();
 
     /**

-        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().
+        This virtual function is called when the document is being closed.
+
+        The default implementation calls DeleteContents() (which may be
+        overridden to perform additional cleanup) 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
     */
     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);
 
     */
     virtual bool OnCreate(const wxString& path, long flags);
 


@@ -1172,7 +1430,7 @@ public:
 
     /**
         If the document has been modified, prompts the user to ask if the
 
     /**
         If the document has been modified, prompts the user to ask if the

-        changes should be changed. If the user replies Yes, the Save() function
+        changes should be saved. If the user replies Yes, the Save() function

         is called. If No, the document is marked as unmodified and the function
         succeeds. If Cancel, the function fails.
     */
         is called. If No, the document is marked as unmodified and the function
         succeeds. If Cancel, the function fails.
     */


@@ -1196,6 +1454,14 @@ public:
     */
     virtual bool SaveAs();
 
     */
     virtual bool SaveAs();
 

+    /**
+        Discard changes and load last saved version.
+
+        Prompts the user first, and then calls DoOpenDocument() to reload the
+        current file.
+    */
+    virtual bool Revert();
+

     //@{
     /**
         Override this function and call it from your own SaveObject() before
     //@{
     /**
         Override this function and call it from your own SaveObject() before


@@ -1228,15 +1494,38 @@ public:
         Sets the pointer to the template that created the document. Should only
         be called by the framework.
     */
         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 if this document has been already saved or not.
+
+        Normally there is no need to call this function as the document-view
+        framework does it itself as the documents are loaded from and saved to
+        the files. However it may be useful in some particular cases, for
+        example it may be called with @false argument to prevent the user
+        from saving the just opened document into the same file if this
+        shouldn't be done for some reason (e.g. file format version changes and
+        a new extension should be used for saving).
+
+        @see GetDocumentSaved(), AlreadySaved()
+     */
+    void SetDocumentSaved(bool saved = true);

 
     /**
         Sets the filename for this document. Usually called by the framework.
 
 
     /**
         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.
         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
 
     /**
         Sets the title for this document. The document title is used for an


@@ -1250,7 +1539,7 @@ public:
         view. @a hint represents optional information to allow a view to
         optimize its update.
     */
         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:
     /**
 
 protected:
     /**


@@ -1316,152 +1605,11 @@ protected:
 };
 
 
 };
 
 

-
-/**
-    @class wxFileHistory
-
-    The wxFileHistory encapsulates a user interface convenience, the list of
-    most recently visited files as shown on a menu (usually the File menu).
-
-    wxFileHistory can manage one or more file menus. More than one menu may be
-    required in an MDI application, where the file history should appear on
-    each MDI child menu as well as the MDI parent frame.
-
-    @library{wxcore}
-    @category{docview}
-
-    @see @ref overview_docview, wxDocManager
-*/
-class wxFileHistory : public wxObject
-{
-public:
-    /**
-        Constructor. Pass the maximum number of files that should be stored and
-        displayed.
-
-        @a idBase defaults to wxID_FILE1 and represents the id given to the
-        first history menu item. Since menu items can't share the same ID you
-        should change @a idBase (to one of your own defined IDs) when using
-        more than one wxFileHistory in your application.
-    */
-    wxFileHistory(size_t maxFiles = 9, wxWindowID idBase = wxID_FILE1);
-
-    /**
-        Destructor.
-    */
-    ~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);
-
-    /**
-        Appends the files in the history list, to all menus managed by the file
-        history object.
-    */
-    void AddFilesToMenu();
-    /**
-        Appends the files in the history list, to the given menu only.
-    */
-    void AddFilesToMenu(wxMenu* menu);
-
-    /**
-        Returns the base identifier for the range used for appending items.
-    */
-    wxWindowID GetBaseId() const;
-
-    /**
-        Returns the number of files currently stored in the file history.
-    */
-    size_t GetCount() const;
-
-    /**
-        Returns the file at this index (zero-based).
-    */
-    wxString GetHistoryFile(size_t index) const;
-
-    /**
-        Returns the maximum number of files that can be stored.
-    */
-    int GetMaxFiles() const;
-
-    /**
-        Returns the list of menus that are managed by this file history object.
-
-        @see UseMenu()
-    */
-    const wxList& GetMenus() const;
-
-    /**
-        Loads the file history from the given config object. This function
-        should be called explicitly by the application.
-
-        @see wxConfigBase
-    */
-    void Load(const wxConfigBase& config);
-
-    /**
-        Removes the specified file from the history.
-    */
-    void RemoveFileFromHistory(size_t i);
-
-    /**
-        Removes this menu from the list of those managed by this object.
-    */
-    void RemoveMenu(wxMenu* menu);
-
-    /**
-        Saves the file history into the given config object. This must be
-        called explicitly by the application.
-
-        @see wxConfigBase
-    */
-    void Save(wxConfigBase& config);
-
-    /**
-        Sets the base identifier for the range used for appending items.
-    */
-    void SetBaseId(wxWindowID baseId);
-
-    /**
-        Adds this menu to the list of those menus that are managed by this file
-        history object. Also see AddFilesToMenu() for initializing the menu
-        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;
-};
-
-
-

 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
 // ============================================================================
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_file */
+/** @addtogroup group_funcmacro_file */

 //@{
 
 /**
 //@{
 
 /**