Add @onlyfor tag to wxToolBar::SetBitmapResource() documentation.

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

diff --git a/interface/wx/docview.h b/interface/wx/docview.h
index 360c40e25897be14c02e25c910614b44ae83f978..848c987dea0f954a4969657316c2aa1115d41e28 100644 (file)
--- a/interface/wx/docview.h
+++ b/interface/wx/docview.h
@@ -176,6 +176,15 @@ public:
     */
     long GetFlags() const;
 
     */
     long GetFlags() const;
 

+    /**
+        Returns a reference to the wxPageSetupDialogData associated with the
+        printing operations of this document manager.
+    */
+    //@{
+    wxPageSetupDialogData& GetPageSetupDialogData();
+    const wxPageSetupDialogData& GetPageSetupDialogData() const;
+    //@}
+

     /**
         Returns the run-time class information that allows view instances
         to be constructed dynamically, as passed to the document template
     /**
         Returns the run-time class information that allows view instances
         to be constructed dynamically, as passed to the document template


@@ -363,6 +372,27 @@ public:
     */
     void AssociateTemplate(wxDocTemplate* temp);
 
     */
     void AssociateTemplate(wxDocTemplate* temp);
 

+    /**
+        Search for a particular document template.
+
+        Example:
+        @code
+           // creating a document instance of the specified document type:
+           m_doc = (MyDoc*)docManager->FindTemplate(CLASSINFO(MyDoc))->
+                        CreateDocument(wxEmptyString, wxDOC_SILENT);
+        @endcode
+
+        @param classinfo
+            Class info of a document class for which a wxDocTemplate had been
+            previously created.
+
+        @return
+            Pointer to a wxDocTemplate, or @NULL if none found.
+
+        @since 2.9.2
+     */
+    wxDocTemplate* FindTemplate(const wxClassInfo* classinfo);
+

     /**
         Closes the specified document.
 
     /**
         Closes the specified document.
 


@@ -535,24 +565,6 @@ public:
     */
     wxList& GetTemplates();
 
     */
     wxList& GetTemplates();
 

-    /**
-        Create the frame used for print preview.
-
-        This method can be overridden if you need to change the behaviour or
-        appearance of the preview window. By default, a standard wxPreviewFrame
-        is created.
-
-        @since 2.9.1
-
-        @param preview The associated preview object.
-        @param parent The parent window for the frame.
-        @param title The suggested title for the print preview frame.
-        @return A new print preview frame, must not return @NULL.
-    */
-    virtual wxPreviewFrame* CreatePreviewFrame(wxPrintPreviewBase* preview,
-                                               wxWindow* parent,
-                                               const wxString& title);
-

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


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

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

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


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

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

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


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

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

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


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

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

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

-    wxFileHistory* m_fileHistory;
+    wxString m_lastDirectory;

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

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

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


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

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

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


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

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

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


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

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

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


@@ -1072,26 +1131,6 @@ public:
         Returns the associated document manager object.
     */
     wxDocManager* GetDocumentManager() const;
         Returns the associated document manager object.
     */
     wxDocManager* GetDocumentManager() const;

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

 };
 
 
 };
 
 


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

+

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

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

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


@@ -1114,8 +1169,14 @@ public:
     /**
         Constructor. Define your own default constructor to initialize
         application-specific data.
     /**
         Constructor. Define your own default constructor to initialize
         application-specific data.

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

     */
     */

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

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


@@ -1248,6 +1309,18 @@ public:
     const wxList& GetViews() const;
     //@}
 
     const wxList& GetViews() const;
     //@}
 

+    /**
+        Returns true if this document is a child document corresponding to a
+        part of the parent document and not a disk file as usual.
+
+        This method can be used to check whether file-related operations make
+        sense for this document as they only apply to top-level documents and
+        not child ones.
+
+        @since 2.9.2
+     */
+    bool IsChildDocument() const;
+

     /**
         Returns @true if the document has been modified since the last save,
         @false otherwise. You may need to override this if your document view
     /**
         Returns @true if the document has been modified since the last save,
         @false otherwise. You may need to override this if your document view