Mention wxGCDC

[wxWidgets.git] / interface / docview.h
diff --git a/interface/docview.h b/interface/docview.h

index 67759e5350f9d2c858511dc7a27f38f51471fb41..ccc13d4189da5fe57ef17a424405a9bf4ac9191e 100644 (file)
--- a/interface/docview.h
+++ b/interface/docview.h
@@ -1,6 +1,6 @@
  /////////////////////////////////////////////////////////////////////////////
  // Name:        docview.h
  /////////////////////////////////////////////////////////////////////////////
  // Name:        docview.h
-// Purpose:     documentation for wxDocTemplate class
+// Purpose:     interface of various doc/view framework classes
  // Author:      wxWidgets team
  // RCS-ID:      $Id$
  // Licence:     wxWindows license
  // Author:      wxWidgets team
  // RCS-ID:      $Id$
  // Licence:     wxWindows license
@@ -14,69 +14,57 @@
      document class and a view class.
  
      @library{wxcore}
      document class and a view class.
  
      @library{wxcore}
-    @category{dvf}
+    @category{docview}
  
  
-    @seealso
-    @ref overview_wxdoctemplateoverview "wxDocTemplate overview", wxDocument, wxView
+    @see @ref overview_docview_wxdoctemplate, wxDocument, wxView
  */
  class wxDocTemplate : public wxObject
  {
  public:
      /**
  */
  class wxDocTemplate : public wxObject
  {
  public:
      /**
-        Constructor. Create instances dynamically near the start of your application
-        after creating
-        a wxDocManager instance, and before doing any document or view operations.
-        @a manager is the document manager object which manages this template.
-        @a descr is a short description of what the template is for. This string will
-        be displayed in the
-        file filter list of Windows file selectors.
-        @a filter is an appropriate file filter such as @c *.txt.
-        @a dir is the default directory to use for file selectors.
-        @a ext is the default file extension (such as txt).
-        @a docTypeName is a name that should be unique for a given type of document,
-        used for
-        gathering a list of views relevant to a particular document.
-        @a viewTypeName is a name that should be unique for a given view.
-        @a docClassInfo is a pointer to the run-time document class information as
-        returned
-        by the CLASSINFO macro, e.g. CLASSINFO(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.
-        @a viewClassInfo is a pointer to the run-time view class information as returned
-        by the CLASSINFO macro, e.g. CLASSINFO(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.
-        @a flags is a bit list of the following:
-         wxTEMPLATE_VISIBLE The template may be displayed to the user in dialogs.
-         wxTEMPLATE_INVISIBLE The template may not be displayed to the user in dialogs.
-         wxDEFAULT_TEMPLATE_FLAGS Defined as wxTEMPLATE_VISIBLE.
-        
-        
-        @b Wx::DocTemplate-new( docmgr, descr, filter, dir,
-        ext, docTypeName, viewTypeName, docClassInfo, viewClassInfo, flags
-        )
-        
-         will construct document and view objects from the class information
-        
-        @b Wx::DocTemplate-new( docmgr, descr, filter, dir,
-        ext, docTypeName, viewTypeName, docClassName, viewClassName, flags
-        )
-        
-         will construct document and view objects from perl packages
-        
-        @b Wx::DocTemplate-new( docmgr, descr, filter, dir,
-        ext, docTypeName, viewTypeName )
-        
-        @c Wx::DocTemplate::CreateDocument() and
-        @c Wx::DocTemplate::CreateView() must be overridden
+        Constructor. Create instances dynamically near the start of your
+        application after creating a wxDocManager instance, and before doing
+        any document or view operations.
+
+        @param manager
+            The document manager object which manages this template.
+        @param descr
+            A short description of what the template is for. This string will
+            be displayed in the file filter list of Windows file selectors.
+        @param filter
+            An appropriate file filter such as "*.txt".
+        @param dir
+            The default directory to use for file selectors.
+        @param ext
+            The default file extension (such as "txt").
+        @param docTypeName
+            A name that should be unique for a given type of document, used for
+            gathering a list of views relevant to a particular document.
+        @param viewTypeName
+            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
+            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
+            supplied, you will need to derive a new wxDocTemplate class and
+            override the CreateView() member to return a new view instance on
+            demand.
+        @param flags
+            A bit list of the following:
+            - wxTEMPLATE_VISIBLE       - The template may be displayed to the
+                                         user in dialogs.
+            - wxTEMPLATE_INVISIBLE     - The template may not be displayed to
+                                         the user in dialogs.
+            - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE.
      */
      wxDocTemplate(wxDocManager* manager, const wxString& descr,
      */
      wxDocTemplate(wxDocManager* manager, const wxString& descr,
-                  const wxString& filter,
-                  const wxString& dir,
-                  const wxString& ext,
-                  const wxString& docTypeName,
+                  const wxString& filter, const wxString& dir,
+                  const wxString& ext, const wxString& docTypeName,
                    const wxString& viewTypeName,
                    wxClassInfo* docClassInfo = NULL,
                    wxClassInfo* viewClassInfo = NULL,
                    const wxString& viewTypeName,
                    wxClassInfo* docClassInfo = NULL,
                    wxClassInfo* viewClassInfo = NULL,
@@ -88,54 +76,56 @@ public:
      ~wxDocTemplate();
  
      /**
      ~wxDocTemplate();
  
      /**
-        Creates a new instance of the associated document class. If you have not
-        supplied
-        a wxClassInfo parameter to the template constructor, you will need to override
-        this
-        function to return an appropriate document instance.
-        This function calls InitDocument() which in turns
-        calls wxDocument::OnCreate.
+        Creates a new instance of the associated document class. If you have
+        not supplied a wxClassInfo parameter to the template constructor, you
+        will need to override this function to return an appropriate document
+        instance.
+
+        This function calls InitDocument() which in turns calls
+        wxDocument::OnCreate().
      */
      wxDocument* CreateDocument(const wxString& path, long flags = 0);
  
      /**
      */
      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.
      */
      wxView* CreateView(wxDocument* doc, long flags = 0);
  
      /**
      */
      wxView* CreateView(wxDocument* doc, long flags = 0);
  
      /**
-        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();
  
      /**
-        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();
  
      /**
-        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();
  
      /**
-        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();
  
      /**
-        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();
  
      /**
      */
      wxString GetDocumentName();
  
      /**
-        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();
  
@@ -145,20 +135,20 @@ public:
      long GetFlags();
  
      /**
      long GetFlags();
  
      /**
-        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();
  
      /**
      */
      wxString GetViewName();
  
      /**
-        Initialises the document, calling wxDocument::OnCreate. This is called from
-        CreateDocument().
+        Initialises the document, calling wxDocument::OnCreate(). This is
+        called from CreateDocument().
      */
      */
-    bool InitDocument(wxDocument* doc, const wxString& path,
-                      long flags = 0);
+    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();
  
@@ -178,9 +168,8 @@ public:
      void SetDirectory(const wxString& dir);
  
      /**
      void SetDirectory(const wxString& dir);
  
      /**
-        Sets the pointer to the document manager instance for which this template was
-        created.
-        Should not be called by the application.
+        Sets the pointer to the document manager instance for which this
+        template was created. Should not be called by the application.
      */
      void SetDocumentManager(wxDocManager* manager);
  
      */
      void SetDocumentManager(wxDocManager* manager);
  
@@ -190,104 +179,94 @@ public:
      void SetFileFilter(const wxString& filter);
  
      /**
      void SetFileFilter(const wxString& filter);
  
      /**
-        Sets the internal document template flags (see the constructor description for
-        more details).
+        Sets the internal document template flags (see the constructor
+        description for more details).
      */
      void SetFlags(long flags);
  
      /**
      */
      void SetFlags(long flags);
  
      /**
-        wxString m_defaultExt
          The default extension for files of this type.
      */
          The default extension for files of this type.
      */
-
+    wxString m_defaultExt;
  
      /**
  
      /**
-        wxString m_description
          A short description of this template.
      */
          A short description of this template.
      */
-
+    wxString m_description;
  
      /**
  
      /**
-        wxString m_directory
          The default directory for files of this type.
      */
          The default directory for files of this type.
      */
-
+    wxString m_directory;
  
      /**
  
      /**
-        wxClassInfo*  m_docClassInfo
-        Run-time class information that allows document instances to be constructed
-        dynamically.
+        Run-time class information that allows document instances to be
+        constructed dynamically.
      */
      */
-
+    wxClassInfo* m_docClassInfo;
  
      /**
  
      /**
-        wxString m_docTypeName
          The named type of the document associated with this template.
      */
          The named type of the document associated with this template.
      */
-
+    wxString m_docTypeName;
  
      /**
  
      /**
-        wxDocTemplate* m_documentManager
          A pointer to the document manager for which this template was created.
      */
          A pointer to the document manager for which this template was created.
      */
-
+    wxDocTemplate* m_documentManager;
  
      /**
  
      /**
-        wxString m_fileFilter
-        The file filter (such as @c *.txt) to be used in file selector dialogs.
+        The file filter (such as "*.txt") to be used in file selector dialogs.
      */
      */
-
+    wxString m_fileFilter;
  
      /**
  
      /**
-        long m_flags
          The flags passed to the constructor.
      */
          The flags passed to the constructor.
      */
-
+    long m_flags;
  
      /**
  
      /**
-        wxClassInfo* m_viewClassInfo
          Run-time class information that allows view instances to be constructed
          dynamically.
      */
          Run-time class information that allows view instances to be constructed
          dynamically.
      */
-
+    wxClassInfo* m_viewClassInfo;
  
      /**
  
      /**
-        wxString m_viewTypeName
          The named type of the view associated with this template.
      */
          The named type of the view associated with this template.
      */
+    wxString m_viewTypeName;
  };
  
  
  };
  
  
+
  /**
      @class wxDocManager
      @wxheader{docview.h}
  
      The wxDocManager class is part of the document/view framework supported by
  /**
      @class wxDocManager
      @wxheader{docview.h}
  
      The wxDocManager class is part of the document/view framework supported by
-    wxWidgets,
-    and cooperates with the wxView, wxDocument
-    and wxDocTemplate classes.
+    wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate
+    classes.
  
      @library{wxcore}
  
      @library{wxcore}
-    @category{dvf}
+    @category{docview}
  
  
-    @seealso
-    @ref overview_wxdocmanageroverview "wxDocManager overview", wxDocument, wxView,
-    wxDocTemplate, wxFileHistory
+    @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate,
+         wxFileHistory
  */
  class wxDocManager : public wxEvtHandler
  {
  public:
      /**
  */
  class wxDocManager : public wxEvtHandler
  {
  public:
      /**
-        Constructor. Create a document manager instance dynamically near the start of
-        your application
-        before doing any document or view operations.
+        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.
          @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.
+
+        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.
      */
      wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS,
                   bool initialize = true);
      */
      wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS,
                   bool initialize = true);
@@ -308,8 +287,8 @@ public:
      void AddDocument(wxDocument* doc);
  
      /**
      void AddDocument(wxDocument* doc);
  
      /**
-        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);
  
      */
      void AddFileToHistory(const wxString& filename);
  
@@ -324,31 +303,30 @@ public:
      bool CloseDocuments(bool force = true);
  
      /**
      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 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.
      */
      wxDocument* CreateDocument(const wxString& path, long flags);
  
      /**
      */
      wxDocument* CreateDocument(const wxString& path, long flags);
  
      /**
-        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);
  
      */
      wxView* CreateView(wxDocument* doc, long flags);
  
@@ -357,52 +335,57 @@ public:
      */
      void DisassociateTemplate(wxDocTemplate* temp);
  
      */
      void DisassociateTemplate(wxDocTemplate* temp);
  
-    //@{
      /**
      /**
-        Appends the files in the history list, to the given menu only.
+        Appends the files in the history list to all menus managed by the file
+        history object.
      */
      void FileHistoryAddFilesToMenu();
      */
      void FileHistoryAddFilesToMenu();
+    /**
+        Appends the files in the history list to the given @a menu only.
+    */
      void FileHistoryAddFilesToMenu(wxMenu* menu);
      void FileHistoryAddFilesToMenu(wxMenu* menu);
-    //@}
  
      /**
          Loads the file history from a config object.
  
      /**
          Loads the file history from a config object.
-        
-        @see wxConfig
+
+        @see wxConfigBase
      */
      void FileHistoryLoad(wxConfigBase& config);
  
      /**
      */
      void FileHistoryLoad(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);
  
      /**
          Saves the file history into a config object. This must be called
          explicitly by the application.
      */
      void FileHistoryRemoveMenu(wxMenu* menu);
  
      /**
          Saves the file history into a config object. This must be called
          explicitly by the application.
-        
-        @see wxConfig
+
+        @see wxConfigBase
      */
      void FileHistorySave(wxConfigBase& resourceFile);
  
      /**
      */
      void FileHistorySave(wxConfigBase& resourceFile);
  
      /**
-        Use this menu for appending recently-visited document filenames, for convenient
-        access. Calling this function with a valid menu pointer enables the history
-        list functionality.
-        Note that you can add multiple menus using this function, to be managed by the
-        file history object.
+        Use this menu for appending recently-visited document filenames, for
+        convenient access. Calling this function with a valid menu pointer
+        enables the history list functionality.
+
+        @note You can add multiple menus using this function, to be managed by
+              the file history object.
      */
      void FileHistoryUseMenu(wxMenu* menu);
  
      /**
      */
      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);
  
      /**
      */
      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();
  
@@ -427,8 +410,8 @@ public:
      size_t GetHistoryFilesCount();
  
      /**
      size_t GetHistoryFilesCount();
  
      /**
-        Returns the directory last selected by the user when opening a file. Initially
-        empty.
+        Returns the directory last selected by the user when opening a file.
+        Initially empty.
      */
      wxString GetLastDirectory() const;
  
      */
      wxString GetLastDirectory() const;
  
@@ -443,32 +426,34 @@ public:
      wxList GetTemplates();
  
      /**
      wxList GetTemplates();
  
      /**
-        Initializes data; currently just calls OnCreateFileHistory. Some data cannot
-        always be initialized in the constructor because the programmer must be given
-        the opportunity to override functionality. If OnCreateFileHistory was called
-        from the constructor, an overridden virtual OnCreateFileHistory would not be
-        called due to C++'s 'interesting' constructor semantics. In fact Initialize
-        @e is called from the wxDocManager constructor, but this can be
-        vetoed by passing @false to the second argument, allowing the derived class's
-        constructor to call Initialize, possibly calling a different OnCreateFileHistory
-        from the default.
-        The bottom line: if you're not deriving from Initialize, forget it and
-        construct wxDocManager with no arguments.
+        Initializes data; currently just calls OnCreateFileHistory().
+
+        Some data cannot always be initialized in the constructor because the
+        programmer must be given the opportunity to override functionality. If
+        OnCreateFileHistory() was called from the constructor, an overridden
+        virtual OnCreateFileHistory() would not be called due to C++'s
+        'interesting' constructor semantics. In fact Initialize() @e is called
+        from the wxDocManager constructor, but this can be vetoed by passing
+        @false to the second argument, allowing the derived class's constructor
+        to call Initialize(), possibly calling a different
+        OnCreateFileHistory() from the default.
+
+        The bottom line: if you're not deriving from Initialize(), forget it
+        and construct wxDocManager with no arguments.
      */
      bool Initialize();
  
      /**
      */
      bool Initialize();
  
      /**
-        Return a string containing a suitable default name for a new document. By
-        default this is implemented by appending an integer counter to the string
-        @b unnamed but can be overridden in the derived classes to do something more
-        appropriate.
+        Return a string containing a suitable default name for a new document.
+        By default this is implemented by appending an integer counter to the
+        string @b unnamed but can be overridden in the derived classes to do
+        something more appropriate.
      */
      wxString MakeNewDocumentName();
  
      /**
      */
      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();
  
      */
      wxFileHistory* OnCreateFileHistory();
  
@@ -483,7 +468,8 @@ public:
      void OnFileCloseAll(wxCommandEvent& event);
  
      /**
      void OnFileCloseAll(wxCommandEvent& event);
  
      /**
-        Creates a document from a list of templates (if more than one template).
+        Creates a document from a list of templates (if more than one
+        template).
      */
      void OnFileNew(wxCommandEvent& event);
  
      */
      void OnFileNew(wxCommandEvent& event);
  
@@ -493,18 +479,19 @@ public:
      void OnFileOpen(wxCommandEvent& event);
  
      /**
      void OnFileOpen(wxCommandEvent& event);
  
      /**
-        Reverts the current document by calling wxDocument::Revert for the current
-        document.
+        Reverts the current document by calling wxDocument::Revert() for the
+        current document.
      */
      void OnFileRevert(wxCommandEvent& event);
  
      /**
      */
      void OnFileRevert(wxCommandEvent& event);
  
      /**
-        Saves the current document by calling wxDocument::Save for the current document.
+        Saves the current document by calling wxDocument::Save() for the
+        current document.
      */
      void OnFileSave(wxCommandEvent& event);
  
      /**
      */
      void OnFileSave(wxCommandEvent& event);
  
      /**
-        Calls wxDocument::SaveAs for the current document.
+        Calls wxDocument::SaveAs() for the current document.
      */
      void OnFileSaveAs(wxCommandEvent& event);
  
      */
      void OnFileSaveAs(wxCommandEvent& event);
  
@@ -514,149 +501,134 @@ public:
      void RemoveDocument(wxDocument* doc);
  
      /**
      void RemoveDocument(wxDocument* doc);
  
      /**
-        Under Windows, pops up a file selector with a list of filters corresponding to
-        document templates.
-        The wxDocTemplate corresponding to the selected file's extension is returned.
-        On other platforms, if there is more than one document template a choice list
-        is popped up,
-        followed by a file selector.
+        Under Windows, pops up a file selector with a list of filters
+        corresponding to document templates. The wxDocTemplate corresponding to
+        the selected file's extension is returned.
+
+        On other platforms, if there is more than one document template a
+        choice list is popped up, followed by a file selector.
+
          This function is used in CreateDocument().
          This function is used in CreateDocument().
-          (doctemplate, path) = My::DocManager-SelectDocumentPath( ... );
      */
      wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates,
      */
      wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates,
-                                      int noTemplates,
-                                      wxString& path,
-                                      long flags,
-                                      bool save);
+                                      int noTemplates, wxString& path,
+                                      long flags, bool save);
  
      /**
  
      /**
-        Returns a document template by asking the user (if there is more than one
-        template).
-        This function is used in CreateDocument().
-        
+        Returns a document template by asking the user (if there is more than
+        one template). This function is used in CreateDocument().
+
          @param templates
          @param templates
-            Pointer to an array of templates from which to choose a desired template.
+            Pointer to an array of templates from which to choose a desired
+            template.
          @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 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.
+            If more than one template is passed in in 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.
      */
      wxDocTemplate* SelectDocumentType(wxDocTemplate** templates,
      */
      wxDocTemplate* SelectDocumentType(wxDocTemplate** templates,
-                                      int noTemplates,
-                                      bool sort = false);
+                                      int noTemplates, bool sort = false);
  
      /**
  
      /**
-        Returns a document template by asking the user (if there is more than one
-        template),
-        displaying a list of valid views. This function is used in CreateView().
-        The dialog normally will not appear because the array of templates only contains
-        those relevant to the document in question, and often there will only be one
-        such.
-        
+        Returns a document template by asking the user (if there is more than
+        one template), displaying a list of valid views. This function is used
+        in CreateView(). The dialog normally will not appear because the array
+        of templates only contains those relevant to the document in question,
+        and often there will only be one such.
+
          @param templates
          @param templates
-            Pointer to an array of templates from which to choose a desired template.
+            Pointer to an array of templates from which to choose a desired
+            template.
          @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 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.
+            If more than one template is passed in in 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.
      */
      wxDocTemplate* SelectViewType(wxDocTemplate** templates,
      */
      wxDocTemplate* SelectViewType(wxDocTemplate** templates,
-                                  int noTemplates,
-                                  bool sort = false);
+                                  int noTemplates, bool sort = false);
  
      /**
  
      /**
-        Sets the directory to be displayed to the user when opening a file. Initially
-        this is empty.
+        Sets the directory to be displayed to the user when opening a file.
+        Initially this is empty.
      */
      void SetLastDirectory(const wxString& dir);
  
      /**
      */
      void SetLastDirectory(const wxString& dir);
  
      /**
-        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.
+        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.
      */
      void SetMaxDocsOpen(int n);
  
      /**
      */
      void SetMaxDocsOpen(int n);
  
      /**
-        wxView* m_currentView
          The currently active view.
      */
          The currently active view.
      */
