Document that message box with wxYES_NO but without wxCANCEL can't be closed.

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

diff --git a/interface/wx/docview.h b/interface/wx/docview.h
index 5b3ad6f83fb505f2f9b47d19886bf1ca605a5257..b39691807674740742b19e2a08692797c465b21c 100644 (file)
--- a/interface/wx/docview.h
+++ b/interface/wx/docview.h
@@ -60,14 +60,35 @@ public:
             - wxTEMPLATE_INVISIBLE     - The template may not be displayed to
                                          the user in dialogs.
             - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE.
             - wxTEMPLATE_INVISIBLE     - The template may not be displayed to
                                          the user in dialogs.
             - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE.

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

     */
     wxDocTemplate(wxDocManager* manager, const wxString& descr,
                   const wxString& filter, const wxString& dir,
                   const wxString& ext, const wxString& docTypeName,
     */
     wxDocTemplate(wxDocManager* manager, const wxString& descr,
                   const wxString& filter, const wxString& dir,
                   const wxString& ext, const wxString& docTypeName,

-                  const wxString& viewTypeName,
-                  wxClassInfo* docClassInfo = NULL,
-                  wxClassInfo* viewClassInfo = NULL,
-                  long flags = wxDEFAULT_TEMPLATE_FLAGS);
+                  const wxString& viewTypeName, wxClassInfo* docClassInfo = 0,
+                  wxClassInfo* viewClassInfo = 0,
+                  long flags = wxTEMPLATE_VISIBLE);

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -86,12 +107,27 @@ public:
     virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
 
     /**
     virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
 
     /**

-        Creates a new instance of the associated view class. If you have not
-        supplied a wxClassInfo parameter to the template constructor, you will
-        need to override this function to return an appropriate view instance.
+        Creates a new instance of the associated view class.
+
+        If you have not supplied a wxClassInfo parameter to the template
+        constructor, you will need to override this function to return an
+        appropriate view instance.
+
+        If the new view initialization fails, it must call
+        wxDocument::RemoveView() for consistency with the default behaviour of
+        this function.

     */
     virtual wxView* CreateView(wxDocument* doc, long flags = 0);
 
     */
     virtual wxView* CreateView(wxDocument* doc, long flags = 0);
 

+    /**
+        This function implements the default (very primitive) format detection
+        which checks if the extension is that of the template.
+
+        @param path
+            The path to be checked against the template.
+    */
+    virtual bool FileMatchesTemplate(const wxString& path);
+

     /**
         Returns the default file extension for the document data, as passed to
         the document template constructor.
     /**
         Returns the default file extension for the document data, as passed to
         the document template constructor.


@@ -110,6 +146,13 @@ public:
     */
     wxString GetDirectory() const;
 
     */
     wxString GetDirectory() const;
 

+    /**
+        Returns the run-time class information that allows document
+        instances to be constructed dynamically, as passed to the document
+        template constructor.
+    */
+    wxClassInfo* GetDocClassInfo() const;
+

     /**
         Returns a pointer to the document manager instance for which this
         template was created.
     /**
         Returns a pointer to the document manager instance for which this
         template was created.


@@ -133,6 +176,13 @@ public:
     */
     long GetFlags() const;
 
     */
     long GetFlags() const;
 

+    /**
+        Returns the run-time class information that allows view instances
+        to be constructed dynamically, as passed to the document template
+        constructor.
+    */
+    wxClassInfo* GetViewClassInfo() const;
+

     /**
         Returns the view type name, as passed to the document template
         constructor.
     /**
         Returns the view type name, as passed to the document template
         constructor.


@@ -140,10 +190,25 @@ public:
     virtual wxString GetViewName() const;
 
     /**
     virtual wxString GetViewName() const;
 
     /**

-        Initialises the document, calling wxDocument::OnCreate(). This is
-        called from CreateDocument().
+        Initialises the document, calling wxDocument::OnCreate().
+
+        This is called from CreateDocument().
+
+        If you override this method, notice that you must @em delete the @a doc
+        if its initialization fails for consistency with the default behaviour.
+
+        @param doc
+            The document to initialize.
+        @param path
+            The associated file path.
+        @param flags
+            Flags passed to CreateDocument().
+        @return
+            @true if the initialization was successful or @false if it failed
+            in which case @a doc should be deleted by this function.

     */
     */

