X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..58f1fdc926e4fc0f0b8ca49384d72e51bea2e86b:/docs/latex/wx/tdocview.tex

diff --git a/docs/latex/wx/tdocview.tex b/docs/latex/wx/tdocview.tex
index 08d9cd7bf6..e99749ebcb 100644
--- a/docs/latex/wx/tdocview.tex
+++ b/docs/latex/wx/tdocview.tex
@@ -1,7 +1,19 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        tdocview.tex
+%% Purpose:     Document/view overview
+%% Author:      wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) wxWidgets Team
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \section{Document/view overview}\label{docviewoverview}
 
 Classes: \helpref{wxDocument}{wxdocument}, \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate},\rtfsp
 \helpref{wxDocManager}{wxdocmanager}, \helpref{wxDocParentFrame}{wxdocparentframe}, \helpref{wxDocChildFrame}{wxdocchildframe},
+\rtfsp\helpref{wxDocMDIParentFrame}{wxdocmdiparentframe}, \helpref{wxDocMDIChildFrame}{wxdocmdichildframe},
 \rtfsp\helpref{wxCommand}{wxcommand}, \helpref{wxCommandProcessor}{wxcommandprocessor}
 
 The document/view framework is found in most application frameworks, because it
@@ -27,15 +39,14 @@ These are the overall steps involved in creating an application based on the doc
 \item Define your own document and view classes, overriding a minimal set of
 member functions e.g. for input/output, drawing and initialization.
 \item Define any subwindows
-(such as a canvas) that are needed for the view(s). You may need to route some events
+(such as a scrolled window) that are needed for the view(s). You may need to route some events
 to views or documents, for example OnPaint needs to be routed to wxView::OnDraw.
 \item Decide what style of interface you will use: Microsoft's MDI (multiple
 document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
 for each document), or single-window (one document open at a time, as in Windows Write).
 \item Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
 of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
-you initialize a view. Create menus using standard menu ids (such as wxID\_OPEN, wxID\_PRINT),
-routing non-application-specific identifiers to the base frame's OnMenuCommand.
+you initialize a view. Create menus using standard menu ids (such as wxID\_OPEN, wxID\_PRINT).
 \item Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
 as many wxDocTemplate instances as necessary to define relationships between documents and
 views. For a simple application, there will be just one wxDocTemplate.
@@ -59,7 +70,16 @@ class, to provide multi-page document facilities.
 \end{itemize}
 
 Note that to activate framework functionality, you need to use some or all of
-the wxWindows \helpref{predefined command identifiers}{predefinedids} in your menus.
+the wxWidgets \helpref{predefined command identifiers}{predefinedids} in your menus.
+
+\perlnote{The document/view framework is available in wxPerl. To use it,
+you will need the following statements in your application code:\par
+{\small
+\begin{verbatim}
+use Wx::DocView;
+use Wx ':docview';   # import constants (optional)
+\end{verbatim}
+}}
 
 \subsection{wxDocument overview}\label{wxdocumentoverview}
 
@@ -68,7 +88,7 @@ the wxWindows \helpref{predefined command identifiers}{predefinedids} in your me
 Class: \helpref{wxDocument}{wxdocument}
 
 The wxDocument class can be used to model an application's file-based
-data. It is part of the document/view framework supported by wxWindows,
+data. It is part of the document/view framework supported by wxWidgets,
 and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}\rtfsp
 and \helpref{wxDocManager}{wxdocmanager} classes.
 
@@ -97,7 +117,7 @@ a \helpref{wxDocTemplate}{wxdoctemplate} object on application initialization, y
 should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
 so that it knows how to create an instance of this class.
 
-If you do not wish to use the wxWindows method of creating document
+If you do not wish to use the wxWidgets method of creating document
 objects dynamically, you must override wxDocTemplate::CreateDocument
 to return an instance of the appropriate class.
 
@@ -108,16 +128,15 @@ to return an instance of the appropriate class.
 Class: \helpref{wxView}{wxview}
 
 The wxView 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 wxWindows,
+an application's file-based data. It is part of the document/view framework supported by wxWidgets,
 and cooperates with the \helpref{wxDocument}{wxdocument}, \helpref{wxDocTemplate}{wxdoctemplate}
 and \helpref{wxDocManager}{wxdocmanager} classes.
 
 See the example application in {\tt samples/docview}.
 
 To use the abstract wxView class, you need to derive a new class and override
-at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You'll probably
-want to override OnMenuCommand to respond to menu commands from the frame containing the
-view.
+at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You will probably
+want to respond to menu commands from the frame containing the view.
 
 Use the macros DECLARE\_DYNAMIC\_CLASS and IMPLEMENT\_DYNAMIC\_CLASS in order
 to allow the framework to create view objects on demand. When you create
@@ -125,7 +144,7 @@ a \helpref{wxDocTemplate}{wxdoctemplate} object on application initialization, y
 should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
 so that it knows how to create an instance of this class.
 
-If you do not wish to use the wxWindows method of creating view
+If you do not wish to use the wxWidgets method of creating view
 objects dynamically, you must override wxDocTemplate::CreateView
 to return an instance of the appropriate class.
 
@@ -154,15 +173,13 @@ the user clicks on the Open menu item, the file selector is displayed
 with a list of possible file filters -- one for each wxDocTemplate. Selecting
 the filter selects the wxDocTemplate, and when
 a file is selected, that template will be used for creating a document
-and view. Under non-Windows platforms, the user will be prompted for
-a list of templates before the file selector is shown, since most file selectors
-do not allow a choice of file filters.
+and view.
 
 For the case where an application has one document type and one view type,
 a single document template is constructed, and dialogs will be appropriately
 simplified.
 
