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