-    virtual bool InitDocument(wxDocument* doc, const wxString& path,
+    virtual bool InitDocument(wxDocument* doc,
+                              const wxString& path,

                               long flags = 0);
 
     /**
                               long flags = 0);
 
     /**


@@ -341,12 +406,20 @@ public:
     */
     virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
 
     */
     virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
 

+    /**
+        Creates an empty new document.
+
+        This is equivalent to calling CreateDocument() with @c wxDOC_NEW flags
+        and without the file name.
+     */
+    wxDocument *CreateNewDocument();
+

     /**
         Creates a new view for the given document. If more than one view is
         allowed for the document (by virtue of multiple templates mentioning
         the same document type), a choice of view is presented to the user.
     */
     /**
         Creates a new view for the given document. If more than one view is
         allowed for the document (by virtue of multiple templates mentioning
         the same document type), a choice of view is presented to the user.
     */

-    wxView* CreateView(wxDocument* doc, long flags);
+    virtual wxView* CreateView(wxDocument* doc, long flags = 0);

 
     /**
         Removes the template from the list of templates.
 
     /**
         Removes the template from the list of templates.


@@ -415,7 +488,7 @@ public:
     /**
         Returns a reference to the list of documents.
     */
     /**
         Returns a reference to the list of documents.
     */

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

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


@@ -441,7 +514,7 @@ public:
     /**
         Returns a reference to the list of associated templates.
     */
     /**
         Returns a reference to the list of associated templates.
     */

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

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


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

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

     */
     */

-    wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates,
-                                      int noTemplates, wxString& path,
-                                      long flags, bool save);
+    virtual wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates,
+                                              int noTemplates, wxString& path,
+                                              long flags, bool save = false);

 
     /**
         Returns a document template by asking the user (if there is more than
 
     /**
         Returns a document template by asking the user (if there is more than


@@ -546,9 +629,14 @@ public:
             parameter indicates whether the list of templates that the user
             will have to choose from is sorted or not when shown the choice box
             dialog. Default is @false.
             parameter indicates whether the list of templates that the user
             will have to choose from is sorted or not when shown the choice box
             dialog. Default is @false.

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

     */
     */

-    wxDocTemplate* SelectDocumentType(wxDocTemplate** templates,
-                                      int noTemplates, bool sort = false);
+    virtual wxDocTemplate* SelectDocumentType(wxDocTemplate** templates,
+                                              int noTemplates,
+                                              bool sort = false);

 
     /**
         Returns a document template by asking the user (if there is more than
 
     /**
         Returns a document template by asking the user (if there is more than


@@ -567,9 +655,13 @@ public:
             parameter indicates whether the list of templates that the user
             will have to choose from is sorted or not when shown the choice box
             dialog. Default is @false.
             parameter indicates whether the list of templates that the user
             will have to choose from is sorted or not when shown the choice box
             dialog. Default is @false.

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

     */
     */

-    wxDocTemplate* SelectViewType(wxDocTemplate** templates,
-                                  int noTemplates, bool sort = false);
+    virtual wxDocTemplate* SelectViewType(wxDocTemplate** templates,
+                                          int noTemplates, bool sort = false);

 
     /**
         Sets the directory to be displayed to the user when opening a file.
 
     /**
         Sets the directory to be displayed to the user when opening a file.


@@ -709,8 +801,7 @@ public:
 
     /**
         Called when the filename has changed. The default implementation
 
     /**
         Called when the filename has changed. The default implementation

-        constructs a suitable title and sets the title of the view frame (if
-        any).
+        constructs a suitable title and sets the title of the view frame (if any).

     */
     virtual void OnChangeFilename();
 
     */
     virtual void OnChangeFilename();
 


