a7af285d1a
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@47777 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
365 lines
13 KiB
TeX
365 lines
13 KiB
TeX
\section{\class{wxDocument}}\label{wxdocument}
|
|
|
|
The document 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 \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}\rtfsp
|
|
and \helpref{wxDocManager}{wxdocmanager} classes.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxEvtHandler}{wxevthandler}\\
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/docview.h>
|
|
|
|
\wxheading{Library}
|
|
|
|
\helpref{wxCore}{librarieslist}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxDocument overview}{wxdocumentoverview}, \helpref{wxView}{wxview},\rtfsp
|
|
\helpref{wxDocTemplate}{wxdoctemplate}, \helpref{wxDocManager}{wxdocmanager}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxDocument::m\_commandProcessor}\label{wxdocumentmcommandprocessor}
|
|
|
|
\member{wxCommandProcessor*}{m\_commandProcessor}
|
|
|
|
A pointer to the command processor associated with this document.
|
|
|
|
\membersection{wxDocument::m\_documentFile}\label{wxdocumentmdocumentfile}
|
|
|
|
\member{wxString}{m\_documentFile}
|
|
|
|
Filename associated with this document (``" if none).
|
|
|
|
\membersection{wxDocument::m\_documentModified}\label{wxdocumentmdocumentmodified}
|
|
|
|
\member{bool}{m\_documentModified}
|
|
|
|
true if the document has been modified, false otherwise.
|
|
|
|
\membersection{wxDocument::m\_documentTemplate}\label{wxdocumentmdocumenttemplate}
|
|
|
|
\member{wxDocTemplate *}{m\_documentTemplate}
|
|
|
|
A pointer to the template from which this document was created.
|
|
|
|
\membersection{wxDocument::m\_documentTitle}\label{wxdocumentmdocumenttitle}
|
|
|
|
\member{wxString}{m\_documentTitle}
|
|
|
|
Document title. The document title is used for an associated
|
|
frame (if any), and is usually constructed by the framework from
|
|
the filename.
|
|
|
|
\membersection{wxDocument::m\_documentTypeName}\label{documenttypename}
|
|
|
|
\member{wxString}{m\_documentTypeName}
|
|
|
|
The document type name given to the wxDocTemplate constructor, copied to this
|
|
variable when the document is created. If several document templates are
|
|
created that use the same document type, this variable is used in wxDocManager::CreateView
|
|
to collate a list of alternative view types that can be used on this kind of
|
|
document. Do not change the value of this variable.
|
|
|
|
\membersection{wxDocument::m\_documentViews}\label{wxdocumentmdocumentviews}
|
|
|
|
\member{wxList}{m\_documentViews}
|
|
|
|
List of wxView instances associated with this document.
|
|
|
|
\membersection{wxDocument::wxDocument}\label{wxdocumentctor}
|
|
|
|
\func{}{wxDocument}{\void}
|
|
|
|
Constructor. Define your own default constructor to initialize application-specific
|
|
data.
|
|
|
|
\membersection{wxDocument::\destruct{wxDocument}}\label{wxdocumentdtor}
|
|
|
|
\func{}{\destruct{wxDocument}}{\void}
|
|
|
|
Destructor. Removes itself from the document manager.
|
|
|
|
\membersection{wxDocument::AddView}\label{wxdocumentaddview}
|
|
|
|
\func{virtual bool}{AddView}{\param{wxView *}{view}}
|
|
|
|
If the view is not already in the list of views, adds the view and calls OnChangedViewList.
|
|
|
|
\membersection{wxDocument::Close}\label{wxdocumentclose}
|
|
|
|
\func{virtual bool}{Close}{\void}
|
|
|
|
Closes the document, by calling OnSaveModified and then (if this returned true) OnCloseDocument.
|
|
This does not normally delete the document object: use DeleteAllViews to do this implicitly.
|
|
|
|
\membersection{wxDocument::DeleteAllViews}\label{wxdocumentdeleteviews}
|
|
|
|
\func{virtual bool}{DeleteAllViews}{\void}
|
|
|
|
Calls wxView::Close and deletes each view. Deleting the final view will implicitly
|
|
delete the document itself, because the wxView destructor calls RemoveView. This
|
|
in turns calls wxDocument::OnChangedViewList, whose default implemention is to
|
|
save and delete the document if no views exist.
|
|
|
|
\membersection{wxDocument::GetCommandProcessor}\label{wxdocumentgetcommandprocessor}
|
|
|
|
\constfunc{wxCommandProcessor*}{GetCommandProcessor}{\void}
|
|
|
|
Returns a pointer to the command processor associated with this document.
|
|
|
|
See \helpref{wxCommandProcessor}{wxcommandprocessor}.
|
|
|
|
\membersection{wxDocument::GetDocumentTemplate}\label{wxdocumentgetdocumenttemplate}
|
|
|
|
\constfunc{wxDocTemplate*}{GetDocumentTemplate}{\void}
|
|
|
|
Gets a pointer to the template that created the document.
|
|
|
|
\membersection{wxDocument::GetDocumentManager}\label{wxdocumentgetdocumentmanager}
|
|
|
|
\constfunc{wxDocManager*}{GetDocumentManager}{\void}
|
|
|
|
Gets a pointer to the associated document manager.
|
|
|
|
\membersection{wxDocument::GetDocumentName}\label{wxdocumentgetdocumentname}
|
|
|
|
\constfunc{wxString}{GetDocumentName}{\void}
|
|
|
|
Gets the document type name for this document. See the comment for \helpref{documentTypeName}{documenttypename}.
|
|
|
|
\membersection{wxDocument::GetDocumentWindow}\label{wxdocumentgetdocumentwindow}
|
|
|
|
\constfunc{wxWindow*}{GetDocumentWindow}{\void}
|
|
|
|
Intended to return a suitable window for using as a parent for document-related
|
|
dialog boxes. By default, uses the frame associated with the first view.
|
|
|
|
\membersection{wxDocument::GetFilename}\label{wxdocumentgetfilename}
|
|
|
|
\constfunc{wxString}{GetFilename}{\void}
|
|
|
|
Gets the filename associated with this document, or "" if none is
|
|
associated.
|
|
|
|
\membersection{wxDocument::GetFirstView}\label{wxdocumentgetfirstview}
|
|
|
|
\constfunc{wxView *}{GetFirstView}{\void}
|
|
|
|
A convenience function to get the first view for a document, because
|
|
in many cases a document will only have a single view.
|
|
|
|
See also: \helpref{GetViews}{wxdocumentgetviews}
|
|
|
|
\membersection{wxDocument::GetUserReadableName}\label{wxdocumentgetuserreadablentablename}
|
|
|
|
\constfunc{virtual wxString}{GetUserReadableName}{\void}
|
|
|
|
Return the document name suitable to be shown to the user. The default
|
|
implementation uses the document title, if any, of the name part of the
|
|
document filename if it was set or, otherwise, the string {\bf unnamed}.
|
|
|
|
\membersection{wxDocument::GetTitle}\label{wxdocumentgettitle}
|
|
|
|
\constfunc{wxString}{GetTitle}{\void}
|
|
|
|
Gets the title for this document. The document title is used for an associated
|
|
frame (if any), and is usually constructed by the framework from
|
|
the filename.
|
|
|
|
\membersection{wxDocument::GetViews}\label{wxdocumentgetviews}
|
|
|
|
\constfunc{wxList \&}{GetViews}{\void}
|
|
|
|
Returns the list whose elements are the views on the document.
|
|
|
|
See also: \helpref{GetFirstView}{wxdocumentgetfirstview}
|
|
|
|
\membersection{wxDocument::IsModified}\label{wxdocumentismodified}
|
|
|
|
\constfunc{virtual bool}{IsModified}{\void}
|
|
|
|
Returns true if the document has been modified since the last save, false otherwise.
|
|
You may need to override this if your document view maintains its own
|
|
record of being modified (for example if using wxTextWindow to view and edit the document).
|
|
|
|
See also \helpref{Modify}{wxdocumentmodify}.
|
|
|
|
\membersection{wxDocument::LoadObject}\label{wxdocumentloadobject}
|
|
|
|
\func{virtual istream\&}{LoadObject}{\param{istream\& }{stream}}
|
|
|
|
\func{virtual wxInputStream\&}{LoadObject}{\param{wxInputStream\& }{stream}}
|
|
|
|
Override this function and call it from your own LoadObject before
|
|
streaming your own data. LoadObject is called by the framework
|
|
automatically when the document contents need to be loaded.
|
|
|
|
Note that only one of these forms exists, depending on how wxWidgets
|
|
was configured.
|
|
|
|
\membersection{wxDocument::Modify}\label{wxdocumentmodify}
|
|
|
|
\func{virtual void}{Modify}{\param{bool}{ modify}}
|
|
|
|
Call with true to mark the document as modified since the last save, false otherwise.
|
|
You may need to override this if your document view maintains its own
|
|
record of being modified (for example if using wxTextWindow to view and edit the document).
|
|
|
|
See also \helpref{IsModified}{wxdocumentismodified}.
|
|
|
|
\membersection{wxDocument::OnChangedViewList}\label{wxdocumentonchangedviewlist}
|
|
|
|
\func{virtual void}{OnChangedViewList}{\void}
|
|
|
|
Called when a view is added to or deleted from this document. The default
|
|
implementation saves and deletes the document if no views exist (the last
|
|
one has just been removed).
|
|
|
|
\membersection{wxDocument::OnCloseDocument}\label{wxdocumentonclosedocument}
|
|
|
|
\func{virtual bool}{OnCloseDocument}{\void}
|
|
|
|
The default implementation calls DeleteContents (an empty implementation)
|
|
sets the modified flag to false. Override this to
|
|
supply additional behaviour when the document is closed with Close.
|
|
|
|
\membersection{wxDocument::OnCreate}\label{wxdocumentoncreate}
|
|
|
|
\func{virtual bool}{OnCreate}{\param{const wxString\& }{path}, \param{long}{ flags}}
|
|
|
|
Called just after the document object is created to give it a chance
|
|
to initialize itself. The default implementation uses the
|
|
template associated with the document to create an initial view.
|
|
If this function returns false, the document is deleted.
|
|
|
|
\membersection{wxDocument::OnCreateCommandProcessor}\label{wxdocumentoncreatecommandprocessor}
|
|
|
|
\func{virtual wxCommandProcessor*}{OnCreateCommandProcessor}{\void}
|
|
|
|
Override this function if you want a different (or no) command processor
|
|
to be created when the document is created. By default, it returns
|
|
an instance of wxCommandProcessor.
|
|
|
|
See \helpref{wxCommandProcessor}{wxcommandprocessor}.
|
|
|
|
\membersection{wxDocument::OnNewDocument}\label{wxdocumentonnewdocument}
|
|
|
|
\func{virtual bool}{OnNewDocument}{\void}
|
|
|
|
The default implementation calls OnSaveModified and DeleteContents, makes a default title for the
|
|
document, and notifies the views that the filename (in fact, the title) has changed.
|
|
|
|
\membersection{wxDocument::OnOpenDocument}\label{wxdocumentonopendocument}
|
|
|
|
\func{virtual bool}{OnOpenDocument}{\param{const wxString\& }{filename}}
|
|
|
|
Constructs an input file stream for the given filename (which must not be empty),
|
|
and calls LoadObject. If LoadObject returns true, the document is set to
|
|
unmodified; otherwise, an error message box is displayed. The document's
|
|
views are notified that the filename has changed, to give windows an opportunity
|
|
to update their titles. All of the document's views are then updated.
|
|
|
|
\membersection{wxDocument::OnSaveDocument}\label{wxdocumentonsavedocument}
|
|
|
|
\func{virtual bool}{OnSaveDocument}{\param{const wxString\& }{filename}}
|
|
|
|
Constructs an output file stream for the given filename (which must not be empty),
|
|
and calls SaveObject. If SaveObject returns true, the document is set to
|
|
unmodified; otherwise, an error message box is displayed.
|
|
|
|
\membersection{wxDocument::OnSaveModified}\label{wxdocumentonsavemodified}
|
|
|
|
\func{virtual bool}{OnSaveModified}{\void}
|
|
|
|
If the document has been modified, prompts the user to ask if the changes should
|
|
be changed. If the user replies Yes, the Save function is called. If No, the
|
|
document is marked as unmodified and the function succeeds. If Cancel, the
|
|
function fails.
|
|
|
|
\membersection{wxDocument::RemoveView}\label{wxdocumentremoveview}
|
|
|
|
\func{virtual bool}{RemoveView}{\param{wxView* }{view}}
|
|
|
|
Removes the view from the document's list of views, and calls OnChangedViewList.
|
|
|
|
\membersection{wxDocument::Save}\label{wxdocumentsave}
|
|
|
|
\func{virtual bool}{Save}{\void}
|
|
|
|
Saves the document by calling OnSaveDocument if there is an associated filename,
|
|
or SaveAs if there is no filename.
|
|
|
|
\membersection{wxDocument::SaveAs}\label{wxdocumentsaveas}
|
|
|
|
\func{virtual bool}{SaveAs}{\void}
|
|
|
|
Prompts the user for a file to save to, and then calls OnSaveDocument.
|
|
|
|
\membersection{wxDocument::SaveObject}\label{wxdocumentsaveobject}
|
|
|
|
\func{virtual ostream\&}{SaveObject}{\param{ostream\& }{stream}}
|
|
|
|
\func{virtual wxOutputStream\&}{SaveObject}{\param{wxOutputStream\& }{stream}}
|
|
|
|
Override this function and call it from your own SaveObject before
|
|
streaming your own data. SaveObject is called by the framework
|
|
automatically when the document contents need to be saved.
|
|
|
|
Note that only one of these forms exists, depending on how wxWidgets
|
|
was configured.
|
|
|
|
\membersection{wxDocument::SetCommandProcessor}\label{wxdocumentsetcommandprocessor}
|
|
|
|
\func{virtual void}{SetCommandProcessor}{\param{wxCommandProcessor *}{processor}}
|
|
|
|
Sets the command processor to be used for this document. The document will then be responsible
|
|
for its deletion. Normally you should not call this; override OnCreateCommandProcessor
|
|
instead.
|
|
|
|
See \helpref{wxCommandProcessor}{wxcommandprocessor}.
|
|
|
|
\membersection{wxDocument::SetDocumentName}\label{wxdocumentsetdocumentname}
|
|
|
|
\func{void}{SetDocumentName}{\param{const wxString\& }{name}}
|
|
|
|
Sets the document type name for this document. See the comment for \helpref{documentTypeName}{documenttypename}.
|
|
|
|
\membersection{wxDocument::SetDocumentTemplate}\label{wxdocumentsetdocumenttemplate}
|
|
|
|
\func{void}{SetDocumentTemplate}{\param{wxDocTemplate* }{templ}}
|
|
|
|
Sets the pointer to the template that created the document. Should only be called by the
|
|
framework.
|
|
|
|
\membersection{wxDocument::SetFilename}\label{wxdocumentsetfilename}
|
|
|
|
\func{void}{SetFilename}{\param{const wxString\& }{filename}, \param{bool}{ notifyViews = false}}
|
|
|
|
Sets the filename for this document. Usually called by the framework.
|
|
|
|
If {\it notifyViews} is true, wxView::OnChangeFilename is called for all views.
|
|
|
|
\membersection{wxDocument::SetTitle}\label{wxdocumentsettitle}
|
|
|
|
\func{void}{SetTitle}{\param{const wxString\& }{title}}
|
|
|
|
Sets the title for this document. The document title is used for an associated
|
|
frame (if any), and is usually constructed by the framework from
|
|
the filename.
|
|
|
|
\membersection{wxDocument::UpdateAllViews}\label{wxdocumentupdateallviews}
|
|
|
|
\func{void}{UpdateAllViews}{\param{wxView* }{sender = NULL}, \param{wxObject*}{ hint = NULL}}
|
|
|
|
Updates all views. If {\it sender} is non-NULL, does not update this view.
|
|
|
|
{\it hint} represents optional information to allow a view to optimize its update.
|
|
|