docs/doxygen/overviews/docview.h

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