-
+    wxView* m_currentView;
  
      /**
  
      /**
-        int m_defaultDocumentNameCounter
          Stores the integer to be used for the next default document name.
      */
          Stores the integer to be used for the next default document name.
      */
-
+    int m_defaultDocumentNameCounter;
  
      /**
  
      /**
-        wxList m_docs
          A list of all documents.
      */
          A list of all documents.
      */
-
+    wxList m_docs;
  
      /**
  
      /**
-        wxFileHistory* m_fileHistory
-        A pointer to an instance of wxFileHistory,
-        which manages the history of recently-visited files on the File menu.
+        A pointer to an instance of wxFileHistory, which manages the history of
+        recently-visited files on the File menu.
      */
      */
-
+    wxFileHistory* m_fileHistory;
  
      /**
  
      /**
-        long m_flags
          Stores the flags passed to the constructor.
      */
          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
      */
      */
-
+    wxFileHistory* m_fileHistory;
  
      /**
  
      /**
-        int m_maxDocsOpen
          Stores the maximum number of documents that can be opened before
          existing documents are closed. By default, this is 10,000.
      */
          Stores the maximum number of documents that can be opened before
          existing documents are closed. By default, this is 10,000.
      */
+    int m_maxDocsOpen;
  };
  
  
  };
  
  
