even more interface fixes

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

diff --git a/interface/wx/docview.h b/interface/wx/docview.h
index a0788b0a26f1960a29baa610db4936c8e2b0c70b..5b3ad6f83fb505f2f9b47d19886bf1ca605a5257 100644 (file)
--- a/interface/wx/docview.h
+++ b/interface/wx/docview.h
@@ -72,7 +72,7 @@ public:
     /**
         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 +83,74 @@ 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.
     */

-    wxView* CreateView(wxDocument* doc, long flags = 0);
+    virtual 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() 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 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 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().
     */

-    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.


@@ -258,26 +259,28 @@ 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.
-

         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.

+
+        @param flags
+            Currently unused.
+        @param initialize
+            Indicates whether Initialize() should be called by this ctor.

     */
     */

-    wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS,
-                 bool initialize = true);
+    wxDocManager(long flags = 0, bool initialize = true);

 
     /**
         Destructor.
     */
 
     /**
         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.


@@ -288,7 +291,7 @@ 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.
 
     /**
         Adds the template to the document manager's template list.


@@ -301,25 +304,42 @@ 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.
+
+        This function can either create a document corresponding to a new
+        file or to an already existing one depending on whether @c wxDOC_NEW is
+        specified in the @a flags.
+
+        By default, this function asks the user for the type of document to
+        open and the path to its file if it's not specified, i.e. if @a path is
+        empty. Specifying @c wxDOC_SILENT flag suppresses any prompts and means
+        that the @a path must be non-empty and there must be a registered
+        document template handling the extension of this file, otherwise a
+        warning message is logged and the function returns @NULL. Notice that
+        @c wxDOC_SILENT can be combined with @c wxDOC_NEW, however in this case
+        the @a path must still be specified, even if the file with this path
+        typically won't exist.
+
+        Finally notice that if this document manager was configured to allow
+        only a limited number of simultaneously opened documents using
+        SetMaxDocsOpen(), this function will try to close the oldest existing
+        document if this number was reached before creating a new document.
+        And if closing the old document fails (e.g. because it was vetoed by
+        user), this function fails as well.
+
+        @param path
+            Path to a file or an empty string. If the path is empty, the user
+            will be asked to select it (thus, this is incompatible with the use
+            of @c wxDOC_SILENT). The file should exist unless @a flags includes
+            @c wxDOC_NEW.
+        @param flags
+            By default, none. May include @c wxDOC_NEW to indicate that the new
+            document corresponds to a new file and not an existing one and
+            @c wxDOC_SILENT to suppress any dialogs asking the user about the
+            file path and type.
+        @return a new document object or @NULL on failure.

     */
     */

-    wxDocument* CreateDocument(const wxString& path, long flags);
+    virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);

 
     /**
         Creates a new view for the given document. If more than one view is
 
     /**
         Creates a new view for the given document. If more than one view is


@@ -337,24 +357,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


@@ -362,7 +382,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


@@ -372,25 +392,25 @@ 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.


@@ -400,12 +420,12 @@ public:
     /**
         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.


@@ -416,7 +436,7 @@ 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.


@@ -439,7 +459,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.


@@ -447,13 +467,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.


@@ -559,11 +579,12 @@ public:
 
     /**
         Sets the maximum number of documents that can be open at a time. By
 
     /**
         Sets the maximum number of documents that can be open at a time. By

-        default, this is 10,000. If you set it to 1, existing documents will be
-        saved and deleted when the user tries to open or create a new one
-        (similar to the behaviour of Windows Write, for example). Allowing
-        multiple documents gives behaviour more akin to MS Word and other
-        Multiple Document Interface applications.
+        default, this is @c INT_MAX, i.e. the number of documents is unlimited.
+        If you set it to 1, existing documents will be saved and deleted when
+        the user tries to open or create a new one (similar to the behaviour of
+        Windows Write, for example). Allowing multiple documents gives
+        behaviour more akin to MS Word and other Multiple Document Interface
+        applications.

     */
     void SetMaxDocsOpen(int n);
 
     */
     void SetMaxDocsOpen(int n);
 


@@ -632,7 +653,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


@@ -671,7 +692,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


@@ -757,7 +778,7 @@ public:
         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


@@ -827,7 +848,7 @@ public:
     /**
         Destructor.
     */
     /**
         Destructor.
     */

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

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


@@ -909,7 +930,7 @@ public:
     /**
         Destructor.
     */
     /**
         Destructor.
     */

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

 
     /**
         Used in two-step construction.
 
     /**
         Used in two-step construction.


@@ -973,7 +994,7 @@ public:
     /**
         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


@@ -1003,12 +1024,12 @@ public:
 
         @see wxCommandProcessor
     */
 
         @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


