+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: tdocview.tex
+%% Purpose: Document/view overview
+%% Author: wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID: $Id$
+%% Copyright: (c) wxWidgets Team
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\section{Document/view overview}\label{docviewoverview}
Classes: \helpref{wxDocument}{wxdocument}, \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate},\rtfsp
\helpref{wxDocManager}{wxdocmanager}, \helpref{wxDocParentFrame}{wxdocparentframe}, \helpref{wxDocChildFrame}{wxdocchildframe},
+\rtfsp\helpref{wxDocMDIParentFrame}{wxdocmdiparentframe}, \helpref{wxDocMDIChildFrame}{wxdocmdichildframe},
\rtfsp\helpref{wxCommand}{wxcommand}, \helpref{wxCommandProcessor}{wxcommandprocessor}
The document/view framework is found in most application frameworks, because it
\item Define your own document and view classes, overriding a minimal set of
member functions e.g. for input/output, drawing and initialization.
\item Define any subwindows
-(such as a canvas) that are needed for the view(s). You may need to route some events
+(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.
\item 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).
\item 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),
-routing non-application-specific identifiers to the base frame's OnMenuCommand.
+you initialize a view. Create menus using standard menu ids (such as wxID\_OPEN, wxID\_PRINT).
\item 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.
\end{itemize}
Note that to activate framework functionality, you need to use some or all of
-the wxWindows \helpref{predefined command identifiers}{predefinedids} in your menus.
+the wxWidgets \helpref{predefined command identifiers}{predefinedids} in your menus.
+
+\perlnote{The document/view framework is available in wxPerl. To use it,
+you will need the following statements in your application code:\par
+{\small
+\begin{verbatim}
+use Wx::DocView;
+use Wx ':docview'; # import constants (optional)
+\end{verbatim}
+}}
\subsection{wxDocument overview}\label{wxdocumentoverview}
Class: \helpref{wxDocument}{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 wxWindows,
+data. It is part of the document/view framework supported by wxWidgets,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}\rtfsp
and \helpref{wxDocManager}{wxdocmanager} classes.
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 wxWindows method of creating document
+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.
Class: \helpref{wxView}{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 wxWindows,
+an application's file-based data. It is part of the document/view framework supported by wxWidgets,
and cooperates with the \helpref{wxDocument}{wxdocument}, \helpref{wxDocTemplate}{wxdoctemplate}
and \helpref{wxDocManager}{wxdocmanager} classes.
See the example application in {\tt 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'll probably
-want to override OnMenuCommand to respond to menu commands from the frame containing the
-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
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 wxWindows method of creating view
+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.
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. Under non-Windows platforms, the user will be prompted for
-a list of templates before the file selector is shown, since most file selectors
-do not allow a choice of file filters.
+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
simplified.
-wxDocTemplate is part of the document/view framework supported by wxWindows,
+wxDocTemplate is part of the document/view framework supported by wxWidgets,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}
and \helpref{wxDocManager}{wxdocmanager} classes.
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 wxWindows method of creating document
+If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
and wxDocTemplate::CreateView to return instances of the appropriate class.
-{\it NOTE}: the document template has nothing to do with the C++ template construct. C++
-templates are not used anywhere in wxWindows.
+{\it NOTE}: the document template has nothing to do with the C++ template construct.
\subsection{wxDocManager overview}\label{wxdocmanageroverview}
Class: \helpref{wxDocManager}{wxdocmanager}
-The wxDocManager class is part of the document/view framework supported by wxWindows,
+The wxDocManager class is part of the document/view framework supported by wxWidgets,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}\rtfsp
and \helpref{wxDocTemplate}{wxdoctemplate} classes.
-A wxDocManager instance coordinates documents, views and document templates. It keeps a list of document and
+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.
to a \helpref{wxCommandProcessor}{wxcommandprocessoroverview} object to execute and
store.
-The wxWindows document/view framework handles Undo and Redo by use of
+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.
to derive from it to allow different behaviour, such as popping up a scrolling
list of files.
-By calling wxFileHistory::FileHistoryUseMenu you can associate a file menu with
-the file history, that will be used for appending the filenames. They are
-appended using menu identifiers in the range wxID\_FILE1 to wxID\_FILE9.
+By calling \helpref{wxFileHistory::UseMenu()}{wxfilehistoryusemenu} 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
+\helpref{AddFilesToMenu()}{wxfilehistoryaddfilestomenu} 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
+\texttt{wxID\_FILE1} to \texttt{wxID\_FILE9}.
In order to respond to a file load command from one of these identifiers,
-you need to handle them in your wxFrame::OnMenuCommand. Below is the
-code used by the default document/view parent frame.
+you need to handle them using an event handler, for example:
+{\small
\begin{verbatim}
-void wxDocParentFrame::OnMenuCommand(int id)
+BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
+ EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)
+ EVT_MENU_RANGE(wxID_FILE1, wxID_FILE9, wxDocParentFrame::OnMRUFile)
+END_EVENT_TABLE()
+
+void wxDocParentFrame::OnExit(wxCommandEvent& WXUNUSED(event))
{
- switch (id)
- {
- case wxID_EXIT:
- {
- if (GetEventHandler()->OnClose())
- delete this;
- break;
- }
- case wxID_FILE1:
- case wxID_FILE2:
- case wxID_FILE3:
- case wxID_FILE4:
- case wxID_FILE5:
- case wxID_FILE6:
- case wxID_FILE7:
- case wxID_FILE8:
- case wxID_FILE9:
- {
- char *f = docManager->GetHistoryFile(id-wxID_FILE1);
- if (f)
- (void)docManager->CreateDocument(f, wxDOC_SILENT);
- break;
- }
- default:
- {
- docManager->OnMenuCommand(id);
- }
- }
+ Close();
+}
+
+void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
+{
+ wxString f(m_docManager->GetHistoryFile(event.GetId() - wxID_FILE1));
+ if (!f.empty())
+ (void)m_docManager->CreateDocument(f, wxDOC_SILENT);
}
\end{verbatim}
+}
-\subsection{wxWindows predefined command identifiers}\label{predefinedids}
+\subsection{wxWidgets predefined command identifiers}\label{predefinedids}
To allow communication between the application's menus and the
document/view framework, several command identifiers are predefined for you
-to use in menus. The framework recognizes them and processes them if you
-forward commands from wxFrame::OnMenuCommand (or perhaps from toolbars and
-other user interface constructs).
+to use in menus.
\begin{itemize}\itemsep=0pt
\item wxID\_OPEN (5000)
\item wxID\_PREVIEW (5012)
\end{itemize}
-
projects / wxWidgets.git / blobdiff