1\section{\class{wxDocument}}\label{wxdocument} 2 3The document class can be used to model an application's file-based 4data. It is part of the document/view framework supported by wxWidgets, 5and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}\rtfsp 6and \helpref{wxDocManager}{wxdocmanager} classes. 7 8\wxheading{Derived from} 9 10\helpref{wxEvtHandler}{wxevthandler}\\ 11\helpref{wxObject}{wxobject} 12 13\wxheading{Include files} 14 15<wx/docview.h> 16 17\wxheading{See also} 18 19\helpref{wxDocument overview}{wxdocumentoverview}, \helpref{wxView}{wxview},\rtfsp 20\helpref{wxDocTemplate}{wxdoctemplate}, \helpref{wxDocManager}{wxdocmanager} 21 22\latexignore{\rtfignore{\wxheading{Members}}} 23 24\membersection{wxDocument::m\_commandProcessor}\label{wxdocumentmcommandprocessor} 25 26\member{wxCommandProcessor*}{m\_commandProcessor} 27 28A pointer to the command processor associated with this document. 29 30\membersection{wxDocument::m\_documentFile}\label{wxdocumentmdocumentfile} 31 32\member{wxString}{m\_documentFile} 33 34Filename associated with this document (``" if none). 35 36\membersection{wxDocument::m\_documentModified}\label{wxdocumentmdocumentmodified} 37 38\member{bool}{m\_documentModified} 39 40true if the document has been modified, false otherwise. 41 42\membersection{wxDocument::m\_documentTemplate}\label{wxdocumentmdocumenttemplate} 43 44\member{wxDocTemplate *}{m\_documentTemplate} 45 46A pointer to the template from which this document was created. 47 48\membersection{wxDocument::m\_documentTitle}\label{wxdocumentmdocumenttitle} 49 50\member{wxString}{m\_documentTitle} 51 52Document title. The document title is used for an associated 53frame (if any), and is usually constructed by the framework from 54the filename. 55 56\membersection{wxDocument::m\_documentTypeName}\label{documenttypename} 57 58\member{wxString}{m\_documentTypeName} 59 60The document type name given to the wxDocTemplate constructor, copied to this 61variable when the document is created. If several document templates are 62created that use the same document type, this variable is used in wxDocManager::CreateView 63to collate a list of alternative view types that can be used on this kind of 64document. Do not change the value of this variable. 65 66\membersection{wxDocument::m\_documentViews}\label{wxdocumentmdocumentviews} 67 68\member{wxList}{m\_documentViews} 69 70List of wxView instances associated with this document. 71 72\membersection{wxDocument::wxDocument}\label{wxdocumentctor} 73 74\func{}{wxDocument}{\void} 75 76Constructor. Define your own default constructor to initialize application-specific 77data. 78 79\membersection{wxDocument::\destruct{wxDocument}}\label{wxdocumentdtor} 80 81\func{}{\destruct{wxDocument}}{\void} 82 83Destructor. Removes itself from the document manager. 84 85\membersection{wxDocument::AddView}\label{wxdocumentaddview} 86 87\func{virtual bool}{AddView}{\param{wxView *}{view}} 88 89If the view is not already in the list of views, adds the view and calls OnChangedViewList. 90 91\membersection{wxDocument::Close}\label{wxdocumentclose} 92 93\func{virtual bool}{Close}{\void} 94 95Closes the document, by calling OnSaveModified and then (if this returned true) OnCloseDocument. 96This does not normally delete the document object: use DeleteAllViews to do this implicitly. 97 98\membersection{wxDocument::DeleteAllViews}\label{wxdocumentdeleteviews} 99 100\func{virtual bool}{DeleteAllViews}{\void} 101 102Calls wxView::Close and deletes each view. Deleting the final view will implicitly 103delete the document itself, because the wxView destructor calls RemoveView. This 104in turns calls wxDocument::OnChangedViewList, whose default implemention is to 105save and delete the document if no views exist. 106 107\membersection{wxDocument::GetCommandProcessor}\label{wxdocumentgetcommandprocessor} 108 109\constfunc{wxCommandProcessor*}{GetCommandProcessor}{\void} 110 111Returns a pointer to the command processor associated with this document. 112 113See \helpref{wxCommandProcessor}{wxcommandprocessor}. 114 115\membersection{wxDocument::GetDocumentTemplate}\label{wxdocumentgetdocumenttemplate} 116 117\constfunc{wxDocTemplate*}{GetDocumentTemplate}{\void} 118 119Gets a pointer to the template that created the document. 120 121\membersection{wxDocument::GetDocumentManager}\label{wxdocumentgetdocumentmanager} 122 123\constfunc{wxDocManager*}{GetDocumentManager}{\void} 124 125Gets a pointer to the associated document manager. 126 127\membersection{wxDocument::GetDocumentName}\label{wxdocumentgetdocumentname} 128 129\constfunc{wxString}{GetDocumentName}{\void} 130 131Gets the document type name for this document. See the comment for \helpref{documentTypeName}{documenttypename}. 132 133\membersection{wxDocument::GetDocumentWindow}\label{wxdocumentgetdocumentwindow} 134 135\constfunc{wxWindow*}{GetDocumentWindow}{\void} 136 137Intended to return a suitable window for using as a parent for document-related 138dialog boxes. By default, uses the frame associated with the first view. 139 140\membersection{wxDocument::GetFilename}\label{wxdocumentgetfilename} 141 142\constfunc{wxString}{GetFilename}{\void} 143 144Gets the filename associated with this document, or "" if none is 145associated. 146 147\membersection{wxDocument::GetFirstView}\label{wxdocumentgetfirstview} 148 149\constfunc{wxView *}{GetFirstView}{\void} 150 151A convenience function to get the first view for a document, because 152in many cases a document will only have a single view. 153 154See also: \helpref{GetViews}{wxdocumentgetviews} 155 156\membersection{wxDocument::GetPrintableName}\label{wxdocumentgetprintablename} 157 158\constfunc{virtual void}{GetPrintableName}{\param{wxString\& }{name}} 159 160Copies a suitable document name into the supplied {\it name} buffer. The default 161function uses the title, or if there is no title, uses the filename; or if no 162filename, the string {\bf unnamed}. 163 164\perlnote{In wxPerl this function must return the modified name rather 165than just modifying the argument.} 166 167\membersection{wxDocument::GetTitle}\label{wxdocumentgettitle} 168 169\constfunc{wxString}{GetTitle}{\void} 170 171Gets the title for this document. The document title is used for an associated 172frame (if any), and is usually constructed by the framework from 173the filename. 174 175\membersection{wxDocument::GetViews}\label{wxdocumentgetviews} 176 177\constfunc{wxList \&}{GetViews}{\void} 178 179Returns the list whose elements are the views on the document. 180 181See also: \helpref{GetFirstView}{wxdocumentgetfirstview} 182 183\membersection{wxDocument::IsModified}\label{wxdocumentismodified} 184 185\constfunc{virtual bool}{IsModified}{\void} 186 187Returns true if the document has been modified since the last save, false otherwise. 188You may need to override this if your document view maintains its own 189record of being modified (for example if using wxTextWindow to view and edit the document). 190 191See also \helpref{Modify}{wxdocumentmodify}. 192 193\membersection{wxDocument::LoadObject}\label{wxdocumentloadobject} 194 195\func{virtual istream\&}{LoadObject}{\param{istream\& }{stream}} 196 197\func{virtual wxInputStream\&}{LoadObject}{\param{wxInputStream\& }{stream}} 198 199Override this function and call it from your own LoadObject before 200streaming your own data. LoadObject is called by the framework 201automatically when the document contents need to be loaded. 202 203Note that only one of these forms exists, depending on how wxWidgets 204was configured. 205 206\membersection{wxDocument::Modify}\label{wxdocumentmodify} 207 208\func{virtual void}{Modify}{\param{bool}{ modify}} 209 210Call with true to mark the document as modified since the last save, false otherwise. 211You may need to override this if your document view maintains its own 212record of being modified (for example if using wxTextWindow to view and edit the document). 213 214See also \helpref{IsModified}{wxdocumentismodified}. 215 216\membersection{wxDocument::OnChangedViewList}\label{wxdocumentonchangedviewlist} 217 218\func{virtual void}{OnChangedViewList}{\void} 219 220Called when a view is added to or deleted from this document. The default 221implementation saves and deletes the document if no views exist (the last 222one has just been removed). 223 224\membersection{wxDocument::OnCloseDocument}\label{wxdocumentonclosedocument} 225 226\func{virtual bool}{OnCloseDocument}{\void} 227 228The default implementation calls DeleteContents (an empty implementation) 229sets the modified flag to false. Override this to 230supply additional behaviour when the document is closed with Close. 231 232\membersection{wxDocument::OnCreate}\label{wxdocumentoncreate} 233 234\func{virtual bool}{OnCreate}{\param{const wxString\& }{path}, \param{long}{ flags}} 235 236Called just after the document object is created to give it a chance 237to initialize itself. The default implementation uses the 238template associated with the document to create an initial view. 239If this function returns false, the document is deleted. 240 241\membersection{wxDocument::OnCreateCommandProcessor}\label{wxdocumentoncreatecommandprocessor} 242 243\func{virtual wxCommandProcessor*}{OnCreateCommandProcessor}{\void} 244 245Override this function if you want a different (or no) command processor 246to be created when the document is created. By default, it returns 247an instance of wxCommandProcessor. 248 249See \helpref{wxCommandProcessor}{wxcommandprocessor}. 250 251\membersection{wxDocument::OnNewDocument}\label{wxdocumentonnewdocument} 252 253\func{virtual bool}{OnNewDocument}{\void} 254 255The default implementation calls OnSaveModified and DeleteContents, makes a default title for the 256document, and notifies the views that the filename (in fact, the title) has changed. 257 258\membersection{wxDocument::OnOpenDocument}\label{wxdocumentonopendocument} 259 260\func{virtual bool}{OnOpenDocument}{\param{const wxString\& }{filename}} 261 262Constructs an input file stream for the given filename (which must not be empty), 263and calls LoadObject. If LoadObject returns true, the document is set to 264unmodified; otherwise, an error message box is displayed. The document's 265views are notified that the filename has changed, to give windows an opportunity 266to update their titles. All of the document's views are then updated. 267 268\membersection{wxDocument::OnSaveDocument}\label{wxdocumentonsavedocument} 269 270\func{virtual bool}{OnSaveDocument}{\param{const wxString\& }{filename}} 271 272Constructs an output file stream for the given filename (which must not be empty), 273and calls SaveObject. If SaveObject returns true, the document is set to 274unmodified; otherwise, an error message box is displayed. 275 276\membersection{wxDocument::OnSaveModified}\label{wxdocumentonsavemodified} 277 278\func{virtual bool}{OnSaveModified}{\void} 279 280If the document has been modified, prompts the user to ask if the changes should 281be changed. If the user replies Yes, the Save function is called. If No, the 282document is marked as unmodified and the function succeeds. If Cancel, the 283function fails. 284 285\membersection{wxDocument::RemoveView}\label{wxdocumentremoveview} 286 287\func{virtual bool}{RemoveView}{\param{wxView* }{view}} 288 289Removes the view from the document's list of views, and calls OnChangedViewList. 290 291\membersection{wxDocument::Save}\label{wxdocumentsave} 292 293\func{virtual bool}{Save}{\void} 294 295Saves the document by calling OnSaveDocument if there is an associated filename, 296or SaveAs if there is no filename. 297 298\membersection{wxDocument::SaveAs}\label{wxdocumentsaveas} 299 300\func{virtual bool}{SaveAs}{\void} 301 302Prompts the user for a file to save to, and then calls OnSaveDocument. 303 304\membersection{wxDocument::SaveObject}\label{wxdocumentsaveobject} 305 306\func{virtual ostream\&}{SaveObject}{\param{ostream\& }{stream}} 307 308\func{virtual wxOutputStream\&}{SaveObject}{\param{wxOutputStream\& }{stream}} 309 310Override this function and call it from your own SaveObject before 311streaming your own data. SaveObject is called by the framework 312automatically when the document contents need to be saved. 313 314Note that only one of these forms exists, depending on how wxWidgets 315was configured. 316 317\membersection{wxDocument::SetCommandProcessor}\label{wxdocumentsetcommandprocessor} 318 319\func{virtual void}{SetCommandProcessor}{\param{wxCommandProcessor *}{processor}} 320 321Sets the command processor to be used for this document. The document will then be responsible 322for its deletion. Normally you should not call this; override OnCreateCommandProcessor 323instead. 324 325See \helpref{wxCommandProcessor}{wxcommandprocessor}. 326 327\membersection{wxDocument::SetDocumentName}\label{wxdocumentsetdocumentname} 328 329\func{void}{SetDocumentName}{\param{const wxString\& }{name}} 330 331Sets the document type name for this document. See the comment for \helpref{documentTypeName}{documenttypename}. 332 333\membersection{wxDocument::SetDocumentTemplate}\label{wxdocumentsetdocumenttemplate} 334 335\func{void}{SetDocumentTemplate}{\param{wxDocTemplate* }{templ}} 336 337Sets the pointer to the template that created the document. Should only be called by the 338framework. 339 340\membersection{wxDocument::SetFilename}\label{wxdocumentsetfilename} 341 342\func{void}{SetFilename}{\param{const wxString\& }{filename}, \param{bool}{ notifyViews = false}} 343 344Sets the filename for this document. Usually called by the framework. 345 346If {\it notifyViews} is true, wxView::OnChangeFilename is called for all views. 347 348\membersection{wxDocument::SetTitle}\label{wxdocumentsettitle} 349 350\func{void}{SetTitle}{\param{const wxString\& }{title}} 351 352Sets the title for this document. The document title is used for an associated 353frame (if any), and is usually constructed by the framework from 354the filename. 355 356\membersection{wxDocument::UpdateAllViews}\label{wxdocumentupdateallviews} 357 358\func{void}{UpdateAllViews}{\param{wxView* }{sender = NULL}, \param{wxObject*}{ hint = NULL}} 359 360Updates all views. If {\it sender} is non-NULL, does not update this view. 361 362{\it hint} represents optional information to allow a view to optimize its update. 363 364