X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/fe604ccddcf5696a751892ad70dbc822be239c95..1f65137f8de90aba96242d5e44b00dfd0efa4b67:/docs/latex/wx/tdocview.tex diff --git a/docs/latex/wx/tdocview.tex b/docs/latex/wx/tdocview.tex index 8b147fa176..e91f08e839 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 @@ -34,8 +46,7 @@ document child frames surrounded by an overall frame), SDI (a separate, unconstr 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) @@ -315,4 +323,3 @@ other user interface constructs). \item wxID\_PREVIEW (5012) \end{itemize} -