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