]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/tdocview.tex
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / docs / latex / wx / tdocview.tex
... / ...
CommitLineData
1\section{Document/view overview}\label{docviewoverview}
2
3Classes: \helpref{wxDocument}{wxdocument}, \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate},\rtfsp
4\helpref{wxDocManager}{wxdocmanager}, \helpref{wxDocParentFrame}{wxdocparentframe}, \helpref{wxDocChildFrame}{wxdocchildframe},
5\rtfsp\helpref{wxDocMDIParentFrame}{wxdocmdiparentframe}, \helpref{wxDocMDIChildFrame}{wxdocmdichildframe},
6\rtfsp\helpref{wxCommand}{wxcommand}, \helpref{wxCommandProcessor}{wxcommandprocessor}
7
8The document/view framework is found in most application frameworks, because it
9can dramatically simplify the code required to build many kinds of application.
10
11The idea is that you can model your application primarily in terms of {\it documents} to store data
12and provide interface-independent operations upon it, and {\it views} to visualise and manipulate
13the data. Documents know how to do input and output given stream objects, and views are responsible
14for taking input from physical windows and performing the manipulation on the document data.
15If a document's data changes, all views should be updated to reflect the change.
16
17The framework can provide many user-interface elements based on this model. Once you have defined
18your own classes and the relationships between them, the framework takes care
19of popping up file selectors, opening and closing files, asking the user to save
20modifications, routing menu commands to appropriate (possibly default) code, even
21some default print/preview functionality and support for command undo/redo.
22The framework is highly modular, allowing overriding and replacement of functionality
23and objects to achieve more than the default behaviour.
24
25These are the overall steps involved in creating an application based on the document/view framework:
26
27\begin{enumerate}\itemsep=0pt
28\item Define your own document and view classes, overriding a minimal set of
29member functions e.g. for input/output, drawing and initialization.
30\item Define any subwindows
31(such as a scrolled window) that are needed for the view(s). You may need to route some events
32to views or documents, for example OnPaint needs to be routed to wxView::OnDraw.
33\item Decide what style of interface you will use: Microsoft's MDI (multiple
34document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
35for each document), or single-window (one document open at a time, as in Windows Write).
36\item Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
37of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
38you initialize a view. Create menus using standard menu ids (such as wxID\_OPEN, wxID\_PRINT),
39routing non-application-specific identifiers to the base frame's OnMenuCommand.
40\item Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
41as many wxDocTemplate instances as necessary to define relationships between documents and
42views. For a simple application, there will be just one wxDocTemplate.
43\end{enumerate}
44
45If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand
46and use wxCommandProcessor::Submit instead of directly executing code. The framework will
47take care of calling Undo and Do functions as appropriate, so long as the wxID\_UNDO and
48wxID\_REDO menu items are defined in the view menu.
49
50Here are a few examples of the tailoring you can do to go beyond the default framework
51behaviour:
52
53\begin{itemize}\itemsep=0pt
54\item Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
55or a command history editor.
56\item Override wxView::OnCreatePrintout to create an instance of a derived \helpref{wxPrintout}{wxprintout}\rtfsp
57class, to provide multi-page document facilities.
58\item Override wxDocManager::SelectDocumentPath to provide a different file selector.
59\item Limit the maximum number of open documents and the maximum number of undo commands.
60\end{itemize}
61
62Note that to activate framework functionality, you need to use some or all of
63the wxWidgets \helpref{predefined command identifiers}{predefinedids} in your menus.
64
65\perlnote{The document/view framework is available in wxPerl. To use it,
66you will need the following statements in your application code:\par
67{\small
68\begin{verbatim}
69use Wx::DocView;
70use Wx ':docview'; # import constants (optional)
71\end{verbatim}
72}}
73
74\subsection{wxDocument overview}\label{wxdocumentoverview}
75
76\overview{Document/view framework overview}{docviewoverview}
77
78Class: \helpref{wxDocument}{wxdocument}
79
80The wxDocument class can be used to model an application's file-based
81data. It is part of the document/view framework supported by wxWidgets,
82and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}\rtfsp
83and \helpref{wxDocManager}{wxdocmanager} classes.
84
85Using this framework can save a lot of routine user-interface programming,
86since a range of menu commands -- such as open, save, save as -- are supported automatically.
87The programmer just needs to define a minimal set of classes and member functions
88for the framework to call when necessary. Data, and the means to view and edit
89the data, are explicitly separated out in this model, and the concept of multiple {\it views} onto
90the same data is supported.
91
92Note that the document/view model will suit many but not all styles of application.
93For example, it would be overkill for a simple file conversion utility, where there
94may be no call for {\it views} on {\it documents} or the ability to open, edit and save
95files. But probably the majority of applications are document-based.
96
97See the example application in {\tt samples/docview}.
98
99To use the abstract wxDocument class, you need to derive a new class and override
100at least the member functions SaveObject and LoadObject. SaveObject and
101LoadObject will be called by the framework when the document needs to be saved
102or loaded.
103
104Use the macros DECLARE\_DYNAMIC\_CLASS and IMPLEMENT\_DYNAMIC\_CLASS in order
105to allow the framework to create document objects on demand. When you create
106a \helpref{wxDocTemplate}{wxdoctemplate} object on application initialization, you
107should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
108so that it knows how to create an instance of this class.
109
110If you do not wish to use the wxWidgets method of creating document
111objects dynamically, you must override wxDocTemplate::CreateDocument
112to return an instance of the appropriate class.
113
114\subsection{wxView overview}\label{wxviewoverview}
115
116\overview{Document/view framework overview}{docviewoverview}
117
118Class: \helpref{wxView}{wxview}
119
120The wxView class can be used to model the viewing and editing component of
121an application's file-based data. It is part of the document/view framework supported by wxWidgets,
122and cooperates with the \helpref{wxDocument}{wxdocument}, \helpref{wxDocTemplate}{wxdoctemplate}
123and \helpref{wxDocManager}{wxdocmanager} classes.
124
125See the example application in {\tt samples/docview}.
126
127To use the abstract wxView class, you need to derive a new class and override
128at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You will probably
129want to override OnMenuCommand to respond to menu commands from the frame containing the
130view.
131
132Use the macros DECLARE\_DYNAMIC\_CLASS and IMPLEMENT\_DYNAMIC\_CLASS in order
133to allow the framework to create view objects on demand. When you create
134a \helpref{wxDocTemplate}{wxdoctemplate} object on application initialization, you
135should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
136so that it knows how to create an instance of this class.
137
138If you do not wish to use the wxWidgets method of creating view
139objects dynamically, you must override wxDocTemplate::CreateView
140to return an instance of the appropriate class.
141
142\subsection{wxDocTemplate overview}\label{wxdoctemplateoverview}
143
144\overview{Document/view framework overview}{docviewoverview}
145
146Class: \helpref{wxDocTemplate}{wxdoctemplate}
147
148The wxDocTemplate class is used to model the relationship between a
149document class and a view class. The application creates a document
150template object for each document/view pair. The list of document
151templates managed by the wxDocManager instance is used to create
152documents and views. Each document template knows what file filters
153and default extension are appropriate for a document/view combination,
154and how to create a document or view.
155
156For example, you might write a small doodling application that can load
157and save lists of line segments. If you had two views of the data -- graphical,
158and a list of the segments -- then you would create one document class DoodleDocument,
159and two view classes (DoodleGraphicView and DoodleListView). You would also
160need two document templates, one for the graphical view and another for the
161list view. You would pass the same document class and default file extension to both
162document templates, but each would be passed a different view class. When
163the user clicks on the Open menu item, the file selector is displayed
164with a list of possible file filters -- one for each wxDocTemplate. Selecting
165the filter selects the wxDocTemplate, and when
166a file is selected, that template will be used for creating a document
167and view. Under non-Windows platforms, the user will be prompted for
168a list of templates before the file selector is shown, since most file selectors
169do not allow a choice of file filters.
170
171For the case where an application has one document type and one view type,
172a single document template is constructed, and dialogs will be appropriately
173simplified.
174
175wxDocTemplate is part of the document/view framework supported by wxWidgets,
176and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}
177and \helpref{wxDocManager}{wxdocmanager} classes.
178
179See the example application in {\tt samples/docview}.
180
181To use the wxDocTemplate class, you do not need to derive a new class.
182Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass) and
183CLASSINFO(YourViewClass) to allow dynamic instance creation.
184If you do not wish to use the wxWidgets method of creating document
185objects dynamically, you must override wxDocTemplate::CreateDocument
186and wxDocTemplate::CreateView to return instances of the appropriate class.
187
188{\it NOTE}: the document template has nothing to do with the C++ template construct. C++
189templates are not used anywhere in wxWidgets.
190
191\subsection{wxDocManager overview}\label{wxdocmanageroverview}
192
193\overview{Document/view framework overview}{docviewoverview}
194
195Class: \helpref{wxDocManager}{wxdocmanager}
196
197The wxDocManager class is part of the document/view framework supported by wxWidgets,
198and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}\rtfsp
199and \helpref{wxDocTemplate}{wxdoctemplate} classes.
200
201A wxDocManager instance coordinates documents, views and document templates. It keeps a list of document
202and template instances, and much functionality is routed through this object, such
203as providing selection and file dialogs. The application can use this class `as is' or
204derive a class and override some members to extend or change the functionality.
205Create an instance of this class near the beginning of your application initialization,
206before any documents, views or templates are manipulated.
207
208There may be multiple wxDocManager instances in an application.
209
210See the example application in {\tt samples/docview}.
211
212\subsection{wxCommand overview}\label{wxcommandoverview}
213
214\overview{Document/view framework overview}{docviewoverview}
215
216Classes: \helpref{wxCommand}{wxcommand}, \helpref{wxCommandProcessor}{wxcommandprocessor}
217
218wxCommand is a base class for modelling an application command,
219which is an action usually performed by selecting a menu item, pressing
220a toolbar button or any other means provided by the application to
221change the data or view.
222
223Instead of the application functionality being scattered around
224switch statements and functions in a way that may be hard to
225read and maintain, the functionality for a command is explicitly represented
226as an object which can be manipulated by a framework or application.
227When a user interface event occurs, the application {\it submits} a command
228to a \helpref{wxCommandProcessor}{wxcommandprocessoroverview} object to execute and
229store.
230
231The wxWidgets document/view framework handles Undo and Redo by use of
232wxCommand and wxCommandProcessor objects. You might find further uses
233for wxCommand, such as implementing a macro facility that stores, loads
234and replays commands.
235
236An application can derive a new class for every command, or, more likely, use
237one class parameterized with an integer or string command identifier.
238
239\subsection{wxCommandProcessor overview}\label{wxcommandprocessoroverview}
240
241\overview{Document/view framework overview}{docviewoverview}
242
243Classes: \helpref{wxCommandProcessor}{wxcommandprocessor}, \helpref{wxCommand}{wxcommand}
244
245wxCommandProcessor is a class that maintains a history of wxCommand
246instances, with undo/redo functionality built-in. Derive a new class from this
247if you want different behaviour.
248
249\subsection{wxFileHistory overview}\label{wxfilehistoryoverview}
250
251\overview{Document/view framework overview}{docviewoverview}
252
253Classes: \helpref{wxFileHistory}{wxfilehistory}, \helpref{wxDocManager}{wxdocmanager}
254
255wxFileHistory encapsulates functionality to record the last few files visited, and
256to allow the user to quickly load these files using the list appended to the File menu.
257
258Although wxFileHistory is used by wxDocManager, it can be used independently. You may wish
259to derive from it to allow different behaviour, such as popping up a scrolling
260list of files.
261
262By calling wxFileHistory::FileHistoryUseMenu you can associate a file menu with
263the file history, that will be used for appending the filenames. They are
264appended using menu identifiers in the range wxID\_FILE1 to wxID\_FILE9.
265
266In order to respond to a file load command from one of these identifiers,
267you need to handle them using an event handler, for example:
268
269{\small
270\begin{verbatim}
271BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
272 EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)
273 EVT_MENU_RANGE(wxID_FILE1, wxID_FILE9, wxDocParentFrame::OnMRUFile)
274END_EVENT_TABLE()
275
276void wxDocParentFrame::OnExit(wxCommandEvent& WXUNUSED(event))
277{
278 Close();
279}
280
281void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
282{
283 wxString f(m_docManager->GetHistoryFile(event.GetId() - wxID_FILE1));
284 if (f != "")
285 (void)m_docManager->CreateDocument(f, wxDOC_SILENT);
286}
287\end{verbatim}
288}
289
290\subsection{wxWidgets predefined command identifiers}\label{predefinedids}
291
292To allow communication between the application's menus and the
293document/view framework, several command identifiers are predefined for you
294to use in menus. The framework recognizes them and processes them if you
295forward commands from wxFrame::OnMenuCommand (or perhaps from toolbars and
296other user interface constructs).
297
298\begin{itemize}\itemsep=0pt
299\item wxID\_OPEN (5000)
300\item wxID\_CLOSE (5001)
301\item wxID\_NEW (5002)
302\item wxID\_SAVE (5003)
303\item wxID\_SAVEAS (5004)
304\item wxID\_REVERT (5005)
305\item wxID\_EXIT (5006)
306\item wxID\_UNDO (5007)
307\item wxID\_REDO (5008)
308\item wxID\_HELP (5009)
309\item wxID\_PRINT (5010)
310\item wxID\_PRINT\_SETUP (5011)
311\item wxID\_PREVIEW (5012)
312\end{itemize}
313
314