+
  /**
      @class wxView
      @wxheader{docview.h}
  
      The view class can be used to model the viewing and editing component of
      an application's file-based data. It is part of the document/view framework
  /**
      @class wxView
      @wxheader{docview.h}
  
      The view class can be used to model the viewing and editing component of
      an application's file-based data. It is part of the document/view framework
-    supported by wxWidgets,
-    and cooperates with the wxDocument, wxDocTemplate
+    supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
      and wxDocManager classes.
  
      @library{wxcore}
      and wxDocManager classes.
  
      @library{wxcore}
-    @category{dvf}
+    @category{docview}
  
  
-    @seealso
-    @ref overview_wxviewoverview "wxView overview", wxDocument, wxDocTemplate,
-    wxDocManager
+    @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager
  */
  class wxView : public wxEvtHandler
  {
  public:
      /**
          Constructor. Define your own default constructor to initialize
  */
  class wxView : public wxEvtHandler
  {
  public:
      /**
          Constructor. Define your own default constructor to initialize
-        application-specific
-        data.
+        application-specific data.
      */
      wxView();
  
      */
      wxView();
  
@@ -666,22 +638,22 @@ public:
      ~wxView();
  
      /**
      ~wxView();
  
      /**
-        Call this from your view frame's OnActivate member to tell the framework which
-        view is
-        currently active. If your windowing system doesn't call OnActivate, you may
-        need to
-        call this function from any place where you know the view must
-        be active, and the framework will need to get the current view.
-        The prepackaged view frame wxDocChildFrame calls Activate() from its OnActivate
-        member.
+        Call this from your view frame's wxDocChildFrame::OnActivate() member
+        to tell the framework which view is currently active. If your windowing
+        system doesn't call wxDocChildFrame::OnActivate(), you may need to call
+        this function from any place where you know the view must be active,
+        and the framework will need to get the current view.
+
+        The prepackaged view frame wxDocChildFrame calls Activate() from its
+        wxDocChildFrame::OnActivate() member.
+
          This function calls OnActivateView().
      */
      virtual void Activate(bool activate);
  
      /**
          This function calls OnActivateView().
      */
      virtual void Activate(bool activate);
  
      /**
-        Closes the view by calling OnClose. If @a deleteWindow is @true, this function
-        should
-        delete the window associated with the view.
+        Closes the view by calling OnClose(). If @a deleteWindow is @true, this
+        function should delete the window associated with the view.
      */
      virtual bool Close(bool deleteWindow = true);
  
      */
      virtual bool Close(bool deleteWindow = true);
  
@@ -691,74 +663,76 @@ public:
      wxDocument* GetDocument() const;
  
      /**
      wxDocument* GetDocument() const;
  
      /**
-        Returns a pointer to the document manager instance associated with this view.
+        Returns a pointer to the document manager instance associated with this
+        view.
      */
      wxDocManager* GetDocumentManager() const;
  
      /**
      */
      wxDocManager* GetDocumentManager() const;
  
      /**
-        Gets the frame associated with the view (if any). Note that this "frame'' is
-        not a wxFrame at all in the generic MDI implementation which uses the notebook
-        pages instead of the frames and this is why this method returns a wxWindow and
-        not a wxFrame.
+        Gets the frame associated with the view (if any). Note that this
+        "frame" is not a wxFrame at all in the generic MDI implementation which
+        uses notebook pages instead of frames and this is why this method
+        returns a wxWindow and not a wxFrame.
      */
      wxWindow* GetFrame();
  
      /**
          Gets the name associated with the view (passed to the wxDocTemplate
      */
      wxWindow* GetFrame();
  
      /**
          Gets the name associated with the view (passed to the wxDocTemplate
-        constructor).
-        Not currently used by the framework.
+        constructor). Not currently used by the framework.
      */
      wxString GetViewName() const;
  
      /**
          Called when a view is activated by means of Activate(). The default
      */
      wxString GetViewName() const;
  
      /**
          Called when a view is activated by means of Activate(). The default
-        implementation does
-        nothing.
+        implementation does nothing.
      */
      virtual void OnActivateView(bool activate, wxView* activeView,
                                  wxView* deactiveView);
  
      /**
      */
      virtual void OnActivateView(bool activate, wxView* activeView,
                                  wxView* deactiveView);
  
      /**
-        Called when the filename has changed. The default implementation constructs a
-        suitable title and sets the title of the view frame (if any).
+        Called when the filename has changed. The default implementation
+        constructs a suitable title and sets the title of the view frame (if
+        any).
      */
      virtual void OnChangeFilename();
  
      /**
      */
      virtual void OnChangeFilename();
  
      /**
-        Implements closing behaviour. The default implementation calls wxDocument::Close
-        to close the associated document. Does not delete the view. The application
-        may wish to do some cleaning up operations in this function, @e if a
-        call to wxDocument::Close succeeded. For example, if your views
-        all share the same window, you need to disassociate the window from the view
-        and perhaps clear the window. If @a deleteWindow is @true, delete the
-        frame associated with the view.
+        Implements closing behaviour. The default implementation calls
+        wxDocument::Close() to close the associated document. Does not delete
+        the view. The application may wish to do some cleaning up operations in
+        this function, @e if a call to wxDocument::Close() succeeded. For
+        example, if your views all share the same window, you need to
+        disassociate the window from the view and perhaps clear the window. If
+        @a deleteWindow is @true, delete the frame associated with the view.
      */
      virtual bool OnClose(bool deleteWindow);
  
      /**
      */
      virtual bool OnClose(bool deleteWindow);
  
      /**
-        Override this to clean up the view when the document is being
-        closed.
+        Override this to clean up the view when the document is being closed.
      */
      virtual void OnClosingDocument();
  
      /**
      */
      virtual void OnClosingDocument();
  
      /**
-        wxDocManager or wxDocument creates a wxView via a wxDocTemplate.
-        Just after the wxDocTemplate creates the wxView, it calls
-        OnCreate(). In its OnCreate member function, the wxView can create a
-        wxDocChildFrame
-        or a derived class. This wxDocChildFrame provides user interface
-        elements to view and/or edit the contents of the wxDocument.
+        wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just
+        after the wxDocTemplate creates the wxView, it calls OnCreate(). The
+        wxView can create a wxDocChildFrame (or derived class) in its
+        wxView::OnCreate() member function. This wxDocChildFrame provides user
+        interface elements to view and/or edit the contents of the wxDocument.
+
          By default, simply returns @true. If the function returns @false, the
          view will be deleted.
      */
      virtual bool OnCreate(wxDocument* doc, long flags);
  
      /**
          By default, simply returns @true. If the function returns @false, the
          view will be deleted.
      */
      virtual bool OnCreate(wxDocument* doc, long flags);
  
      /**
-        If the printing framework is enabled in the library, this function returns a
-        wxPrintout object for the purposes of printing. It should create a new object
-        every time it is called; the framework will delete objects it creates.
-        By default, this function returns an instance of wxDocPrintout, which prints
-        and previews one page by calling OnDraw().
+        If the printing framework is enabled in the library, this function
+        returns a wxPrintout object for the purposes of printing. It should
+        create a new object every time it is called; the framework will delete
+        objects it creates.
+
+        By default, this function returns an instance of wxDocPrintout, which
+        prints and previews one page by calling OnDraw().
+
          Override to return an instance of a class other than wxDocPrintout.
      */
      virtual wxPrintout* OnCreatePrintout();
          Override to return an instance of a class other than wxDocPrintout.
      */
      virtual wxPrintout* OnCreatePrintout();
@@ -769,11 +743,16 @@ public:
      virtual void OnDraw(wxDC* dc);
  
      /**
      virtual void OnDraw(wxDC* dc);
  
      /**
-        Called when the view should be updated. @a sender is a pointer to the view
-        that sent the update request, or @NULL if no single view requested the update
-        (for instance,
-        when the document is opened). @a hint is as yet unused but may in future contain
-        application-specific information for making updating more efficient.
+        Called when the view should be updated.
+
+        @param sender
+            A pointer to the wxView that sent the update request, or @NULL if
+            no single view requested the update (for instance, when the
+            document is opened).
+        @param hint
+            This is unused currently, but may in future contain
+            application-specific information for making updating more
+            efficient.
      */
      virtual void OnUpdate(wxView* sender, wxObject* hint);
  
      */
      virtual void OnUpdate(wxView* sender, wxObject* hint);
  
@@ -784,10 +763,11 @@ public:
      void SetDocument(wxDocument* doc);
  
      /**
      void SetDocument(wxDocument* doc);
  
      /**
-        Sets the frame associated with this view. The application should call this
-        if possible, to tell the view about the frame.
-        See GetFrame() for the explanation about the mismatch
-        between the "Frame'' in the method name and the type of its parameter.
+        Sets the frame associated with this view. The application should call
+        this if possible, to tell the view about the frame.
+
+        See GetFrame() for the explanation about the mismatch between the
+        "Frame" in the method name and the type of its parameter.
      */
      void SetFrame(wxWindow* frame);
  
      */
      void SetFrame(wxWindow* frame);
  
@@ -797,44 +777,43 @@ public:
      void SetViewName(const wxString& name);
  
      /**
      void SetViewName(const wxString& name);
  
      /**
-        wxDocument* m_viewDocument
-        The document associated with this view. There may be more than one view per
-        document, but there can never be more than one document for one view.
+        The document associated with this view. There may be more than one view
+        per document, but there can never be more than one document for one
+        view.
      */
      */
-
+    wxDocument* m_viewDocument;
  
      /**
  
      /**
-        wxFrame* m_viewFrame
          Frame associated with the view, if any.
      */
          Frame associated with the view, if any.
      */
-
+    wxFrame* m_viewFrame;
  
      /**
  
      /**
-        wxString m_viewTypeName
-        The view type name given to the wxDocTemplate constructor, copied to this
-        variable when the view is created. Not currently used by the framework.
+        The view type name given to the wxDocTemplate constructor, copied to
+        this variable when the view is created. Not currently used by the
+        framework.
      */
      */
+    wxString m_viewTypeName;
  };
  
  
  };
  
  
