Contents Up Previous Next

Document/view overview

Classes: wxDocument, wxView, wxDocTemplate, wxDocManager, wxDocParentFrame, wxDocChildFrame, wxDocMDIParentFrame, wxDocMDIChildFrame, wxCommand, wxCommandProcessor

The document/view framework is found in most application frameworks, because it can dramatically simplify the code required to build many kinds of application.

The idea is that you can model your application primarily in terms of documents to store data and provide interface-independent operations upon it, and views to visualise and manipulate the data. Documents know how to do input and output given stream objects, and views are responsible for taking input from physical windows and performing the manipulation on the document data. If a document's data changes, all views should be updated to reflect the change.

The framework can provide many user-interface elements based on this model. Once you have defined your own classes and the relationships between them, the framework takes care of popping up file selectors, opening and closing files, asking the user to save modifications, routing menu commands to appropriate (possibly default) code, even some default print/preview functionality and support for command undo/redo. The framework is highly modular, allowing overriding and replacement of functionality and objects to achieve more than the default behaviour.

These are the overall steps involved in creating an application based on the document/view framework:

  1. Define your own document and view classes, overriding a minimal set of member functions e.g. for input/output, drawing and initialization.
  2. Define any subwindows (such as a scrolled window) that are needed for the view(s). You may need to route some events to views or documents, for example OnPaint needs to be routed to wxView::OnDraw.
  3. Decide what style of interface you will use: Microsoft's MDI (multiple document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame for each document), or single-window (one document open at a time, as in Windows Write).
  4. Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when you initialize a view. Create menus using standard menu ids (such as wxID_OPEN, wxID_PRINT).
  5. Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then as many wxDocTemplate instances as necessary to define relationships between documents and views. For a simple application, there will be just one wxDocTemplate.

If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand and use wxCommandProcessor::Submit instead of directly executing code. The framework will take care of calling Undo and Do functions as appropriate, so long as the wxID_UNDO and wxID_REDO menu items are defined in the view menu.

Here are a few examples of the tailoring you can do to go beyond the default framework behaviour:

Note that to activate framework functionality, you need to use some or all of the wxWidgets predefined command identifiers in your menus.

wxPerl note: The document/view framework is available in wxPerl. To use it, you will need the following statements in your application code:

use Wx::DocView;
use Wx ':docview';   # import constants (optional)

wxDocument overview
wxView overview
wxDocTemplate overview
wxDocManager overview
wxCommand overview
wxCommandProcessor overview
wxFileHistory overview
wxWidgets predefined command identifiers

wxDocument overview

Document/view framework overview

Class: wxDocument

The wxDocument class can be used to model an application's file-based data. It is part of the document/view framework supported by wxWidgets, and cooperates with the wxView, wxDocTemplate and wxDocManager classes.

Using this framework can save a lot of routine user-interface programming, since a range of menu commands -- such as open, save, save as -- are supported automatically. The programmer just needs to define a minimal set of classes and member functions for the framework to call when necessary. Data, and the means to view and edit the data, are explicitly separated out in this model, and the concept of multiple views onto the same data is supported.

Note that the document/view model will suit many but not all styles of application. For example, it would be overkill for a simple file conversion utility, where there may be no call for views on documents or the ability to open, edit and save files. But probably the majority of applications are document-based.

See the example application in samples/docview.

To use the abstract wxDocument class, you need to derive a new class and override at least the member functions SaveObject and LoadObject. SaveObject and LoadObject will be called by the framework when the document needs to be saved or loaded.

Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order to allow the framework to create document objects on demand. When you create a wxDocTemplate object on application initialization, you should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor so that it knows how to create an instance of this class.

If you do not wish to use the wxWidgets method of creating document objects dynamically, you must override wxDocTemplate::CreateDocument to return an instance of the appropriate class.

wxView overview

Document/view framework overview

Class: wxView

The wxView class can be used to model the viewing and editing component of an application's file-based data. It is part of the document/view framework supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate and wxDocManager classes.

See the example application in samples/docview.

To use the abstract wxView class, you need to derive a new class and override at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You will probably want to respond to menu commands from the frame containing the view.

Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order to allow the framework to create view objects on demand. When you create a wxDocTemplate object on application initialization, you should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor so that it knows how to create an instance of this class.

If you do not wish to use the wxWidgets method of creating view objects dynamically, you must override wxDocTemplate::CreateView to return an instance of the appropriate class.

wxDocTemplate overview

Document/view framework overview

Class: wxDocTemplate

The wxDocTemplate class is used to model the relationship between a document class and a view class. The application creates a document template object for each document/view pair. The list of document templates managed by the wxDocManager instance is used to create documents and views. Each document template knows what file filters and default extension are appropriate for a document/view combination, and how to create a document or view.

For example, you might write a small doodling application that can load and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad and save lists of line segments. If you had two views oleast tad