X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1ecc323f2609c8afea31948b9eac2d965cc84f5e..bf2c43c76e2819be443ab1d830ab68d9569d66b1:/interface/wx/docview.h diff --git a/interface/wx/docview.h b/interface/wx/docview.h index 1b2c9f9788..af3d47d930 100644 --- a/interface/wx/docview.h +++ b/interface/wx/docview.h @@ -2,10 +2,30 @@ // Name: docview.h // Purpose: interface of various doc/view framework classes // Author: wxWidgets team -// RCS-ID: $Id$ // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/** + A vector of wxDocument pointers. + + @since 2.9.5 +*/ +typedef wxVector wxDocVector; + +/** + A vector of wxView pointers. + + @since 2.9.5 +*/ +typedef wxVector wxViewVector; + +/** + A vector of wxDocTemplate pointers. + + @since 2.9.5 +*/ +typedef wxVector wxDocTemplateVector; + /** @class wxDocTemplate @@ -393,6 +413,19 @@ public: */ wxDocTemplate* FindTemplate(const wxClassInfo* classinfo); + + /** + Search for the document corresponding to the given file. + + @param path + Document file path. + @return + Pointer to a wxDocument, or @NULL if none found. + + @since 2.9.5 + */ + wxDocument* FindDocumentByPath(const wxString& path) const; + /** Closes the specified document. @@ -523,6 +556,18 @@ public: */ virtual wxDocTemplate* FindTemplateForPath(const wxString& path); + /** + Returns the view to apply a user command to. + + This method tries to find the view that the user wants to interact + with. It returns the same view as GetCurrentDocument() if there is any + currently active view but falls back to the first view of the first + document if there is no active view. + + @since 2.9.5 + */ + wxView* GetAnyUsableView() const; + /** Returns the document associated with the currently active view (if any). @@ -530,10 +575,28 @@ public: wxDocument* GetCurrentDocument() const; /** - Returns the currently active view + Returns the currently active view. + + This method can return @NULL if no view is currently active. + + @see GetAnyUsableView() */ virtual wxView* GetCurrentView() const; + /** + Returns a vector of wxDocument pointers. + + @since 2.9.5 + */ + wxDocVector GetDocumentsVector() const; + + /** + Returns a vector of wxDocTemplate pointers. + + @since 2.9.5 + */ + wxDocTemplateVector GetTemplatesVector() const; + /** Returns a reference to the list of documents. */ @@ -565,24 +628,6 @@ public: */ 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(). @@ -749,6 +794,53 @@ public: 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. */ @@ -984,6 +1076,13 @@ public: 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} @@ -1017,18 +1116,6 @@ public: */ 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. */ @@ -1062,6 +1149,12 @@ public: 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} @@ -1101,26 +1194,6 @@ public: 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); }; @@ -1195,6 +1268,29 @@ public: */ bool AlreadySaved() const; + /** + Activate the first view of the document if any. + + This function simply calls the Raise() method of the frame of the first + view. You may need to override the Raise() method to get the desired + effect if you are not using a standard wxFrame for your view. For + instance, if your document is inside its own notebook tab you could + implement Raise() like this: + + @code + void MyNotebookPage::Raise() + { + wxNotebook* notebook = wxStaticCast(GetParent(), wxNotebook); + notebook->SetSelection(notebook->FindPage(this)); + } + @endcode + + @see GetFirstView() + + @since 2.9.5 + */ + void Activate() const; + /** Closes the document, by calling OnSaveModified() and then (if this returned @true) OnCloseDocument(). This does not normally delete the @@ -1289,6 +1385,13 @@ public: */ virtual wxString GetUserReadableName() const; + /** + Returns a vector of wxView pointers. + + @since 2.9.5 + */ + wxViewVector GetViewsVector() const; + //@{ /** Returns the list whose elements are the views on the document.