+
  /**
      @class wxDocChildFrame
      @wxheader{docview.h}
  
      The wxDocChildFrame class provides a default frame for displaying documents
  /**
      @class wxDocChildFrame
      @wxheader{docview.h}
  
      The wxDocChildFrame class provides a default frame for displaying documents
-    on separate windows. This class can only be used for SDI (not MDI) child frames.
+    on separate windows. This class can only be used for SDI (not MDI) child
+    frames.
  
      The class is part of the document/view framework supported by wxWidgets,
  
      The class is part of the document/view framework supported by wxWidgets,
-    and cooperates with the wxView, wxDocument,
-    wxDocManager and wxDocTemplate classes.
-
-    See the example application in @c samples/docview.
+    and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
+    classes.
  
      @library{wxcore}
  
      @library{wxcore}
-    @category{dvf}
+    @category{docview}
  
  
-    @seealso
-    @ref overview_docviewoverview, wxFrame
+    @see @ref overview_docview, @ref page_samples_docview, wxFrame
  */
  class wxDocChildFrame : public wxFrame
  {
  */
  class wxDocChildFrame : public wxFrame
  {
@@ -843,8 +822,7 @@ public:
          Constructor.
      */
      wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent,
          Constructor.
      */
      wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent,
-                    wxWindowID id,
-                    const wxString& title,
+                    wxWindowID id, const wxString& title,
                      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,
@@ -866,8 +844,8 @@ 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
+        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);
          focus for your subwindow.
      */
      void OnActivate(wxActivateEvent event);
@@ -888,53 +866,50 @@ public:
      void SetView(wxView* view);
  
      /**
      void SetView(wxView* view);
  
      /**
-        wxDocument* m_childDocument
          The document associated with the frame.
      */
          The document associated with the frame.
      */
-
+    wxDocument* m_childDocument;
  
      /**
  
      /**
-        wxView* m_childView
          The view associated with the frame.
      */
          The view associated with the frame.
      */
+    wxView* m_childView;
  };
  
  
  };
  
  
