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