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