+
  /**
      @class wxDocParentFrame
      @wxheader{docview.h}
  
      The wxDocParentFrame class provides a default top-level frame for
  /**
      @class wxDocParentFrame
      @wxheader{docview.h}
  
      The wxDocParentFrame class provides a default top-level frame for
-    applications using the document/view framework. This class can only be used for
-    SDI (not MDI) parent frames.
+    applications using the document/view framework. This class can only be used
+    for SDI (not MDI) parent frames.
  
  
-    It cooperates with the wxView, wxDocument,
-    wxDocManager and wxDocTemplates classes.
-
-    See the example application in @c samples/docview.
+    It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
+    classes.
  
      @library{wxcore}
  
      @library{wxcore}
-    @category{dvf}
+    @category{docview}
  
  
-    @seealso
-    @ref overview_docviewoverview, wxFrame
+    @see @ref overview_docview, @ref page_samples_docview, wxFrame
  */
  class wxDocParentFrame : public wxFrame
  {
  public:
  */
  class wxDocParentFrame : public wxFrame
  {
  public:
-    //@{
      /**
      /**
-        Constructor.
+        Default constructor.
      */
      wxDocParentFrame();
      */
      wxDocParentFrame();
+    /**
+        Constructor.
+    */
      wxDocParentFrame(wxDocManager* manager, wxFrame* parent,
      wxDocParentFrame(wxDocManager* manager, wxFrame* parent,
-                     wxWindowID id,
-                     const wxString& title,
+                     wxWindowID id, const wxString& title,
                       const wxPoint& pos = wxDefaultPosition,
                       const wxSize& size = wxDefaultSize,
                       long style = wxDEFAULT_FRAME_STYLE,
                       const wxString& name = "frame");
                       const wxPoint& pos = wxDefaultPosition,
                       const wxSize& size = wxDefaultSize,
                       long style = wxDEFAULT_FRAME_STYLE,
                       const wxString& name = "frame");
-    //@}
  
      /**
          Destructor.
  
      /**
          Destructor.
@@ -952,43 +927,52 @@ public:
                  const wxString& name = "frame");
  
      /**
                  const wxString& name = "frame");
  
      /**
-        Returns the associated @ref overview_wxdocmanager "document manager object".
+        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.
      */
      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.
+        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);
  };
  
  
      */
      void OnCloseWindow(wxCloseEvent& event);
  };
  
  