-wxDocTemplate is part of the document/view framework supported by wxWindows,
+wxDocTemplate is part of the document/view framework supported by wxWidgets,
 and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}
 and \helpref{wxDocManager}{wxdocmanager} classes.
 
@@ -171,12 +188,11 @@ See the example application in {\tt samples/docview}.
 To use the wxDocTemplate class, you do not need to derive a new class.
 Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass) and
 CLASSINFO(YourViewClass) to allow dynamic instance creation.
-If you do not wish to use the wxWindows method of creating document
+If you do not wish to use the wxWidgets method of creating document
 objects dynamically, you must override wxDocTemplate::CreateDocument
 and wxDocTemplate::CreateView to return instances of the appropriate class.
 
-{\it NOTE}: the document template has nothing to do with the C++ template construct. C++
-templates are not used anywhere in wxWindows.
+{\it NOTE}: the document template has nothing to do with the C++ template construct.
 
 \subsection{wxDocManager overview}\label{wxdocmanageroverview}
 
@@ -184,11 +200,11 @@ templates are not used anywhere in wxWindows.
 
 Class: \helpref{wxDocManager}{wxdocmanager}
 
-The wxDocManager class is part of the document/view framework supported by wxWindows,
+The wxDocManager class is part of the document/view framework supported by wxWidgets,
 and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}\rtfsp
 and \helpref{wxDocTemplate}{wxdoctemplate} classes.
 
-A wxDocManager instance coordinates documents, views and document templates. It keeps a list of document and
+A wxDocManager instance coordinates documents, views and document templates. It keeps a list of document
 and template instances, and much functionality is routed through this object, such
 as providing selection and file dialogs. The application can use this class `as is' or
 derive a class and override some members to extend or change the functionality.
@@ -218,7 +234,7 @@ When a user interface event occurs, the application {\it submits} a command
 to a \helpref{wxCommandProcessor}{wxcommandprocessoroverview} object to execute and
 store.
 
-The wxWindows document/view framework handles Undo and Redo by use of
+The wxWidgets document/view framework handles Undo and Redo by use of
 wxCommand and wxCommandProcessor objects. You might find further uses
 for wxCommand, such as implementing a macro facility that stores, loads
 and replays commands.
@@ -249,55 +265,47 @@ Although wxFileHistory is used by wxDocManager, it can be used independently. Yo
 to derive from it to allow different behaviour, such as popping up a scrolling
 list of files.
 
-By calling wxFileHistory::FileHistoryUseMenu you can associate a file menu with
-the file history, that will be used for appending the filenames. They are
-appended using menu identifiers in the range wxID\_FILE1 to wxID\_FILE9.
+By calling \helpref{wxFileHistory::UseMenu()}{wxfilehistoryusemenu} you can
+associate a file menu with the file history. The menu will then be used for
+appending filenames that are added to the history. Please notice that currently
+if the history already contained filenames when UseMenu() is called (e.g. when
+initializing a second MDI child frame), the menu is not automatically
+initialized with the existing filenames in the history and so you need to call
+\helpref{AddFilesToMenu()}{wxfilehistoryaddfilestomenu} after UseMenu()
+explicitly in order to initialize the menu with the existing list of MRU files.
+(otherwise an assertion failure is raised in debug builds).
+The filenames are appended using menu identifiers in the range
+\texttt{wxID\_FILE1} to \texttt{wxID\_FILE9}.
 
 In order to respond to a file load command from one of these identifiers,
-you need to handle them in your wxFrame::OnMenuCommand. Below is the
-code used by the default document/view parent frame.
+you need to handle them using an event handler, for example:
 
+{\small
 \begin{verbatim}
-void wxDocParentFrame::OnMenuCommand(int id)
+BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
+    EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)
+    EVT_MENU_RANGE(wxID_FILE1, wxID_FILE9, wxDocParentFrame::OnMRUFile)
+END_EVENT_TABLE()
+
+void wxDocParentFrame::OnExit(wxCommandEvent& WXUNUSED(event))
 {
-  switch (id)
-  {
-    case wxID_EXIT:
-    {
-      if (GetEventHandler()->OnClose())
-        delete this;
-      break;
-    }
-    case wxID_FILE1:
-    case wxID_FILE2:
-    case wxID_FILE3:
-    case wxID_FILE4:
-    case wxID_FILE5:
-    case wxID_FILE6:
-    case wxID_FILE7:
-    case wxID_FILE8:
-    case wxID_FILE9:
-    {
-      char *f = docManager->GetHistoryFile(id-wxID_FILE1);
-      if (f)
-        (void)docManager->CreateDocument(f, wxDOC_SILENT);
-      break;
-    }
-    default:
-    {
-      docManager->OnMenuCommand(id);
-    }
-  }
+    Close();
+}
+
+void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
+{
+      wxString f(m_docManager->GetHistoryFile(event.GetId() - wxID_FILE1));
+      if (!f.empty())
+        (void)m_docManager->CreateDocument(f, wxDOC_SILENT);
 }
 \end{verbatim}
+}
 
-\subsection{wxWindows predefined command identifiers}\label{predefinedids}
+\subsection{wxWidgets predefined command identifiers}\label{predefinedids}
 
 To allow communication between the application's menus and the
 document/view framework, several command identifiers are predefined for you
-to use in menus. The framework recognizes them and processes them if you
-forward commands from wxFrame::OnMenuCommand (or perhaps from toolbars and
-other user interface constructs).
+to use in menus.
 
 \begin{itemize}\itemsep=0pt
 \item wxID\_OPEN (5000)
@@ -314,5 +322,3 @@ other user interface constructs).
 \item wxID\_PRINT\_SETUP (5011)
 \item wxID\_PREVIEW (5012)
 \end{itemize}
-
-