X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/526954c5968baa29218c994ec48e476ae2bd4b9f..507a6cd69a2097a415b81745b014b286ba3d451b:/docs/doxygen/overviews/docview.h diff --git a/docs/doxygen/overviews/docview.h b/docs/doxygen/overviews/docview.h index 94344b42cd..49d2689a55 100644 --- a/docs/doxygen/overviews/docview.h +++ b/docs/doxygen/overviews/docview.h @@ -10,177 +10,168 @@ @page overview_docview Document/View Framework -Classes: wxDocument, wxView, wxDocTemplate, wxDocManager, wxDocParentFrame, - wxDocChildFrame, wxDocMDIParentFrame, wxDocMDIChildFrame, - wxCommand, wxCommandProcessor +@tableofcontents 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 @e documents to store data -and provide interface-independent operations upon it, and @e 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. +The idea is that you can model your application primarily in terms of +@e documents to store data and provide interface-independent operations upon +it, and @e 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. +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. +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. +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: @li Define your own document and view classes, overriding a minimal set of member functions e.g. for input/output, drawing and initialization. -@li 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. +@li 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. @li 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). -@li 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). -@li 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: - -@li Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy, - or a command history editor. -@li Override wxView::OnCreatePrintout to create an instance of a derived wxPrintout - class, to provide multi-page document facilities. -@li Override wxDocManager::SelectDocumentPath to provide a different file selector. -@li Limit the maximum number of open documents and the maximum number of undo commands. + 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). +@li 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). +@li 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: + +@li Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo + strategy, or a command history editor. +@li Override wxView::OnCreatePrintout to create an instance of a derived + wxPrintout class, to provide multi-page document facilities. +@li Override wxDocManager::SelectDocumentPath to provide a different file + selector. +@li Limit the maximum number of open documents and the maximum number of undo + commands. Note that to activate framework functionality, you need to use some or all of the wxWidgets @ref overview_docview_predefid in your menus. @beginWxPerlOnly -The document/view framework is available in wxPerl. To use it, -you will need the following statements in your application code: +The document/view framework is available in wxPerl. To use it, you will need +the following statements in your application code: -@code +@code{.pl} use Wx::DocView; use Wx ':docview'; # import constants (optional) @endcode @endWxPerlOnly -@li @ref overview_docview_wxdoc -@li @ref overview_docview_wxview -@li @ref overview_docview_wxdoctemplate -@li @ref overview_docview_wxdocmanager -@li @ref overview_docview_wxcommand -@li @ref overview_docview_wxcommandproc -@li @ref overview_docview_filehistory -@li @ref overview_docview_predefid - - -
+@see @ref group_class_docview, -@section overview_docview_wxdoc wxDocument overview -Class: wxDocument +@section overview_docview_wxdoc wxDocument Overview -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 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 -@e views onto the same data is supported. +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 @e 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 @e views on @e documents or the ability to open, edit and save -files. But probably the majority of applications are document-based. +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 @e views on @e documents or the ability +to open, edit and save files. But probably the majority of applications are +document-based. -See the example application in @c 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. +See the example application in @c 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. +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. +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. -@section overview_docview_wxview wxView overview +@section overview_docview_wxview wxView 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. +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 @c 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. - - - -@section overview_docview_wxdoctemplate wxDocTemplate 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 of the data -- graphical, -and a list of the segments -- then you would create one document class DoodleDocument, -and two view classes (DoodleGraphicView and DoodleListView). You would also -need two document templates, one for the graphical view and another for the -list view. You would pass the same document class and default file extension to both -document templates, but each would be passed a different view class. When -the user clicks on the Open menu item, the file selector is displayed -with a list of possible file filters -- one for each wxDocTemplate. Selecting -the filter selects the wxDocTemplate, and when a file is selected, that template -will be used for creating a document and view. +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. + + + +@section overview_docview_wxdoctemplate wxDocTemplate Overview + +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 of the data -- graphical, and +a list of the segments -- then you would create one document class +DoodleDocument, and two view classes (DoodleGraphicView and DoodleListView). +You would also need two document templates, one for the graphical view and +another for the list view. You would pass the same document class and default +file extension to both document templates, but each would be passed a different +view class. When the user clicks on the Open menu item, the file selector is +displayed with a list of possible file filters -- one for each wxDocTemplate. +Selecting the filter selects the wxDocTemplate, and when a file is selected, +that template will be used for creating a document and view. For the case where an application has one document type and one view type, a single document template is constructed, and dialogs will be appropriately @@ -191,9 +182,10 @@ and cooperates with the wxView, wxDocument and wxDocManager classes. See the example application in @c samples/docview. -To use the wxDocTemplate class, you do not need to derive a new class. -Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass) -and CLASSINFO(YourViewClass) to allow dynamic instance creation. +To use the wxDocTemplate class, you do not need to derive a new class. Just +pass relevant information to the constructor including +CLASSINFO(YourDocumentClass) and CLASSINFO(YourViewClass) to allow dynamic +instance creation. If you do not wish to use the wxWidgets method of creating document objects dynamically, you must override wxDocTemplate::CreateDocument @@ -203,87 +195,81 @@ and wxDocTemplate::CreateView to return instances of the appropriate class. -@section overview_docview_wxdocmanager wxDocManager overview - -Class: wxDocManager +@section overview_docview_wxdocmanager wxDocManager Overview -The wxDocManager class is part of the document/view framework supported by wxWidgets, -and cooperates with the wxView, wxDocument and wxDocTemplate classes. +The wxDocManager class is part of the document/view framework supported by +wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate +classes. -A wxDocManager instance coordinates documents, views and document templates. -It keeps a list of document and template instances, and much functionality is routed -through this object, such as providing selection and file dialogs. -The application can use this class 'as is' or derive a class and override some members -to extend or change the functionality. +A wxDocManager instance coordinates documents, views and document templates. It +keeps a list of document and template instances, and much functionality is +routed through this object, such as providing selection and file dialogs. The +application can use this class 'as is' or derive a class and override some +members to extend or change the functionality. -Create an instance of this class near the beginning of your application initialization, -before any documents, views or templates are manipulated. - -There may be multiple wxDocManager instances in an application. -See the example application in @c samples/docview. +Create an instance of this class near the beginning of your application +initialization, before any documents, views or templates are manipulated. +There may be multiple wxDocManager instances in an application. See the example +application in @c samples/docview. -@section overview_docview_wxcommand wxCommand overview -Classes: wxCommand, wxCommandProcessor +@section overview_docview_wxcommand wxCommand Overview -wxCommand is a base class for modelling an application command, -which is an action usually performed by selecting a menu item, pressing -a toolbar button or any other means provided by the application to -change the data or view. +wxCommand is a base class for modelling an application command, which is an +action usually performed by selecting a menu item, pressing a toolbar button or +any other means provided by the application to change the data or view. -Instead of the application functionality being scattered around -switch statements and functions in a way that may be hard to -read and maintain, the functionality for a command is explicitly represented -as an object which can be manipulated by a framework or application. +Instead of the application functionality being scattered around switch +statements and functions in a way that may be hard to read and maintain, the +functionality for a command is explicitly represented as an object which can be +manipulated by a framework or application. -When a user interface event occurs, the application @e submits a command -to a wxCommandProcessor object to execute and store. +When a user interface event occurs, the application @e submits a command to a +wxCommandProcessor object to execute and store. -The wxWidgets document/view framework handles Undo and Redo by use of -wxCommand and wxCommandProcessor objects. You might find further uses -for wxCommand, such as implementing a macro facility that stores, loads -and replays commands. +The wxWidgets document/view framework handles Undo and Redo by use of wxCommand +and wxCommandProcessor objects. You might find further uses for wxCommand, such +as implementing a macro facility that stores, loads and replays commands. An application can derive a new class for every command, or, more likely, use one class parameterized with an integer or string command identifier. -@section overview_docview_wxcommandproc wxCommandProcessor overview - -Classes: wxCommandProcessor, wxCommand +@section overview_docview_wxcommandproc wxCommandProcessor Overview -wxCommandProcessor is a class that maintains a history of wxCommand -instances, with undo/redo functionality built-in. Derive a new class from this -if you want different behaviour. +wxCommandProcessor is a class that maintains a history of wxCommand instances, +with undo/redo functionality built-in. Derive a new class from this if you want +different behaviour. -@section overview_docview_filehistory wxFileHistory overview +@section overview_docview_filehistory wxFileHistory Overview -Classes: wxFileHistory, wxDocManager +wxFileHistory encapsulates functionality to record the last few files visited, +and to allow the user to quickly load these files using the list appended to +the File menu. Although wxFileHistory is used by wxDocManager, it can be used +independently. You may wish to derive from it to allow different behaviour, +such as popping up a scrolling list of files. -wxFileHistory encapsulates functionality to record the last few files visited, and -to allow the user to quickly load these files using the list appended to the File menu. -Although wxFileHistory is used by wxDocManager, it can be used independently. You may wish -to derive from it to allow different behaviour, such as popping up a scrolling -list of files. +By calling wxFileHistory::UseMenu() you can associate a file menu with the file +history. The menu will then be used for appending filenames that are added to +the history. -By calling wxFileHistory::UseMenu() you can associate a file menu with the file history. -The menu will then be used for appending filenames that are added to the history. +Please notice that currently if the history already contained filenames when +UseMenu() is called (e.g. when initializing a second MDI child frame), the menu +is not automatically initialized with the existing filenames in the history and +so you need to call wxFileHistory::AddFilesToMenu() after UseMenu() explicitly +in order to initialize the menu with the existing list of MRU files (otherwise +an assertion failure is raised in debug builds). -Please notice that currently if the history already contained filenames when UseMenu() -is called (e.g. when initializing a second MDI child frame), the menu is not automatically -initialized with the existing filenames in the history and so you need to call -wxFileHistory::AddFilesToMenu() after UseMenu() explicitly in order to initialize the menu with -the existing list of MRU files (otherwise an assertion failure is raised in debug builds). +The filenames are appended using menu identifiers in the range @c wxID_FILE1 to +@c wxID_FILE9. -The filenames are appended using menu identifiers in the range @c wxID_FILE1 to @c wxID_FILE9. - -In order to respond to a file load command from one of these identifiers, -you need to handle them using an event handler, for example: +In order to respond to a file load command from one of these identifiers, you +need to handle them using an event handler, for example: @code BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame) @@ -306,11 +292,10 @@ void wxDocParentFrame::OnMRUFile(wxCommandEvent& event) -@section overview_docview_predefid wxWidgets predefined command identifiers +@section overview_docview_predefid Predefined Command Identifiers -To allow communication between the application's menus and the -document/view framework, several command identifiers are predefined for you -to use in menus. +To allow communication between the application's menus and the document/view +framework, several command identifiers are predefined for you to use in menus. @verbatim wxID_OPEN (5000) @@ -329,4 +314,3 @@ wxID_PREVIEW (5012) @endverbatim */ -