+
  /**
      @class wxDocument
      @wxheader{docview.h}
  
  /**
      @class wxDocument
      @wxheader{docview.h}
  
-    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.
+    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.
  
      @library{wxcore}
  
      @library{wxcore}
-    @category{dvf}
+    @category{docview}
  
  
-    @seealso
-    @ref overview_wxdocumentoverview "wxDocument overview", wxView, wxDocTemplate,
-    wxDocManager
+    @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager
  */
  class wxDocument : public wxEvtHandler
  {
  public:
      /**
          Constructor. Define your own default constructor to initialize
  */
  class wxDocument : public wxEvtHandler
  {
  public:
      /**
          Constructor. Define your own default constructor to initialize
-        application-specific
-        data.
+        application-specific data.
      */
      wxDocument();
  
      */
      wxDocument();
  
@@ -998,31 +982,32 @@ public:
      ~wxDocument();
  
      /**
      ~wxDocument();
  
      /**
-        If the view is not already in the list of views, adds the view and calls
-        OnChangedViewList.
+        If the view is not already in the list of views, adds the view and
+        calls OnChangedViewList().
      */
      virtual bool AddView(wxView* view);
  
      /**
      */
      virtual bool AddView(wxView* view);
  
      /**
-        Closes the document, by calling OnSaveModified and then (if this returned @true)
-        OnCloseDocument.
-        This does not normally delete the document object: use DeleteAllViews to do
-        this implicitly.
+        Closes the document, by calling OnSaveModified() and then (if this
+        returned @true) OnCloseDocument(). This does not normally delete the
+        document object, use DeleteAllViews() to do this implicitly.
      */
      virtual bool Close();
  
      /**
      */
      virtual bool Close();
  
      /**
-        Calls wxView::Close and deletes each view. Deleting the final view will
-        implicitly
-        delete the document itself, because the wxView destructor calls RemoveView. This
-        in turns calls OnChangedViewList(), whose default implemention is to
-        save and delete the document if no views exist.
+        Calls wxView::Close() and deletes each view. Deleting the final view
+        will implicitly delete the document itself, because the wxView
+        destructor calls RemoveView(). This in turns calls OnChangedViewList(),
+        whose default implemention is to save and delete the document if no
+        views exist.
      */
      virtual bool DeleteAllViews();
  
      /**
      */
      virtual bool DeleteAllViews();
  
      /**
-        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;
  
      */
      wxCommandProcessor* GetCommandProcessor() const;
  
@@ -1033,7 +1018,7 @@ public:
  
      /**
          Gets the document type name for this document. See the comment for
  
      /**
          Gets the document type name for this document. See the comment for
-        documentTypeName.
+        @ref m_documentTypeName.
      */
      wxString GetDocumentName() const;
  
      */
      wxString GetDocumentName() const;
  
@@ -1043,8 +1028,9 @@ public:
      wxDocTemplate* GetDocumentTemplate() const;
  
      /**
      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;
  
      */
      wxWindow* GetDocumentWindow() const;
  
@@ -1055,16 +1041,17 @@ public:
      wxString GetFilename() const;
  
      /**
      wxString GetFilename() const;
  
      /**
-        A convenience function to get the first view for a document, because
-        in many cases a document will only have a single view.
-        See also: GetViews()
+        A convenience function to get the first view for a document, because in
+        many cases a document will only have a single view.
+
+        @see GetViews()
      */
      wxView* GetFirstView() const;
  
      /**
      */
      wxView* GetFirstView() const;
  
      /**
-        Gets the title for this document. The document title is used for an associated
-        frame (if any), and is usually constructed by the framework from
-        the filename.
+        Gets the title for this document. The document title is used for an
+        associated frame (if any), and is usually constructed by the framework
+        from the filename.
      */
      wxString GetTitle() const;
  
      */
      wxString GetTitle() const;
  
@@ -1077,245 +1064,260 @@ public:
  
      /**
          Returns the list whose elements are the views on the document.
  
      /**
          Returns the list whose elements are the views on the document.
-        See also: GetFirstView()
+
+        @see GetFirstView()
      */
      wxList GetViews() const;
  
      /**
      */
      wxList GetViews() const;
  
      /**
-        Returns @true if the document has been modified since the last save, @false
-        otherwise.
-        You may need to override this if your document view maintains its own
-        record of being modified (for example if using wxTextWindow to view and edit
-        the document).
-        See also Modify().
+        Returns @true if the document has been modified since the last save,
+        @false otherwise. You may need to override this if your document view
+        maintains its own record of being modified.
+
+        @see Modify()
      */
      virtual bool IsModified() const;
  
      //@{
      /**
      */
      virtual bool IsModified() const;
  
      //@{
      /**
-        Override this function and call it from your own LoadObject before
-        streaming your own data. LoadObject is called by the framework
+        Override this function and call it from your own LoadObject() before
+        streaming your own data. LoadObject() is called by the framework
          automatically when the document contents need to be loaded.
          automatically when the document contents need to be loaded.
-        Note that only one of these forms exists, depending on how wxWidgets
-        was configured.
+
+        @note This version of LoadObject() may not exist depending on how
+              wxWidgets was configured.
      */
      */
-    virtual istream LoadObject(istream& stream);
-    virtual wxInputStream LoadObject(wxInputStream& stream);
+    virtual istream& LoadObject(istream& stream);
+    virtual wxInputStream& LoadObject(wxInputStream& stream);
      //@}
  
      /**
      //@}
  
      /**
-        Call with @true to mark the document as modified since the last save, @false
-        otherwise.
-        You may need to override this if your document view maintains its own
-        record of being modified (for example if using wxTextWindow to view and edit
-        the document).
-        See also IsModified().
+        Call with @true to mark the document as modified since the last save,
+        @false otherwise. You may need to override this if your document view
+        maintains its own record of being modified.
+
+        @see IsModified()
      */
      virtual void Modify(bool modify);
  
      /**
      */
      virtual void Modify(bool modify);
  
      /**
-        Called when a view is added to or deleted from this document. The default
-        implementation saves and deletes the document if no views exist (the last
-        one has just been removed).
+        Called when a view is added to or deleted from this document. The
+        default implementation saves and deletes the document if no views exist
+        (the last one has just been removed).
      */
      virtual void OnChangedViewList();
  
      /**
      */
      virtual void OnChangedViewList();
  
      /**
-        The default implementation calls DeleteContents (an empty implementation)
-        sets the modified flag to @false. Override this to
-        supply additional behaviour when the document is closed with Close.
+        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().
      */
      virtual bool OnCloseDocument();
  
      /**
      */
      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.
+        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.
      */
      virtual bool OnCreate(const wxString& path, long flags);
  
      /**
      */
      virtual bool OnCreate(const wxString& path, long flags);
  
      /**
-        Override this function if you want a different (or no) command processor
-        to be created when the document is created. By default, it returns
-        an instance of wxCommandProcessor.
-        See wxCommandProcessor.
+        Override this function if you want a different (or no) command
+        processor to be created when the document is created. By default, it
+        returns an instance of wxCommandProcessor.
+
+        @see wxCommandProcessor
      */
      virtual wxCommandProcessor* OnCreateCommandProcessor();
  
      /**
      */
      virtual wxCommandProcessor* OnCreateCommandProcessor();
  
      /**
-        The default implementation calls OnSaveModified and DeleteContents, makes a
-        default title for the
-        document, and notifies the views that the filename (in fact, the title) has
-        changed.
+        The default implementation calls OnSaveModified() and DeleteContents(),
+        makes a default title for the document, and notifies the views that the
+        filename (in fact, the title) has changed.
      */
      virtual bool OnNewDocument();
  
      /**
      */
      virtual bool OnNewDocument();
  
      /**
-        Constructs an input file stream for the given filename (which must not be
-        empty),
-        and calls LoadObject. If LoadObject returns @true, the document is set to
-        unmodified; otherwise, an error message box is displayed. The document's
-        views are notified that the filename has changed, to give windows an opportunity
-        to update their titles. All of the document's views are then updated.
+        Constructs an input file stream for the given filename (which must not
+        be empty), and calls LoadObject(). If LoadObject() returns @true, the
+        document is set to unmodified; otherwise, an error message box is
+        displayed. The document's views are notified that the filename has
+        changed, to give windows an opportunity to update their titles. All of
+        the document's views are then updated.
      */
      virtual bool OnOpenDocument(const wxString& filename);
  
      /**
      */
      virtual bool OnOpenDocument(const wxString& filename);
  
      /**
-        Constructs an output file stream for the given filename (which must not be
-        empty),
-        and calls SaveObject. If SaveObject returns @true, the document is set to
-        unmodified; otherwise, an error message box is displayed.
+        Constructs an output file stream for the given filename (which must not
+        be empty), and calls SaveObject(). If SaveObject() returns @true, the
+        document is set to unmodified; otherwise, an error message box is
+        displayed.
      */
      virtual bool OnSaveDocument(const wxString& filename);
  
      /**
      */
      virtual bool OnSaveDocument(const wxString& filename);
  
      /**
-        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 is called. If No, the
-        document is marked as unmodified and the function succeeds. If Cancel, the
-        function fails.
+        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
+        is called. If No, the document is marked as unmodified and the function
+        succeeds. If Cancel, the function fails.
      */
      virtual bool OnSaveModified();
  
      /**
      */
      virtual bool OnSaveModified();
  
      /**
-        Removes the view from the document's list of views, and calls OnChangedViewList.
+        Removes the view from the document's list of views, and calls
+        OnChangedViewList().
      */
      virtual bool RemoveView(wxView* view);
  
      /**
      */
      virtual bool RemoveView(wxView* view);
  
      /**
-        Saves the document by calling OnSaveDocument if there is an associated filename,
-        or SaveAs if there is no filename.
+        Saves the document by calling OnSaveDocument() if there is an
+        associated filename, or SaveAs() if there is no filename.
      */
      virtual bool Save();
  
      /**
      */
      virtual bool Save();
  
      /**
-        Prompts the user for a file to save to, and then calls OnSaveDocument.
+        Prompts the user for a file to save to, and then calls
+        OnSaveDocument().
      */
      virtual bool SaveAs();
  
      //@{
      /**
      */
      virtual bool SaveAs();
  
      //@{
      /**
-        Override this function and call it from your own SaveObject before
-        streaming your own data. SaveObject is called by the framework
+        Override this function and call it from your own SaveObject() before
+        streaming your own data. SaveObject() is called by the framework
          automatically when the document contents need to be saved.
          automatically when the document contents need to be saved.
-        Note that only one of these forms exists, depending on how wxWidgets
-        was configured.
+
+        @note This version of SaveObject() may not exist depending on how
+              wxWidgets was configured.
      */
      */
-    virtual ostream SaveObject(ostream& stream);
-    virtual wxOutputStream SaveObject(wxOutputStream& stream);
+    virtual ostream& SaveObject(ostream& stream);
+    virtual wxOutputStream& SaveObject(wxOutputStream& stream);
      //@}
  
      /**
      //@}
  
      /**
-        Sets the command processor to be used for this document. The document will then
-        be responsible
-        for its deletion. Normally you should not call this; override
-        OnCreateCommandProcessor
-        instead.
-        See wxCommandProcessor.
+        Sets the command processor to be used for this document. The document
+        will then be responsible for its deletion. Normally you should not call
+        this; override OnCreateCommandProcessor() instead.
+
+        @see wxCommandProcessor
      */
      virtual void SetCommandProcessor(wxCommandProcessor* processor);
  
      /**
          Sets the document type name for this document. See the comment for
      */
      virtual void SetCommandProcessor(wxCommandProcessor* processor);
  
      /**
          Sets the document type name for this document. See the comment for
-        documentTypeName.
+        @ref m_documentTypeName.
      */
      void SetDocumentName(const wxString& name);
  
      /**
      */
      void SetDocumentName(const wxString& name);
  
      /**
-        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);
  
      /**
          Sets the filename for this document. Usually called by the framework.
      */
      void SetDocumentTemplate(wxDocTemplate* templ);
  
      /**
          Sets the filename for this document. Usually called by the framework.
-        If @a notifyViews is @true, wxView::OnChangeFilename is called for all views.
+
+        If @a notifyViews is @true, wxView::OnChangeFilename() is called for
+        all views.
      */
      */
-    void SetFilename(const wxString& filename,
-                     bool notifyViews = false);
+    void SetFilename(const wxString& filename, bool notifyViews = false);
  
      /**
  
      /**
-        Sets the title for this document. The document title is used for an associated
-        frame (if any), and is usually constructed by the framework from
-        the filename.
+        Sets the title for this document. The document title is used for an
+        associated frame (if any), and is usually constructed by the framework
+        from the filename.
      */
      void SetTitle(const wxString& title);
  
      /**
      */
      void SetTitle(const wxString& title);
  
      /**
-        Updates all views. If @a sender is non-@NULL, does not update this view.
-        @a hint represents optional information to allow a view to optimize its update.
+        Updates all views. If @a sender is non-@NULL, does not update this
+        view. @a hint represents optional information to allow a view to
+        optimize its update.
      */
      void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL);
  
      */
      void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL);
  