@@ -758,7 +849,7 @@ public:
     /**
         Override this function to render the view on the given device context.
     */
     /**
         Override this function to render the view on the given device context.
     */

-    virtual void OnDraw(wxDC* dc);
+    virtual void OnDraw(wxDC* dc) = 0;

 
     /**
         Called when the view should be updated.
 
     /**
         Called when the view should be updated.


@@ -772,7 +863,7 @@ public:
             application-specific information for making updating more
             efficient.
     */
             application-specific information for making updating more
             efficient.
     */

-    virtual void OnUpdate(wxView* sender, wxObject* hint);
+    virtual void OnUpdate(wxView* sender, wxObject* hint = 0);

 
     /**
         Associates the given document with the view. Normally called by the
 
     /**
         Associates the given document with the view. Normally called by the


@@ -843,7 +934,7 @@ public:
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxDEFAULT_FRAME_STYLE,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxDEFAULT_FRAME_STYLE,

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

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -865,7 +956,7 @@ public:
         override (but still call) this function in order to set the keyboard
         focus for your subwindow.
     */
         override (but still call) this function in order to set the keyboard
         focus for your subwindow.
     */

-    void OnActivate(wxActivateEvent event);
+    void OnActivate(wxActivateEvent& event);

 
     /**
         Closes and deletes the current view and document.
 
     /**
         Closes and deletes the current view and document.


@@ -925,7 +1016,7 @@ public:
                      const wxPoint& pos = wxDefaultPosition,
                      const wxSize& size = wxDefaultSize,
                      long style = wxDEFAULT_FRAME_STYLE,
                      const wxPoint& pos = wxDefaultPosition,
                      const wxSize& size = wxDefaultSize,
                      long style = wxDEFAULT_FRAME_STYLE,

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

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -935,12 +1026,10 @@ public:
     /**
         Used in two-step construction.
     */
     /**
         Used in two-step construction.
     */

-    bool Create(wxDocManager* manager, wxFrame* parent,
-                wxWindowID id, const wxString& title,
-                const wxPoint& pos = wxDefaultPosition,
-                const wxSize& size = wxDefaultSize,
-                long style = wxDEFAULT_FRAME_STYLE,
-                const wxString& name = "frame");
+    bool Create(wxDocManager* manager, wxFrame* parent, wxWindowID id,
+                const wxString& title, const wxPoint& pos = wxDefaultPosition,
+                const wxSize& size = wxDefaultSize, long style = 541072960,
+                const wxString& name = wxFrameNameStr);

 
     /**
         Returns the associated document manager object.
 
     /**
         Returns the associated document manager object.


@@ -989,7 +1078,7 @@ public:
         Constructor. Define your own default constructor to initialize
         application-specific data.
     */
         Constructor. Define your own default constructor to initialize
         application-specific data.
     */

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

 
     /**
         Destructor. Removes itself from the document manager.
 
     /**
         Destructor. Removes itself from the document manager.


@@ -1002,6 +1091,22 @@ public:
     */
     virtual bool AddView(wxView* view);
 
     */
     virtual bool AddView(wxView* view);
 

+    /**
+        Returns true if the document hasn't been modified since the last time
+        it had been saved.
+
+        Notice that this function returns @false if the document had been never
+        saved at all, so it may be also used to test whether it makes sense to
+        save the document: if it returns @true, there is nothing to save but if
+        @false is returned, it can be saved, even if it might be not modified
+        (this can be used to create an empty document file by the user).
+
+        @see IsModified(), GetDocumentSaved()
+
+        @since 2.9.0
+     */
+    bool AlreadySaved() const;
+

     /**
         Closes the document, by calling OnSaveModified() and then (if this
         returned @true) OnCloseDocument(). This does not normally delete the
     /**
         Closes the document, by calling OnSaveModified() and then (if this
         returned @true) OnCloseDocument(). This does not normally delete the


@@ -1037,6 +1142,13 @@ public:
     */
     wxString GetDocumentName() const;
 
     */
     wxString GetDocumentName() const;
 

