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