+protected:
+    /**
+        This method is called by OnSaveDocument() to really save the document
+        contents to the specified file.
+
+        Base class version creates a file-based stream and calls SaveObject().
+        Override this if you need to do something else or prefer not to use
+        SaveObject() at all.
+     */
+    virtual bool DoSaveDocument(const wxString& file);
+
+    /**
+        This method is called by OnOpenDocument() to really load the document
+        contents from the specified file.
+
+        Base class version creates a file-based stream and calls LoadObject().
+        Override this if you need to do something else or prefer not to use
+        LoadObject() at all.
+     */
+    virtual bool DoOpenDocument(const wxString& file);
+
      /**
      /**
-        wxCommandProcessor* m_commandProcessor
          A pointer to the command processor associated with this document.
      */
          A pointer to the command processor associated with this document.
      */
-
+    wxCommandProcessor* m_commandProcessor;
  
      /**
  
      /**
-        wxString m_documentFile
          Filename associated with this document ("" if none).
      */
          Filename associated with this document ("" if none).
      */
-
+    wxString m_documentFile;
  
      /**
  
      /**
-        bool m_documentModified
          @true if the document has been modified, @false otherwise.
      */
          @true if the document has been modified, @false otherwise.
      */
-
+    bool m_documentModified;
  
      /**
  
      /**
-        wxDocTemplate * m_documentTemplate
          A pointer to the template from which this document was created.
      */
          A pointer to the template from which this document was created.
      */