@@ -1019,14 +1040,14 @@ public:
     /**
         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


@@ -1102,9 +1123,16 @@ public:
     virtual void OnChangedViewList();
 
     /**
     virtual void OnChangedViewList();
 
     /**

+        This virtual function is called when the document is being closed.
+

         The default implementation calls DeleteContents() (an empty
         The default implementation calls DeleteContents() (an empty

-        implementation) and sets the modified flag to @false. Override this to
-        supply additional behaviour when the document is closed with Close().
+        implementation) and sets the modified flag to @false. You can override
+        it to supply additional behaviour when the document is closed with
+        Close().
+
+        Notice that previous wxWidgets versions used to call this function also
+        from OnNewDocument(), rather counter-intuitively. This is no longer the
+        case since wxWidgets 2.9.0.

     */
     virtual bool OnCloseDocument();
 
     */
     virtual bool OnCloseDocument();
 


@@ -1208,7 +1236,7 @@ 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 the filename for this document. Usually called by the framework.
 
     /**
         Sets the filename for this document. Usually called by the framework.


@@ -1230,7 +1258,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:
     /**


@@ -1329,23 +1357,23 @@ public:
     /**
         Destructor.
     */
     /**
         Destructor.
     */

-    ~wxFileHistory();
+    virtual ~wxFileHistory();

 
     /**
         Adds a file to the file history list, if the object has a pointer to an
         appropriate file menu.
     */
 
     /**
         Adds a file to the file history list, if the object has a pointer to an
         appropriate file menu.
     */

-    void AddFileToHistory(const wxString& filename);
+    virtual void AddFileToHistory(const wxString& filename);

 
     /**
         Appends the files in the history list, to all menus managed by the file
         history object.
     */
 
     /**
         Appends the files in the history list, to all menus managed by the file
         history object.
     */

-    void AddFilesToMenu();
+    virtual void AddFilesToMenu();

     /**
         Appends the files in the history list, to the given menu only.
     */
     /**
         Appends the files in the history list, to the given menu only.
     */

-    void AddFilesToMenu(wxMenu* menu);
+    virtual void AddFilesToMenu(wxMenu* menu);

 
     /**
         Returns the base identifier for the range used for appending items.
 
     /**
         Returns the base identifier for the range used for appending items.


@@ -1355,17 +1383,17 @@ public:
     /**
         Returns the number of files currently stored in the file history.
     */
     /**
         Returns the number of files currently stored in the file history.
     */

-    size_t GetCount() const;
+    virtual size_t GetCount() const;

 
     /**
         Returns the file at this index (zero-based).
     */
 
     /**
         Returns the file at this index (zero-based).
     */

-    wxString GetHistoryFile(size_t index) const;
+    virtual wxString GetHistoryFile(size_t index) const;

 
     /**
         Returns the maximum number of files that can be stored.
     */
 
     /**
         Returns the maximum number of files that can be stored.
     */

-    int GetMaxFiles() const;
+    virtual int GetMaxFiles() const;

 
     /**
         Returns the list of menus that are managed by this file history object.
 
     /**
         Returns the list of menus that are managed by this file history object.


@@ -1380,17 +1408,17 @@ public:
 
         @see wxConfigBase
     */
 
         @see wxConfigBase
     */

-    void Load(const wxConfigBase& config);
+    virtual void Load(const wxConfigBase& config);

 
     /**
         Removes the specified file from the history.
     */
 
     /**
         Removes the specified file from the history.
     */

-    void RemoveFileFromHistory(size_t i);
+    virtual void RemoveFileFromHistory(size_t i);

 
     /**
         Removes this menu from the list of those managed by this object.
     */
 
     /**
         Removes this menu from the list of those managed by this object.
     */

-    void RemoveMenu(wxMenu* menu);
+    virtual void RemoveMenu(wxMenu* menu);

 
     /**
         Saves the file history into the given config object. This must be
 
     /**
         Saves the file history into the given config object. This must be


@@ -1398,7 +1426,7 @@ public:
 
         @see wxConfigBase
     */
 
         @see wxConfigBase
     */

-    void Save(wxConfigBase& config);
+    virtual void Save(wxConfigBase& config);

 
     /**
         Sets the base identifier for the range used for appending items.
 
     /**
         Sets the base identifier for the range used for appending items.


@@ -1411,7 +1439,7 @@ public:
         with filenames that are already in the history when this function is
         called, as this is not done automatically.
     */
         with filenames that are already in the history when this function is
         called, as this is not done automatically.
     */

-    void UseMenu(wxMenu* menu);
+    virtual void UseMenu(wxMenu* menu);

 
     /**
         A character array of strings corresponding to the most recently opened
 
     /**
         A character array of strings corresponding to the most recently opened