]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/docmanag.tex
* wxStream fixes (integer/line parsing).
[wxWidgets.git] / docs / latex / wx / docmanag.tex
1 \section{\class{wxDocManager}}\label{wxdocmanager}
2
3 The wxDocManager class is part of the document/view framework supported by wxWindows,
4 and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}\rtfsp
5 and \helpref{wxDocTemplate}{wxdoctemplate} classes.
6
7 \wxheading{Derived from}
8
9 \helpref{wxEvtHandler}{wxevthandler}\\
10 \helpref{wxObject}{wxobject}
11
12 \wxheading{Include files}
13
14 <wx/docview.h>
15
16 \wxheading{See also}
17
18 \helpref{wxDocManager overview}{wxdocmanageroverview}, \helpref{wxDocument}{wxdocument},\rtfsp
19 \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}, \helpref{wxFileHistory}{wxfilehistory}
20
21 \latexignore{\rtfignore{\wxheading{Members}}}
22
23 \membersection{wxDocManager::m\_currentView}
24
25 \member{wxView*}{m\_currentView}
26
27 The currently active view.
28
29 \membersection{wxDocManager::m\_defaultDocumentNameCounter}
30
31 \member{int}{m\_defaultDocumentNameCounter}
32
33 Stores the integer to be used for the next default document name.
34
35 \membersection{wxDocManager::m\_fileHistory}
36
37 \member{wxFileHistory*}{m\_fileHistory}
38
39 A pointer to an instance of \helpref{wxFileHistory}{wxfilehistory},
40 which manages the history of recently-visited files on the File menu.
41
42 \membersection{wxDocManager::m\_maxDocsOpen}
43
44 \member{int}{m\_maxDocsOpen}
45
46 Stores the maximum number of documents that can be opened before
47 existing documents are closed. By default, this is 10,000.
48
49 \membersection{wxDocManager::m\_docs}
50
51 \member{wxList}{m\_docs}
52
53 A list of all documents.
54
55 \membersection{wxDocManager::m\_flags}
56
57 \member{long}{m\_flags}
58
59 Stores the flags passed to the constructor.
60
61 \membersection{wxDocManager::m\_templates}
62
63 \member{wxList}{mnTemplates}
64
65 A list of all document templates.
66
67 \membersection{wxDocManager::wxDocManager}
68
69 \func{void}{wxDocManager}{\param{long}{ flags = wxDEFAULT\_DOCMAN\_FLAGS}, \param{bool}{ initialize = TRUE}}
70
71 Constructor. Create a document manager instance dynamically near the start of your application
72 before doing any document or view operations.
73
74 {\it flags} is currently unused.
75
76 If {\it initialize} is TRUE, the \helpref{Initialize}{wxdocmanagerinitialize} function will be called
77 to create a default history list object. If you derive from wxDocManager, you may wish to call the
78 base constructor with FALSE, and then call Initialize in your own constructor, to allow
79 your own Initialize or OnCreateFileHistory functions to be called.
80
81 \membersection{wxDocManager::\destruct{wxDocManager}}
82
83 \func{void}{\destruct{wxDocManager}}{\void}
84
85 Destructor.
86
87 \membersection{wxDocManager::ActivateView}
88
89 \func{void}{ActivateView}{\param{wxView* }{doc}, \param{bool}{ activate}, \param{bool}{ deleting}}
90
91 Sets the current view.
92
93 \membersection{wxDocManager::AddDocument}
94
95 \func{void}{AddDocument}{\param{wxDocument *}{doc}}
96
97 Adds the document to the list of documents.
98
99 \membersection{wxDocManager::AddFileToHistory}
100
101 \func{void}{AddFileToHistory}{\param{const wxString\& }{filename}}
102
103 Adds a file to the file history list, if we have a pointer to an appropriate file menu.
104
105 \membersection{wxDocManager::AssociateTemplate}
106
107 \func{void}{AssociateTemplate}{\param{wxDocTemplate *}{temp}}
108
109 Adds the template to the document manager's template list.
110
111 \membersection{wxDocManager::CreateDocument}
112
113 \func{wxDocument*}{CreateDocument}{\param{const wxString\& }{path}, \param{long}{ flags}}
114
115 Creates a new document in a manner determined by the {\it flags} parameter, which can be:
116
117 \begin{itemize}\itemsep=0pt
118 \item wxDOC\_NEW Creates a fresh document.
119 \item wxDOC\_SILENT Silently loads the given document file.
120 \end{itemize}
121
122 If wxDOC\_NEW is present, a new document will be created and returned, possibly after
123 asking the user for a template to use if there is more than one document template.
124 If wxDOC\_SILENT is present, a new document will be created and the given file loaded
125 into it. If neither of these flags is present, the user will be presented with
126 a file selector for the file to load, and the template to use will be determined by the
127 extension (Windows) or by popping up a template choice list (other platforms).
128
129 If the maximum number of documents has been reached, this function
130 will delete the oldest currently loaded document before creating a new one.
131
132 \membersection{wxDocManager::CreateView}
133
134 \func{wxView*}{CreateView}{\param{wxDocument*}{doc}, \param{long}{ flags}}
135
136 Creates a new view for the given document. If more than one view is allowed for the
137 document (by virtue of multiple templates mentioning the same document type), a choice
138 of view is presented to the user.
139
140 \membersection{wxDocManager::DisassociateTemplate}
141
142 \func{void}{DisassociateTemplate}{\param{wxDocTemplate *}{temp}}
143
144 Removes the template from the list of templates.
145
146 \membersection{wxDocManager::FileHistoryAddFilesToMenu}\label{wxdocmanagerfilehistoryaddfilestomenu}
147
148 \func{void}{FileHistoryAddFilesToMenu}{\void}
149
150 Appends the files in the history list, to all menus managed by the file history object.
151
152 \func{void}{FileHistoryAddFilesToMenu}{\param{wxMenu*}{ menu}}
153
154 Appends the files in the history list, to the given menu only.
155
156 \membersection{wxDocManager::FileHistoryLoad}\label{wxdocmanagerfilehistoryload}
157
158 \func{void}{FileHistoryLoad}{\param{wxConfigBase\& }{config}}
159
160 Loads the file history from a config object.
161
162 \wxheading{See also}
163
164 \helpref{wxConfig}{wxconfigbase}
165
166 \membersection{wxDocManager::FileHistoryRemoveMenu}\label{wxdocmanagerfilehistoryremovemenu}
167
168 \func{void}{FileHistoryRemoveMenu}{\param{wxMenu*}{ menu}}
169
170 Removes the given menu from the list of menus managed by the file history object.
171
172 \membersection{wxDocManager::FileHistorySave}\label{wxdocmanagerfilehistorysave}
173
174 \func{void}{FileHistorySave}{\param{wxConfigBase\& }{resourceFile}}
175
176 Saves the file history into a config object. This must be called
177 explicitly by the application.
178
179 \wxheading{See also}
180
181 \helpref{wxConfig}{wxconfigbase}
182
183 \membersection{wxDocManager::FileHistoryUseMenu}\label{wxdocmanagerfilehistoryusemenu}
184
185 \func{void}{FileHistoryUseMenu}{\param{wxMenu*}{ menu}}
186
187 Use this menu for appending recently-visited document filenames, for convenient
188 access. Calling this function with a valid menu pointer enables the history
189 list functionality.
190
191 Note that you can add multiple menus using this function, to be managed by the
192 file history object.
193
194 \membersection{wxDocManager::FindTemplateForPath}
195
196 \func{wxDocTemplate *}{FindTemplateForPath}{\param{const wxString\& }{path}}
197
198 Given a path, try to find template that matches the extension. This is only
199 an approximate method of finding a template for creating a document.
200
201 \membersection{wxDocManager::GetCurrentDocument}
202
203 \func{wxDocument *}{GetCurrentDocument}{\void}
204
205 Returns the document associated with the currently active view (if any).
206
207 \membersection{wxDocManager::GetCurrentView}
208
209 \func{wxView *}{GetCurrentView}{\void}
210
211 Returns the currently active view
212
213 \membersection{wxDocManager::GetDocuments}
214
215 \func{wxList\&}{GetDocuments}{\void}
216
217 Returns a reference to the list of documents.
218
219 \membersection{wxDocManager::GetFileHistory}
220
221 \func{wxFileHistory *}{GetFileHistory}{\void}
222
223 Returns a pointer to file history.
224
225 \membersection{wxDocManager::GetMaxDocsOpen}
226
227 \func{int}{GetMaxDocsOpen}{\void}
228
229 Returns the number of documents that can be open simultaneously.
230
231 \membersection{wxDocManager::GetNoHistoryFiles}
232
233 \func{int}{GetNoHistoryFiles}{\void}
234
235 Returns the number of files currently stored in the file history.
236
237 \membersection{wxDocManager::Initialize}\label{wxdocmanagerinitialize}
238
239 \func{bool}{Initialize}{\void}
240
241 Initializes data; currently just calls OnCreateFileHistory. Some data cannot
242 always be initialized in the constructor because the programmer must be given
243 the opportunity to override functionality. If OnCreateFileHistory was called
244 from the constructor, an overridden virtual OnCreateFileHistory would not be
245 called due to C++'s `interesting' constructor semantics. In fact Initialize
246 \rtfsp{\it is} called from the wxDocManager constructor, but this can be
247 vetoed by passing FALSE to the second argument, allowing the derived class's
248 constructor to call Initialize, possibly calling a different OnCreateFileHistory
249 from the default.
250
251 The bottom line: if you're not deriving from Initialize, forget it and
252 construct wxDocManager with no arguments.
253
254 \membersection{wxDocManager::MakeDefaultName}
255
256 \func{bool}{MakeDefaultName}{\param{const wxString\& }{buf}}
257
258 Copies a suitable default name into {\it buf}. This is implemented by
259 appending an integer counter to the string {\bf unnamed} and incrementing
260 the counter.
261
262 \membersection{wxDocManager::OnCreateFileHistory}
263
264 \func{wxFileHistory *}{OnCreateFileHistory}{\void}
265
266 A hook to allow a derived class to create a different type of file history. Called
267 from \helpref{Initialize}{wxdocmanagerinitialize}.
268
269 \membersection{wxDocManager::OnFileClose}
270
271 \func{void}{OnFileClose}{\void}
272
273 Closes and deletes the currently active document.
274
275 \membersection{wxDocManager::OnFileNew}
276
277 \func{void}{OnFileNew}{\void}
278
279 Creates a document from a list of templates (if more than one template).
280
281 \membersection{wxDocManager::OnFileOpen}
282
283 \func{void}{OnFileOpen}{\void}
284
285 Creates a new document and reads in the selected file.
286
287 \membersection{wxDocManager::OnFileSave}
288
289 \func{void}{OnFileSave}{\void}
290
291 Saves the current document by calling wxDocument::Save for the current document.
292
293 \membersection{wxDocManager::OnFileSaveAs}
294
295 \func{void}{OnFileSaveAs}{\void}
296
297 Calls wxDocument::SaveAs for the current document.
298
299 \membersection{wxDocManager::OnMenuCommand}
300
301 \func{void}{OnMenuCommand}{\param{int}{ cmd}}
302
303 Processes menu commands routed from child or parent frames. This deals
304 with the following predefined menu item identifiers:
305
306 \begin{itemize}\itemsep=0pt
307 \item wxID\_OPEN Creates a new document and opens a file into it.
308 \item wxID\_CLOSE Closes the current document.
309 \item wxID\_NEW Creates a new document.
310 \item wxID\_SAVE Saves the document.
311 \item wxID\_SAVE\_AS Saves the document into a specified filename.
312 \end{itemize}
313
314 Unrecognized commands are routed to the currently active wxView's OnMenuCommand.
315
316 \membersection{wxDocManager::RemoveDocument}
317
318 \func{void}{RemoveDocument}{\param{wxDocument *}{doc}}
319
320 Removes the document from the list of documents.
321
322 \membersection{wxDocManager::SelectDocumentPath}
323
324 \func{wxDocTemplate *}{SelectDocumentPath}{\param{wxDocTemplate **}{templates},
325 \param{int}{ noTemplates}, \param{const wxString\& }{path}, \param{const wxString\& }{bufSize},
326 \param{long}{ flags}, \param{bool}{ save}}
327
328 Under Windows, pops up a file selector with a list of filters corresponding to document templates.
329 The wxDocTemplate corresponding to the selected file's extension is returned.
330
331 On other platforms, if there is more than one document template a choice list is popped up,
332 followed by a file selector.
333
334 This function is used in wxDocManager::CreateDocument.
335
336 \membersection{wxDocManager::SelectDocumentType}
337
338 \func{wxDocTemplate *}{SelectDocumentType}{\param{wxDocTemplate **}{templates},
339 \param{int}{ noTemplates}}
340
341 Returns a document template by asking the user (if there is more than one template).
342 This function is used in wxDocManager::CreateDocument.
343
344 \membersection{wxDocManager::SelectViewType}
345
346 \func{wxDocTemplate *}{SelectViewType}{\param{wxDocTemplate **}{templates},
347 \param{int}{ noTemplates}}
348
349 Returns a document template by asking the user (if there is more than one template),
350 displaying a list of valid views. This function is used in wxDocManager::CreateView.
351 The dialog normally won't appear because the array of templates only contains
352 those relevant to the document in question, and often there will only be one such.
353
354 \membersection{wxDocManager::SetMaxDocsOpen}
355
356 \func{void}{SetMaxDocsOpen}{\param{int}{ n}}
357
358 Sets the maximum number of documents that can be open at a time. By default, this
359 is 10,000. If you set it to 1, existing documents will be saved and deleted
360 when the user tries to open or create a new one (similar to the behaviour
361 of Windows Write, for example). Allowing multiple documents gives behaviour
362 more akin to MS Word and other Multiple Document Interface applications.
363
364
365