+    /**
+        Return true if this document had been already saved.
+
+        @see IsModified()
+     */
+    bool GetDocumentSaved() const;
+

     /**
         Gets a pointer to the template that created the document.
     */
     /**
         Gets a pointer to the template that created the document.
     */


@@ -1077,12 +1189,15 @@ public:
     */
     virtual wxString GetUserReadableName() const;
 
     */
     virtual wxString GetUserReadableName() const;
 

+    //@{

     /**
         Returns the list whose elements are the views on the document.
 
         @see GetFirstView()
     */
     /**
         Returns the list whose elements are the views on the document.
 
         @see GetFirstView()
     */

-    wxList GetViews() const;
+    wxList& GetViews();
+    const wxList& GetViews() const;
+    //@}

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


@@ -1138,9 +1253,22 @@ public:
 
     /**
         Called just after the document object is created to give it a chance to
 
     /**
         Called just after the document object is created to give it a chance to

-        initialize itself. The default implementation uses the template
-        associated with the document to create an initial view. If this
-        function returns @false, the document is deleted.
+        initialize itself.
+
+        The default implementation uses the template associated with the
+        document to create an initial view.
+
+        For compatibility reasons, this method may either delete the document
+        itself if its initialization fails or not do it in which case it is
+        deleted by caller. It is recommended to delete the document explicitly
+        in this function if it can't be initialized.
+
+        @param path
+            The associated file path.
+        @param flags
+            Flags passed to CreateDocument().
+        @return
+            @true if the initialization was successful or @false if it failed.

     */
     virtual bool OnCreate(const wxString& path, long flags);
 
     */
     virtual bool OnCreate(const wxString& path, long flags);
 


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

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

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


@@ -1238,13 +1366,36 @@ public:
     */
     virtual void SetDocumentTemplate(wxDocTemplate* templ);
 
     */
     virtual void SetDocumentTemplate(wxDocTemplate* templ);
 

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

     /**
         Sets the filename for this document. Usually called by the framework.
 
     /**
         Sets the filename for this document. Usually called by the framework.
 

+        Calls OnChangeFilename() which in turn calls wxView::OnChangeFilename() for
+        all views if @a notifyViews is @true.
+    */
+    void SetFilename(const wxString& filename, bool notifyViews = false);
+
+    /**

         If @a notifyViews is @true, wxView::OnChangeFilename() is called for
         all views.
         If @a notifyViews is @true, wxView::OnChangeFilename() is called for
         all views.

+
+        @since 2.9.0

     */
     */

-    void SetFilename(const wxString& filename, bool notifyViews = false);
+    virtual void OnChangeFilename(bool notifyViews);

 
     /**
         Sets the title for this document. The document title is used for an
 
     /**
         Sets the title for this document. The document title is used for an


@@ -1440,27 +1591,6 @@ public:
         called, as this is not done automatically.
     */
     virtual void UseMenu(wxMenu* menu);
         called, as this is not done automatically.
     */
     virtual void UseMenu(wxMenu* menu);

-
-    /**
-        A character array of strings corresponding to the most recently opened
-        files.
-    */
-    char** m_fileHistory;
-
-    /**
-        The number of files stored in the history array.
-    */
-    size_t m_fileHistoryN;
-
-    /**
-        The maximum number of files to be stored and displayed on the menu.
-    */
-    size_t m_fileMaxFiles;
-
-    /**
-        The file menu used to display the file history list (if enabled).
-    */
-    wxMenu* m_fileMenu;

 };
 
 
 };
 
 


@@ -1469,7 +1599,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

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

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