-
+    wxDocTemplate* m_documentTemplate;
  
      /**
  
      /**
-        wxString m_documentTitle
-        Document title. The document title is used for an associated
-        frame (if any), and is usually constructed by the framework from
-        the filename.
+        Document title. The document title is used for an associated frame (if
+        any), and is usually constructed by the framework from the filename.
      */
      */
-
+    wxString m_documentTitle;
  
      /**
  
      /**
-        wxString m_documentTypeName
-        The document type name given to the wxDocTemplate constructor, copied to this
-        variable when the document is created. If several document templates are
-        created that use the same document type, this variable is used in
-        wxDocManager::CreateView
-        to collate a list of alternative view types that can be used on this kind of
-        document. Do not change the value of this variable.
+        The document type name given to the wxDocTemplate constructor, copied
+        to this variable when the document is created. If several document
+        templates are created that use the same document type, this variable is
+        used in wxDocManager::CreateView() to collate a list of alternative
+        view types that can be used on this kind of document. Do not change the
+        value of this variable.
      */
      */
-
+    wxString m_documentTypeName;
  
      /**
  
      /**
-        wxList m_documentViews
          List of wxView instances associated with this document.
      */
          List of wxView instances associated with this document.
      */
+    wxList m_documentViews;
  };
  
  
  };
  
  
+
  /**
      @class wxFileHistory
      @wxheader{docview.h}
  
  /**
      @class wxFileHistory
      @wxheader{docview.h}
  
-    The wxFileHistory encapsulates a user interface convenience, the
-    list of most recently visited files as shown on a menu (usually the File menu).
+    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
  
      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.
+    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}
  
      @library{wxcore}
-    @category{FIXME}
+    @category{docview}
  
  
-    @seealso
-    @ref overview_wxfilehistoryoverview "wxFileHistory overview", wxDocManager
+    @see @ref overview_docview, wxDocManager
  */
  class wxFileHistory : public wxObject
  {
  */
  class wxFileHistory : public wxObject
  {
@@ -1323,13 +1325,13 @@ public:
      /**
          Constructor. Pass the maximum number of files that should be stored and
          displayed.
      /**
          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
-        idBase (To one of your own defined IDs) when using more than one wxFileHistory
-        in your application.
+
+        @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);
+    wxFileHistory(size_t maxFiles = 9, wxWindowID idBase = wxID_FILE1);
  
      /**
          Destructor.
  
      /**
          Destructor.
@@ -1342,13 +1344,15 @@ public:
      */
      void AddFileToHistory(const wxString& filename);
  
      */
      void AddFileToHistory(const wxString& filename);
  
-    //@{
      /**
      /**
-        Appends the files in the history list, to the given menu only.
+        Appends the files in the history list, to all menus managed by the file
+        history object.
      */
      void AddFilesToMenu();
      */
      void AddFilesToMenu();
+    /**
+        Appends the files in the history list, to the given menu only.
+    */
      void AddFilesToMenu(wxMenu* menu);
      void AddFilesToMenu(wxMenu* menu);
-    //@}
  
      /**
          Returns the base identifier for the range used for appending items.
  
      /**
          Returns the base identifier for the range used for appending items.
@@ -1372,16 +1376,16 @@ public:
  
      /**
          Returns the list of menus that are managed by this file history object.
  
      /**
          Returns the list of menus that are managed by this file history object.
-        
+
          @see UseMenu()
      */
          @see UseMenu()
      */
-    const wxList GetMenus() const;
+    const wxList& GetMenus() const;
  
      /**
  
      /**
-        Loads the file history from the given config object. This function should be
-        called explicitly by the application.
-        
-        @see wxConfig
+        Loads the file history from the given config object. This function
+        should be called explicitly by the application.
+
+        @see wxConfigBase
      */
      void Load(wxConfigBase& config);
  
      */
      void Load(wxConfigBase& config);
  
@@ -1396,10 +1400,10 @@ public:
      void RemoveMenu(wxMenu* menu);
  
      /**
      void RemoveMenu(wxMenu* menu);
  
      /**
-        Saves the file history into the given config object. This must be called
-        explicitly by the application.
-        
-        @see wxConfig
+        Saves the file history into the given config object. This must be
+        called explicitly by the application.
+
+        @see wxConfigBase
      */
      void Save(wxConfigBase& config);
  
      */
      void Save(wxConfigBase& config);
  
@@ -1409,48 +1413,63 @@ public:
      void SetBaseId(wxWindowID baseId);
  
      /**
      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.
+        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);
  
      /**
      */
      void UseMenu(wxMenu* menu);
  
      /**
-        char** m_fileHistory
          A character array of strings corresponding to the most recently opened
          files.
      */
          A character array of strings corresponding to the most recently opened
          files.
      */
-
+    char** m_fileHistory;
  
      /**
  
      /**
-        size_t m_fileHistoryN
          The number of files stored in the history array.
      */
          The number of files stored in the history array.
      */
-
+    size_t m_fileHistoryN;
  
      /**
  
      /**
-        size_t m_fileMaxFiles
          The maximum number of files to be stored and displayed on the menu.
      */
          The maximum number of files to be stored and displayed on the menu.
      */
-
+    size_t m_fileMaxFiles;
  
      /**
  
      /**
-        wxMenu* m_fileMenu
          The file menu used to display the file history list (if enabled).
      */
          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 */
+//@{
+
  /**
  /**
-    Copies the given file to @e stream. Useful when converting an old application to
-    use streams (within the document/view framework, for example).
+    Copies the given file to @a stream. Useful when converting an old
+    application to use streams (within the document/view framework, for
+    example).
+
+    @header{wx/docview.h}
  */
  bool wxTransferFileToStream(const wxString& filename,
                              ostream& stream);
  
  */
  bool wxTransferFileToStream(const wxString& filename,
                              ostream& stream);
  
+/**
+    Copies the given stream to the file @a filename. Useful when converting an
+    old application to use streams (within the document/view framework, for
+    example).
+
+    @header{wx/docview.h}
+*/
+bool wxTransferStreamToFile(istream& stream,
+                             const wxString& filename);
+
+//@}
+