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