]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: docview.h | |
3 | // Purpose: interface of various doc/view framework classes | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows licence | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxDocTemplate | |
11 | ||
12 | The wxDocTemplate class is used to model the relationship between a | |
13 | document class and a view class. | |
14 | ||
15 | @library{wxcore} | |
16 | @category{docview} | |
17 | ||
18 | @see @ref overview_docview_wxdoctemplate, wxDocument, wxView | |
19 | */ | |
20 | class wxDocTemplate : public wxObject | |
21 | { | |
22 | public: | |
23 | /** | |
24 | Constructor. Create instances dynamically near the start of your | |
25 | application after creating a wxDocManager instance, and before doing | |
26 | any document or view operations. | |
27 | ||
28 | @param manager | |
29 | The document manager object which manages this template. | |
30 | @param descr | |
31 | A short description of what the template is for. This string will | |
32 | be displayed in the file filter list of Windows file selectors. | |
33 | @param filter | |
34 | An appropriate file filter such as "*.txt". | |
35 | @param dir | |
36 | The default directory to use for file selectors. | |
37 | @param ext | |
38 | The default file extension (such as "txt"). | |
39 | @param docTypeName | |
40 | A name that should be unique for a given type of document, used for | |
41 | gathering a list of views relevant to a particular document. | |
42 | @param viewTypeName | |
43 | A name that should be unique for a given view. | |
44 | @param docClassInfo | |
45 | A pointer to the run-time document class information as returned by | |
46 | the wxCLASSINFO() macro, e.g. wxCLASSINFO(MyDocumentClass). If this is | |
47 | not supplied, you will need to derive a new wxDocTemplate class and | |
48 | override the CreateDocument() member to return a new document | |
49 | instance on demand. | |
50 | @param viewClassInfo | |
51 | A pointer to the run-time view class information as returned by the | |
52 | wxCLASSINFO() macro, e.g. wxCLASSINFO(MyViewClass). If this is not | |
53 | supplied, you will need to derive a new wxDocTemplate class and | |
54 | override the CreateView() member to return a new view instance on | |
55 | demand. | |
56 | @param flags | |
57 | A bit list of the following: | |
58 | - wxTEMPLATE_VISIBLE - The template may be displayed to the | |
59 | user in dialogs. | |
60 | - wxTEMPLATE_INVISIBLE - The template may not be displayed to | |
61 | the user in dialogs. | |
62 | - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE. | |
63 | ||
64 | @beginWxPerlOnly | |
65 | ||
66 | In wxPerl @a docClassInfo and @a viewClassInfo can be either | |
67 | @c Wx::ClassInfo objects or strings containing the name of the | |
68 | perl packages which are to be used as @c Wx::Document and | |
69 | @c Wx::View classes (they must have a constructor named new); | |
70 | as an example: | |
71 | ||
72 | - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext, | |
73 | docTypeName, viewTypeName, docClassInfo, viewClassInfo, | |
74 | flags): will construct document and view objects from the | |
75 | class information. | |
76 | - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext, | |
77 | docTypeName, viewTypeName, docClassName, viewClassName, | |
78 | flags): will construct document and view objects from perl | |
79 | packages. | |
80 | - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext, | |
81 | docTypeName, viewTypeName): | |
82 | in this case @c Wx::DocTemplate::CreateDocument() and | |
83 | @c Wx::DocTemplate::CreateView() must be overridden | |
84 | @endWxPerlOnly | |
85 | */ | |
86 | wxDocTemplate(wxDocManager* manager, const wxString& descr, | |
87 | const wxString& filter, const wxString& dir, | |
88 | const wxString& ext, const wxString& docTypeName, | |
89 | const wxString& viewTypeName, wxClassInfo* docClassInfo = 0, | |
90 | wxClassInfo* viewClassInfo = 0, | |
91 | long flags = wxTEMPLATE_VISIBLE); | |
92 | ||
93 | /** | |
94 | Destructor. | |
95 | */ | |
96 | virtual ~wxDocTemplate(); | |
97 | ||
98 | /** | |
99 | Creates a new instance of the associated document class. If you have | |
100 | not supplied a wxClassInfo parameter to the template constructor, you | |
101 | will need to override this function to return an appropriate document | |
102 | instance. | |
103 | ||
104 | This function calls InitDocument() which in turns calls | |
105 | wxDocument::OnCreate(). | |
106 | */ | |
107 | virtual wxDocument* CreateDocument(const wxString& path, long flags = 0); | |
108 | ||
109 | /** | |
110 | Creates a new instance of the associated view class. | |
111 | ||
112 | If you have not supplied a wxClassInfo parameter to the template | |
113 | constructor, you will need to override this function to return an | |
114 | appropriate view instance. | |
115 | ||
116 | If the new view initialization fails, it must call | |
117 | wxDocument::RemoveView() for consistency with the default behaviour of | |
118 | this function. | |
119 | */ | |
120 | virtual wxView* CreateView(wxDocument* doc, long flags = 0); | |
121 | ||
122 | /** | |
123 | This function implements the default (very primitive) format detection | |
124 | which checks if the extension is that of the template. | |
125 | ||
126 | @param path | |
127 | The path to be checked against the template. | |
128 | */ | |
129 | virtual bool FileMatchesTemplate(const wxString& path); | |
130 | ||
131 | /** | |
132 | Returns the default file extension for the document data, as passed to | |
133 | the document template constructor. | |
134 | */ | |
135 | wxString GetDefaultExtension() const; | |
136 | ||
137 | /** | |
138 | Returns the text description of this template, as passed to the | |
139 | document template constructor. | |
140 | */ | |
141 | wxString GetDescription() const; | |
142 | ||
143 | /** | |
144 | Returns the default directory, as passed to the document template | |
145 | constructor. | |
146 | */ | |
147 | wxString GetDirectory() const; | |
148 | ||
149 | /** | |
150 | Returns the run-time class information that allows document | |
151 | instances to be constructed dynamically, as passed to the document | |
152 | template constructor. | |
153 | */ | |
154 | wxClassInfo* GetDocClassInfo() const; | |
155 | ||
156 | /** | |
157 | Returns a pointer to the document manager instance for which this | |
158 | template was created. | |
159 | */ | |
160 | wxDocManager* GetDocumentManager() const; | |
161 | ||
162 | /** | |
163 | Returns the document type name, as passed to the document template | |
164 | constructor. | |
165 | */ | |
166 | virtual wxString GetDocumentName() const; | |
167 | ||
168 | /** | |
169 | Returns the file filter, as passed to the document template | |
170 | constructor. | |
171 | */ | |
172 | wxString GetFileFilter() const; | |
173 | ||
174 | /** | |
175 | Returns the flags, as passed to the document template constructor. | |
176 | */ | |
177 | long GetFlags() const; | |
178 | ||
179 | /** | |
180 | Returns a reference to the wxPageSetupDialogData associated with the | |
181 | printing operations of this document manager. | |
182 | */ | |
183 | //@{ | |
184 | wxPageSetupDialogData& GetPageSetupDialogData(); | |
185 | const wxPageSetupDialogData& GetPageSetupDialogData() const; | |
186 | //@} | |
187 | ||
188 | /** | |
189 | Returns the run-time class information that allows view instances | |
190 | to be constructed dynamically, as passed to the document template | |
191 | constructor. | |
192 | */ | |
193 | wxClassInfo* GetViewClassInfo() const; | |
194 | ||
195 | /** | |
196 | Returns the view type name, as passed to the document template | |
197 | constructor. | |
198 | */ | |
199 | virtual wxString GetViewName() const; | |
200 | ||
201 | /** | |
202 | Initialises the document, calling wxDocument::OnCreate(). | |
203 | ||
204 | This is called from CreateDocument(). | |
205 | ||
206 | If you override this method, notice that you must @em delete the @a doc | |
207 | if its initialization fails for consistency with the default behaviour. | |
208 | ||
209 | @param doc | |
210 | The document to initialize. | |
211 | @param path | |
212 | The associated file path. | |
213 | @param flags | |
214 | Flags passed to CreateDocument(). | |
215 | @return | |
216 | @true if the initialization was successful or @false if it failed | |
217 | in which case @a doc should be deleted by this function. | |
218 | */ | |
219 | virtual bool InitDocument(wxDocument* doc, | |
220 | const wxString& path, | |
221 | long flags = 0); | |
222 | ||
223 | /** | |
224 | Returns @true if the document template can be shown in user dialogs, | |
225 | @false otherwise. | |
226 | */ | |
227 | bool IsVisible() const; | |
228 | ||
229 | /** | |
230 | Sets the default file extension. | |
231 | */ | |
232 | void SetDefaultExtension(const wxString& ext); | |
233 | ||
234 | /** | |
235 | Sets the template description. | |
236 | */ | |
237 | void SetDescription(const wxString& descr); | |
238 | ||
239 | /** | |
240 | Sets the default directory. | |
241 | */ | |
242 | void SetDirectory(const wxString& dir); | |
243 | ||
244 | /** | |
245 | Sets the pointer to the document manager instance for which this | |
246 | template was created. Should not be called by the application. | |
247 | */ | |
248 | void SetDocumentManager(wxDocManager* manager); | |
249 | ||
250 | /** | |
251 | Sets the file filter. | |
252 | */ | |
253 | void SetFileFilter(const wxString& filter); | |
254 | ||
255 | /** | |
256 | Sets the internal document template flags (see the constructor | |
257 | description for more details). | |
258 | */ | |
259 | void SetFlags(long flags); | |
260 | ||
261 | /** | |
262 | The default extension for files of this type. | |
263 | */ | |
264 | wxString m_defaultExt; | |
265 | ||
266 | /** | |
267 | A short description of this template. | |
268 | */ | |
269 | wxString m_description; | |
270 | ||
271 | /** | |
272 | The default directory for files of this type. | |
273 | */ | |
274 | wxString m_directory; | |
275 | ||
276 | /** | |
277 | Run-time class information that allows document instances to be | |
278 | constructed dynamically. | |
279 | */ | |
280 | wxClassInfo* m_docClassInfo; | |
281 | ||
282 | /** | |
283 | The named type of the document associated with this template. | |
284 | */ | |
285 | wxString m_docTypeName; | |
286 | ||
287 | /** | |
288 | A pointer to the document manager for which this template was created. | |
289 | */ | |
290 | wxDocTemplate* m_documentManager; | |
291 | ||
292 | /** | |
293 | The file filter (such as "*.txt") to be used in file selector dialogs. | |
294 | */ | |
295 | wxString m_fileFilter; | |
296 | ||
297 | /** | |
298 | The flags passed to the constructor. | |
299 | */ | |
300 | long m_flags; | |
301 | ||
302 | /** | |
303 | Run-time class information that allows view instances to be constructed | |
304 | dynamically. | |
305 | */ | |
306 | wxClassInfo* m_viewClassInfo; | |
307 | ||
308 | /** | |
309 | The named type of the view associated with this template. | |
310 | */ | |
311 | wxString m_viewTypeName; | |
312 | }; | |
313 | ||
314 | ||
315 | ||
316 | /** | |
317 | @class wxDocManager | |
318 | ||
319 | The wxDocManager class is part of the document/view framework supported by | |
320 | wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate | |
321 | classes. | |
322 | ||
323 | @library{wxcore} | |
324 | @category{docview} | |
325 | ||
326 | @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate, | |
327 | wxFileHistory | |
328 | */ | |
329 | class wxDocManager : public wxEvtHandler | |
330 | { | |
331 | public: | |
332 | /** | |
333 | Constructor. Create a document manager instance dynamically near the | |
334 | start of your application before doing any document or view operations. | |
335 | ||
336 | If @a initialize is @true, the Initialize() function will be called to | |
337 | create a default history list object. If you derive from wxDocManager, | |
338 | you may wish to call the base constructor with @false, and then call | |
339 | Initialize() in your own constructor, to allow your own Initialize() or | |
340 | OnCreateFileHistory functions to be called. | |
341 | ||
342 | @param flags | |
343 | Currently unused. | |
344 | @param initialize | |
345 | Indicates whether Initialize() should be called by this ctor. | |
346 | */ | |
347 | wxDocManager(long flags = 0, bool initialize = true); | |
348 | ||
349 | /** | |
350 | Destructor. | |
351 | */ | |
352 | virtual ~wxDocManager(); | |
353 | ||
354 | /** | |
355 | Sets the current view. | |
356 | */ | |
357 | virtual void ActivateView(wxView* doc, bool activate = true); | |
358 | ||
359 | /** | |
360 | Adds the document to the list of documents. | |
361 | */ | |
362 | void AddDocument(wxDocument* doc); | |
363 | ||
364 | /** | |
365 | Adds a file to the file history list, if we have a pointer to an | |
366 | appropriate file menu. | |
367 | */ | |
368 | virtual void AddFileToHistory(const wxString& filename); | |
369 | ||
370 | /** | |
371 | Adds the template to the document manager's template list. | |
372 | */ | |
373 | void AssociateTemplate(wxDocTemplate* temp); | |
374 | ||
375 | /** | |
376 | Search for a particular document template. | |
377 | ||
378 | Example: | |
379 | @code | |
380 | // creating a document instance of the specified document type: | |
381 | m_doc = (MyDoc*)docManager->FindTemplate(CLASSINFO(MyDoc))-> | |
382 | CreateDocument(wxEmptyString, wxDOC_SILENT); | |
383 | @endcode | |
384 | ||
385 | @param classinfo | |
386 | Class info of a document class for which a wxDocTemplate had been | |
387 | previously created. | |
388 | ||
389 | @return | |
390 | Pointer to a wxDocTemplate, or @NULL if none found. | |
391 | ||
392 | @since 2.9.2 | |
393 | */ | |
394 | wxDocTemplate* FindTemplate(const wxClassInfo* classinfo); | |
395 | ||
396 | /** | |
397 | Closes the specified document. | |
398 | ||
399 | If @a force is @true, the document is closed even if it has unsaved | |
400 | changes. | |
401 | ||
402 | @param doc | |
403 | The document to close, must be non-@NULL. | |
404 | @param force | |
405 | If @true, close the document even if wxDocument::Close() returns | |
406 | @false. | |
407 | @return | |
408 | @true if the document was closed or @false if closing it was | |
409 | cancelled by user (only in @a force = @false case). | |
410 | */ | |
411 | bool CloseDocument(wxDocument *doc, bool force = false); | |
412 | ||
413 | /** | |
414 | Closes all currently opened documents. | |
415 | ||
416 | @see CloseDocument() | |
417 | */ | |
418 | bool CloseDocuments(bool force = true); | |
419 | ||
420 | /** | |
421 | Creates a new document. | |
422 | ||
423 | This function can either create a document corresponding to a new | |
424 | file or to an already existing one depending on whether @c wxDOC_NEW is | |
425 | specified in the @a flags. | |
426 | ||
427 | By default, this function asks the user for the type of document to | |
428 | open and the path to its file if it's not specified, i.e. if @a path is | |
429 | empty. Specifying @c wxDOC_SILENT flag suppresses any prompts and means | |
430 | that the @a path must be non-empty and there must be a registered | |
431 | document template handling the extension of this file, otherwise a | |
432 | warning message is logged and the function returns @NULL. Notice that | |
433 | @c wxDOC_SILENT can be combined with @c wxDOC_NEW, however in this case | |
434 | the @a path must still be specified, even if the file with this path | |
435 | typically won't exist. | |
436 | ||
437 | Finally notice that if this document manager was configured to allow | |
438 | only a limited number of simultaneously opened documents using | |
439 | SetMaxDocsOpen(), this function will try to close the oldest existing | |
440 | document if this number was reached before creating a new document. | |
441 | And if closing the old document fails (e.g. because it was vetoed by | |
442 | user), this function fails as well. | |
443 | ||
444 | @param path | |
445 | Path to a file or an empty string. If the path is empty, the user | |
446 | will be asked to select it (thus, this is incompatible with the use | |
447 | of @c wxDOC_SILENT). The file should exist unless @a flags includes | |
448 | @c wxDOC_NEW. | |
449 | @param flags | |
450 | By default, none. May include @c wxDOC_NEW to indicate that the new | |
451 | document corresponds to a new file and not an existing one and | |
452 | @c wxDOC_SILENT to suppress any dialogs asking the user about the | |
453 | file path and type. | |
454 | @return a new document object or @NULL on failure. | |
455 | */ | |
456 | virtual wxDocument* CreateDocument(const wxString& path, long flags = 0); | |
457 | ||
458 | /** | |
459 | Creates an empty new document. | |
460 | ||
461 | This is equivalent to calling CreateDocument() with @c wxDOC_NEW flags | |
462 | and without the file name. | |
463 | */ | |
464 | wxDocument *CreateNewDocument(); | |
465 | ||
466 | /** | |
467 | Creates a new view for the given document. If more than one view is | |
468 | allowed for the document (by virtue of multiple templates mentioning | |
469 | the same document type), a choice of view is presented to the user. | |
470 | */ | |
471 | virtual wxView* CreateView(wxDocument* doc, long flags = 0); | |
472 | ||
473 | /** | |
474 | Removes the template from the list of templates. | |
475 | */ | |
476 | void DisassociateTemplate(wxDocTemplate* temp); | |
477 | ||
478 | /** | |
479 | Appends the files in the history list to all menus managed by the file | |
480 | history object. | |
481 | */ | |
482 | virtual void FileHistoryAddFilesToMenu(); | |
483 | /** | |
484 | Appends the files in the history list to the given @a menu only. | |
485 | */ | |
486 | virtual void FileHistoryAddFilesToMenu(wxMenu* menu); | |
487 | ||
488 | /** | |
489 | Loads the file history from a config object. | |
490 | ||
491 | @see wxConfigBase | |
492 | */ | |
493 | virtual void FileHistoryLoad(const wxConfigBase& config); | |
494 | ||
495 | /** | |
496 | Removes the given menu from the list of menus managed by the file | |
497 | history object. | |
498 | */ | |
499 | virtual void FileHistoryRemoveMenu(wxMenu* menu); | |
500 | ||
501 | /** | |
502 | Saves the file history into a config object. This must be called | |
503 | explicitly by the application. | |
504 | ||
505 | @see wxConfigBase | |
506 | */ | |
507 | virtual void FileHistorySave(wxConfigBase& resourceFile); | |
508 | ||
509 | /** | |
510 | Use this menu for appending recently-visited document filenames, for | |
511 | convenient access. Calling this function with a valid menu pointer | |
512 | enables the history list functionality. | |
513 | ||
514 | @note You can add multiple menus using this function, to be managed by | |
515 | the file history object. | |
516 | */ | |
517 | virtual void FileHistoryUseMenu(wxMenu* menu); | |
518 | ||
519 | /** | |
520 | Given a path, try to find template that matches the extension. This is | |
521 | only an approximate method of finding a template for creating a | |
522 | document. | |
523 | */ | |
524 | virtual wxDocTemplate* FindTemplateForPath(const wxString& path); | |
525 | ||
526 | /** | |
527 | Returns the document associated with the currently active view (if | |
528 | any). | |
529 | */ | |
530 | wxDocument* GetCurrentDocument() const; | |
531 | ||
532 | /** | |
533 | Returns the currently active view | |
534 | */ | |
535 | virtual wxView* GetCurrentView() const; | |
536 | ||
537 | /** | |
538 | Returns a reference to the list of documents. | |
539 | */ | |
540 | wxList& GetDocuments(); | |
541 | ||
542 | /** | |
543 | Returns a pointer to file history. | |
544 | */ | |
545 | virtual wxFileHistory* GetFileHistory() const; | |
546 | ||
547 | /** | |
548 | Returns the number of files currently stored in the file history. | |
549 | */ | |
550 | virtual size_t GetHistoryFilesCount() const; | |
551 | ||
552 | /** | |
553 | Returns the directory last selected by the user when opening a file. | |
554 | Initially empty. | |
555 | */ | |
556 | wxString GetLastDirectory() const; | |
557 | ||
558 | /** | |
559 | Returns the number of documents that can be open simultaneously. | |
560 | */ | |
561 | int GetMaxDocsOpen() const; | |
562 | ||
563 | /** | |
564 | Returns a reference to the list of associated templates. | |
565 | */ | |
566 | wxList& GetTemplates(); | |
567 | ||
568 | /** | |
569 | Create the frame used for print preview. | |
570 | ||
571 | This method can be overridden if you need to change the behaviour or | |
572 | appearance of the preview window. By default, a standard wxPreviewFrame | |
573 | is created. | |
574 | ||
575 | @since 2.9.1 | |
576 | ||
577 | @param preview The associated preview object. | |
578 | @param parent The parent window for the frame. | |
579 | @param title The suggested title for the print preview frame. | |
580 | @return A new print preview frame, must not return @NULL. | |
581 | */ | |
582 | virtual wxPreviewFrame* CreatePreviewFrame(wxPrintPreviewBase* preview, | |
583 | wxWindow* parent, | |
584 | const wxString& title); | |
585 | ||
586 | /** | |
587 | Initializes data; currently just calls OnCreateFileHistory(). | |
588 | ||
589 | Some data cannot always be initialized in the constructor because the | |
590 | programmer must be given the opportunity to override functionality. If | |
591 | OnCreateFileHistory() was called from the constructor, an overridden | |
592 | virtual OnCreateFileHistory() would not be called due to C++'s | |
593 | 'interesting' constructor semantics. In fact Initialize() @e is called | |
594 | from the wxDocManager constructor, but this can be vetoed by passing | |
595 | @false to the second argument, allowing the derived class's constructor | |
596 | to call Initialize(), possibly calling a different | |
597 | OnCreateFileHistory() from the default. | |
598 | ||
599 | The bottom line: if you're not deriving from Initialize(), forget it | |
600 | and construct wxDocManager with no arguments. | |
601 | */ | |
602 | virtual bool Initialize(); | |
603 | ||
604 | /** | |
605 | Return a string containing a suitable default name for a new document. | |
606 | By default this is implemented by appending an integer counter to the | |
607 | string @b unnamed but can be overridden in the derived classes to do | |
608 | something more appropriate. | |
609 | */ | |
610 | virtual wxString MakeNewDocumentName(); | |
611 | ||
612 | /** | |
613 | A hook to allow a derived class to create a different type of file | |
614 | history. Called from Initialize(). | |
615 | */ | |
616 | virtual wxFileHistory* OnCreateFileHistory(); | |
617 | ||
618 | /** | |
619 | Closes and deletes the currently active document. | |
620 | */ | |
621 | void OnFileClose(wxCommandEvent& event); | |
622 | ||
623 | /** | |
624 | Closes and deletes all the currently opened documents. | |
625 | */ | |
626 | void OnFileCloseAll(wxCommandEvent& event); | |
627 | ||
628 | /** | |
629 | Creates a document from a list of templates (if more than one | |
630 | template). | |
631 | */ | |
632 | void OnFileNew(wxCommandEvent& event); | |
633 | ||
634 | /** | |
635 | Creates a new document and reads in the selected file. | |
636 | */ | |
637 | void OnFileOpen(wxCommandEvent& event); | |
638 | ||
639 | /** | |
640 | Reverts the current document by calling wxDocument::Revert() for the | |
641 | current document. | |
642 | */ | |
643 | void OnFileRevert(wxCommandEvent& event); | |
644 | ||
645 | /** | |
646 | Saves the current document by calling wxDocument::Save() for the | |
647 | current document. | |
648 | */ | |
649 | void OnFileSave(wxCommandEvent& event); | |
650 | ||
651 | /** | |
652 | Calls wxDocument::SaveAs() for the current document. | |
653 | */ | |
654 | void OnFileSaveAs(wxCommandEvent& event); | |
655 | ||
656 | /** | |
657 | Removes the document from the list of documents. | |
658 | */ | |
659 | void RemoveDocument(wxDocument* doc); | |
660 | ||
661 | /** | |
662 | Under Windows, pops up a file selector with a list of filters | |
663 | corresponding to document templates. The wxDocTemplate corresponding to | |
664 | the selected file's extension is returned. | |
665 | ||
666 | On other platforms, if there is more than one document template a | |
667 | choice list is popped up, followed by a file selector. | |
668 | ||
669 | This function is used in CreateDocument(). | |
670 | ||
671 | @beginWxPerlOnly | |
672 | In wxPerl @a templates is a reference to a list of templates. | |
673 | If you override this method in your document manager it must | |
674 | return two values, eg: | |
675 | ||
676 | @code | |
677 | (doctemplate, path) = My::DocManager->SelectDocumentPath(...); | |
678 | @endcode | |
679 | @endWxPerlOnly | |
680 | */ | |
681 | virtual wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates, | |
682 | int noTemplates, wxString& path, | |
683 | long flags, bool save = false); | |
684 | ||
685 | /** | |
686 | Returns a document template by asking the user (if there is more than | |
687 | one template). This function is used in CreateDocument(). | |
688 | ||
689 | @param templates | |
690 | Pointer to an array of templates from which to choose a desired | |
691 | template. | |
692 | @param noTemplates | |
693 | Number of templates being pointed to by the templates pointer. | |
694 | @param sort | |
695 | If more than one template is passed into templates, then this | |
696 | parameter indicates whether the list of templates that the user | |
697 | will have to choose from is sorted or not when shown the choice box | |
698 | dialog. Default is @false. | |
699 | ||
700 | @beginWxPerlOnly | |
701 | In wxPerl @a templates is a reference to a list of templates. | |
702 | @endWxPerlOnly | |
703 | */ | |
704 | virtual wxDocTemplate* SelectDocumentType(wxDocTemplate** templates, | |
705 | int noTemplates, | |
706 | bool sort = false); | |
707 | ||
708 | /** | |
709 | Returns a document template by asking the user (if there is more than | |
710 | one template), displaying a list of valid views. This function is used | |
711 | in CreateView(). The dialog normally will not appear because the array | |
712 | of templates only contains those relevant to the document in question, | |
713 | and often there will only be one such. | |
714 | ||
715 | @param templates | |
716 | Pointer to an array of templates from which to choose a desired | |
717 | template. | |
718 | @param noTemplates | |
719 | Number of templates being pointed to by the templates pointer. | |
720 | @param sort | |
721 | If more than one template is passed into templates, then this | |
722 | parameter indicates whether the list of templates that the user | |
723 | will have to choose from is sorted or not when shown the choice box | |
724 | dialog. Default is @false. | |
725 | ||
726 | @beginWxPerlOnly | |
727 | In wxPerl @a templates is a reference to a list of templates. | |
728 | @endWxPerlOnly | |
729 | */ | |
730 | virtual wxDocTemplate* SelectViewType(wxDocTemplate** templates, | |
731 | int noTemplates, bool sort = false); | |
732 | ||
733 | /** | |
734 | Sets the directory to be displayed to the user when opening a file. | |
735 | Initially this is empty. | |
736 | */ | |
737 | void SetLastDirectory(const wxString& dir); | |
738 | ||
739 | /** | |
740 | Sets the maximum number of documents that can be open at a time. By | |
741 | default, this is @c INT_MAX, i.e. the number of documents is unlimited. | |
742 | If you set it to 1, existing documents will be saved and deleted when | |
743 | the user tries to open or create a new one (similar to the behaviour of | |
744 | Windows Write, for example). Allowing multiple documents gives | |
745 | behaviour more akin to MS Word and other Multiple Document Interface | |
746 | applications. | |
747 | */ | |
748 | void SetMaxDocsOpen(int n); | |
749 | ||
750 | ||
751 | protected: | |
752 | /** | |
753 | Called when a file selected from the MRU list doesn't exist any more. | |
754 | ||
755 | The default behaviour is to remove the file from the MRU (most recently | |
756 | used) files list and the corresponding menu and notify the user about | |
757 | it but this method can be overridden to customize it. | |
758 | ||
759 | For example, an application may want to just give an error about the | |
760 | missing file @a filename but not remove it from the file history. Or it | |
761 | could ask the user whether the file should be kept or removed. | |
762 | ||
763 | Notice that this method is called only if the file selected by user | |
764 | from the MRU files in the menu doesn't exist, but not if opening it | |
765 | failed for any other reason because in the latter case the default | |
766 | behaviour of removing the file from the MRU list is inappropriate. | |
767 | If you still want to do it, you would need to do it by calling | |
768 | RemoveFileFromHistory() explicitly in the part of the file opening code | |
769 | that may fail. | |
770 | ||
771 | @since 2.9.3 | |
772 | ||
773 | @param n | |
774 | The index of the file in the MRU list, it can be passed to | |
775 | RemoveFileFromHistory() to remove this file from the list. | |
776 | @param filename | |
777 | The full name of the file. | |
778 | */ | |
779 | virtual void OnMRUFileNotExist(unsigned n, const wxString& filename); | |
780 | ||
781 | ||
782 | /** | |
783 | The currently active view. | |
784 | */ | |
785 | wxView* m_currentView; | |
786 | ||
787 | /** | |
788 | Stores the integer to be used for the next default document name. | |
789 | */ | |
790 | int m_defaultDocumentNameCounter; | |
791 | ||
792 | /** | |
793 | A list of all documents. | |
794 | */ | |
795 | wxList m_docs; | |
796 | ||
797 | /** | |
798 | A pointer to an instance of wxFileHistory, which manages the history of | |
799 | recently-visited files on the File menu. | |
800 | */ | |
801 | wxFileHistory* m_fileHistory; | |
802 | ||
803 | /** | |
804 | The directory last selected by the user when opening a file. | |
805 | */ | |
806 | wxString m_lastDirectory; | |
807 | ||
808 | /** | |
809 | Stores the maximum number of documents that can be opened before | |
810 | existing documents are closed. | |
811 | ||
812 | By default, this is @c INT_MAX i.e. practically unlimited. | |
813 | */ | |
814 | int m_maxDocsOpen; | |
815 | }; | |
816 | ||
817 | ||
818 | ||
819 | /** | |
820 | @class wxView | |
821 | ||
822 | The view class can be used to model the viewing and editing component of | |
823 | an application's file-based data. It is part of the document/view framework | |
824 | supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate | |
825 | and wxDocManager classes. | |
826 | ||
827 | @library{wxcore} | |
828 | @category{docview} | |
829 | ||
830 | @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager | |
831 | */ | |
832 | class wxView : public wxEvtHandler | |
833 | { | |
834 | public: | |
835 | /** | |
836 | Constructor. Define your own default constructor to initialize | |
837 | application-specific data. | |
838 | */ | |
839 | wxView(); | |
840 | ||
841 | /** | |
842 | Destructor. Removes itself from the document's list of views. | |
843 | */ | |
844 | virtual ~wxView(); | |
845 | ||
846 | /** | |
847 | Call this from your view frame's wxDocChildFrame::OnActivate() member | |
848 | to tell the framework which view is currently active. If your windowing | |
849 | system doesn't call wxDocChildFrame::OnActivate(), you may need to call | |
850 | this function from any place where you know the view must be active, | |
851 | and the framework will need to get the current view. | |
852 | ||
853 | The prepackaged view frame wxDocChildFrame calls Activate() from its | |
854 | wxDocChildFrame::OnActivate() member. | |
855 | ||
856 | This function calls OnActivateView(). | |
857 | */ | |
858 | virtual void Activate(bool activate); | |
859 | ||
860 | /** | |
861 | Closes the view by calling OnClose(). If @a deleteWindow is @true, this | |
862 | function should delete the window associated with the view. | |
863 | */ | |
864 | virtual bool Close(bool deleteWindow = true); | |
865 | ||
866 | /** | |
867 | Gets a pointer to the document associated with the view. | |
868 | */ | |
869 | wxDocument* GetDocument() const; | |
870 | ||
871 | /** | |
872 | Returns a pointer to the document manager instance associated with this | |
873 | view. | |
874 | */ | |
875 | wxDocManager* GetDocumentManager() const; | |
876 | ||
877 | /** | |
878 | Gets the frame associated with the view (if any). Note that this | |
879 | "frame" is not a wxFrame at all in the generic MDI implementation which | |
880 | uses notebook pages instead of frames and this is why this method | |
881 | returns a wxWindow and not a wxFrame. | |
882 | */ | |
883 | wxWindow* GetFrame() const; | |
884 | ||
885 | /** | |
886 | Gets the name associated with the view (passed to the wxDocTemplate | |
887 | constructor). Not currently used by the framework. | |
888 | */ | |
889 | wxString GetViewName() const; | |
890 | ||
891 | /** | |
892 | Called when a view is activated by means of Activate(). The default | |
893 | implementation does nothing. | |
894 | */ | |
895 | virtual void OnActivateView(bool activate, wxView* activeView, | |
896 | wxView* deactiveView); | |
897 | ||
898 | /** | |
899 | Called when the filename has changed. The default implementation | |
900 | constructs a suitable title and sets the title of the view frame (if any). | |
901 | */ | |
902 | virtual void OnChangeFilename(); | |
903 | ||
904 | /** | |
905 | Implements closing behaviour. The default implementation calls | |
906 | wxDocument::Close() to close the associated document. Does not delete | |
907 | the view. The application may wish to do some cleaning up operations in | |
908 | this function, @e if a call to wxDocument::Close() succeeded. For | |
909 | example, if your views all share the same window, you need to | |
910 | disassociate the window from the view and perhaps clear the window. If | |
911 | @a deleteWindow is @true, delete the frame associated with the view. | |
912 | */ | |
913 | virtual bool OnClose(bool deleteWindow); | |
914 | ||
915 | /** | |
916 | Override this to clean up the view when the document is being closed. | |
917 | */ | |
918 | virtual void OnClosingDocument(); | |
919 | ||
920 | /** | |
921 | wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just | |
922 | after the wxDocTemplate creates the wxView, it calls OnCreate(). The | |
923 | wxView can create a wxDocChildFrame (or derived class) in its | |
924 | wxView::OnCreate() member function. This wxDocChildFrame provides user | |
925 | interface elements to view and/or edit the contents of the wxDocument. | |
926 | ||
927 | By default, simply returns @true. If the function returns @false, the | |
928 | view will be deleted. | |
929 | */ | |
930 | virtual bool OnCreate(wxDocument* doc, long flags); | |
931 | ||
932 | /** | |
933 | If the printing framework is enabled in the library, this function | |
934 | returns a wxPrintout object for the purposes of printing. It should | |
935 | create a new object every time it is called; the framework will delete | |
936 | objects it creates. | |
937 | ||
938 | By default, this function returns an instance of wxDocPrintout, which | |
939 | prints and previews one page by calling OnDraw(). | |
940 | ||
941 | Override to return an instance of a class other than wxDocPrintout. | |
942 | */ | |
943 | virtual wxPrintout* OnCreatePrintout(); | |
944 | ||
945 | /** | |
946 | Override this function to render the view on the given device context. | |
947 | */ | |
948 | virtual void OnDraw(wxDC* dc) = 0; | |
949 | ||
950 | /** | |
951 | Called when the view should be updated. | |
952 | ||
953 | @param sender | |
954 | A pointer to the wxView that sent the update request, or @NULL if | |
955 | no single view requested the update (for instance, when the | |
956 | document is opened). | |
957 | @param hint | |
958 | This is unused currently, but may in future contain | |
959 | application-specific information for making updating more | |
960 | efficient. | |
961 | */ | |
962 | virtual void OnUpdate(wxView* sender, wxObject* hint = 0); | |
963 | ||
964 | /** | |
965 | Associates the given document with the view. Normally called by the | |
966 | framework. | |
967 | */ | |
968 | virtual void SetDocument(wxDocument* doc); | |
969 | ||
970 | /** | |
971 | Sets the frame associated with this view. The application should call | |
972 | this if possible, to tell the view about the frame. | |
973 | ||
974 | See GetFrame() for the explanation about the mismatch between the | |
975 | "Frame" in the method name and the type of its parameter. | |
976 | */ | |
977 | void SetFrame(wxWindow* frame); | |
978 | ||
979 | /** | |
980 | Sets the view type name. Should only be called by the framework. | |
981 | */ | |
982 | void SetViewName(const wxString& name); | |
983 | ||
984 | /** | |
985 | The document associated with this view. There may be more than one view | |
986 | per document, but there can never be more than one document for one | |
987 | view. | |
988 | */ | |
989 | wxDocument* m_viewDocument; | |
990 | ||
991 | /** | |
992 | Frame associated with the view, if any. | |
993 | */ | |
994 | wxFrame* m_viewFrame; | |
995 | ||
996 | /** | |
997 | The view type name given to the wxDocTemplate constructor, copied to | |
998 | this variable when the view is created. Not currently used by the | |
999 | framework. | |
1000 | */ | |
1001 | wxString m_viewTypeName; | |
1002 | }; | |
1003 | ||
1004 | ||
1005 | ||
1006 | /** | |
1007 | @class wxDocChildFrame | |
1008 | ||
1009 | The wxDocChildFrame class provides a default frame for displaying documents | |
1010 | on separate windows. This class can only be used for SDI (not MDI) child | |
1011 | frames. | |
1012 | ||
1013 | The class is part of the document/view framework supported by wxWidgets, | |
1014 | and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate | |
1015 | classes. | |
1016 | ||
1017 | @library{wxcore} | |
1018 | @category{docview} | |
1019 | ||
1020 | @see @ref overview_docview, @ref page_samples_docview, wxFrame | |
1021 | */ | |
1022 | class wxDocChildFrame : public wxFrame | |
1023 | { | |
1024 | public: | |
1025 | /** | |
1026 | Constructor. | |
1027 | */ | |
1028 | wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent, | |
1029 | wxWindowID id, const wxString& title, | |
1030 | const wxPoint& pos = wxDefaultPosition, | |
1031 | const wxSize& size = wxDefaultSize, | |
1032 | long style = wxDEFAULT_FRAME_STYLE, | |
1033 | const wxString& name = wxFrameNameStr); | |
1034 | ||
1035 | /** | |
1036 | Destructor. | |
1037 | */ | |
1038 | virtual ~wxDocChildFrame(); | |
1039 | ||
1040 | /** | |
1041 | Returns the document associated with this frame. | |
1042 | */ | |
1043 | wxDocument* GetDocument() const; | |
1044 | ||
1045 | /** | |
1046 | Returns the view associated with this frame. | |
1047 | */ | |
1048 | wxView* GetView() const; | |
1049 | ||
1050 | /** | |
1051 | Sets the currently active view to be the frame's view. You may need to | |
1052 | override (but still call) this function in order to set the keyboard | |
1053 | focus for your subwindow. | |
1054 | */ | |
1055 | void OnActivate(wxActivateEvent& event); | |
1056 | ||
1057 | /** | |
1058 | Closes and deletes the current view and document. | |
1059 | */ | |
1060 | void OnCloseWindow(wxCloseEvent& event); | |
1061 | ||
1062 | /** | |
1063 | Sets the document for this frame. | |
1064 | */ | |
1065 | void SetDocument(wxDocument* doc); | |
1066 | ||
1067 | /** | |
1068 | Sets the view for this frame. | |
1069 | */ | |
1070 | void SetView(wxView* view); | |
1071 | ||
1072 | /** | |
1073 | The document associated with the frame. | |
1074 | */ | |
1075 | wxDocument* m_childDocument; | |
1076 | ||
1077 | /** | |
1078 | The view associated with the frame. | |
1079 | */ | |
1080 | wxView* m_childView; | |
1081 | }; | |
1082 | ||
1083 | ||
1084 | ||
1085 | /** | |
1086 | @class wxDocParentFrame | |
1087 | ||
1088 | The wxDocParentFrame class provides a default top-level frame for | |
1089 | applications using the document/view framework. This class can only be used | |
1090 | for SDI (not MDI) parent frames. | |
1091 | ||
1092 | It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate | |
1093 | classes. | |
1094 | ||
1095 | @library{wxcore} | |
1096 | @category{docview} | |
1097 | ||
1098 | @see @ref overview_docview, @ref page_samples_docview, wxFrame | |
1099 | */ | |
1100 | class wxDocParentFrame : public wxFrame | |
1101 | { | |
1102 | public: | |
1103 | /** | |
1104 | Default constructor. | |
1105 | */ | |
1106 | wxDocParentFrame(); | |
1107 | /** | |
1108 | Constructor. | |
1109 | */ | |
1110 | wxDocParentFrame(wxDocManager* manager, wxFrame* parent, | |
1111 | wxWindowID id, const wxString& title, | |
1112 | const wxPoint& pos = wxDefaultPosition, | |
1113 | const wxSize& size = wxDefaultSize, | |
1114 | long style = wxDEFAULT_FRAME_STYLE, | |
1115 | const wxString& name = wxFrameNameStr); | |
1116 | ||
1117 | /** | |
1118 | Destructor. | |
1119 | */ | |
1120 | virtual ~wxDocParentFrame(); | |
1121 | ||
1122 | /** | |
1123 | Used in two-step construction. | |
1124 | */ | |
1125 | bool Create(wxDocManager* manager, wxFrame* parent, wxWindowID id, | |
1126 | const wxString& title, const wxPoint& pos = wxDefaultPosition, | |
1127 | const wxSize& size = wxDefaultSize, long style = 541072960, | |
1128 | const wxString& name = wxFrameNameStr); | |
1129 | ||
1130 | /** | |
1131 | Returns the associated document manager object. | |
1132 | */ | |
1133 | wxDocManager* GetDocumentManager() const; | |
1134 | ||
1135 | /** | |
1136 | Deletes all views and documents. If no user input cancelled the | |
1137 | operation, the frame will be destroyed and the application will exit. | |
1138 | Since understanding how document/view clean-up takes place can be | |
1139 | difficult, the implementation of this function is shown below: | |
1140 | ||
1141 | @code | |
1142 | void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event) | |
1143 | { | |
1144 | if (m_docManager->Clear(!event.CanVeto())) | |
1145 | { | |
1146 | this->Destroy(); | |
1147 | } | |
1148 | else | |
1149 | event.Veto(); | |
1150 | } | |
1151 | @endcode | |
1152 | */ | |
1153 | void OnCloseWindow(wxCloseEvent& event); | |
1154 | }; | |
1155 | ||
1156 | ||
1157 | ||
1158 | /** | |
1159 | @class wxDocument | |
1160 | ||
1161 | The document class can be used to model an application's file-based data. | |
1162 | ||
1163 | It is part of the document/view framework supported by wxWidgets, and | |
1164 | cooperates with the wxView, wxDocTemplate and wxDocManager classes. | |
1165 | ||
1166 | A normal document is the one created without parent document and is | |
1167 | associated with a disk file. Since version 2.9.2 wxWidgets also supports a | |
1168 | special kind of documents called <em>child documents</em> which are virtual | |
1169 | in the sense that they do not correspond to a file but rather to a part of | |
1170 | their parent document. Because of this, the child documents can't be | |
1171 | created directly by user but can only be created by the parent document | |
1172 | (usually when it's being created itself). They also can't be independently | |
1173 | saved. A child document has its own view with the corresponding window. | |
1174 | This view can be closed by user but, importantly, is also automatically | |
1175 | closed when its parent document is closed. Thus, child documents may be | |
1176 | convenient for creating additional windows which need to be closed when the | |
1177 | main document is. The docview sample demonstrates this use of child | |
1178 | documents by creating a child document containing the information about the | |
1179 | parameters of the image opened in the main document. | |
1180 | ||
1181 | @library{wxcore} | |
1182 | @category{docview} | |
1183 | ||
1184 | @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager | |
1185 | */ | |
1186 | class wxDocument : public wxEvtHandler | |
1187 | { | |
1188 | public: | |
1189 | /** | |
1190 | Constructor. Define your own default constructor to initialize | |
1191 | application-specific data. | |
1192 | ||
1193 | @param parent | |
1194 | Specifying a non-@c NULL parent document here makes this document a | |
1195 | special <em>child document</em>, see their description in the class | |
1196 | documentation. Notice that this parameter exists but is ignored in | |
1197 | wxWidgets versions prior to 2.9.1. | |
1198 | */ | |
1199 | wxDocument(wxDocument* parent = NULL); | |
1200 | ||
1201 | /** | |
1202 | Destructor. Removes itself from the document manager. | |
1203 | */ | |
1204 | virtual ~wxDocument(); | |
1205 | ||
1206 | /** | |
1207 | If the view is not already in the list of views, adds the view and | |
1208 | calls OnChangedViewList(). | |
1209 | */ | |
1210 | virtual bool AddView(wxView* view); | |
1211 | ||
1212 | /** | |
1213 | Returns true if the document hasn't been modified since the last time | |
1214 | it had been saved. | |
1215 | ||
1216 | Notice that this function returns @false if the document had been never | |
1217 | saved at all, so it may be also used to test whether it makes sense to | |
1218 | save the document: if it returns @true, there is nothing to save but if | |
1219 | @false is returned, it can be saved, even if it might be not modified | |
1220 | (this can be used to create an empty document file by the user). | |
1221 | ||
1222 | @see IsModified(), GetDocumentSaved() | |
1223 | ||
1224 | @since 2.9.0 | |
1225 | */ | |
1226 | bool AlreadySaved() const; | |
1227 | ||
1228 | /** | |
1229 | Closes the document, by calling OnSaveModified() and then (if this | |
1230 | returned @true) OnCloseDocument(). This does not normally delete the | |
1231 | document object, use DeleteAllViews() to do this implicitly. | |
1232 | */ | |
1233 | virtual bool Close(); | |
1234 | ||
1235 | /** | |
1236 | Calls wxView::Close() and deletes each view. Deleting the final view | |
1237 | will implicitly delete the document itself, because the wxView | |
1238 | destructor calls RemoveView(). This in turns calls OnChangedViewList(), | |
1239 | whose default implemention is to save and delete the document if no | |
1240 | views exist. | |
1241 | */ | |
1242 | virtual bool DeleteAllViews(); | |
1243 | ||
1244 | /** | |
1245 | Virtual method called from OnCloseDocument(). | |
1246 | ||
1247 | This method may be overridden to perform any additional cleanup which | |
1248 | might be needed when the document is closed. | |
1249 | ||
1250 | The return value of this method is currently ignored. | |
1251 | ||
1252 | The default version does nothing and simply returns @true. | |
1253 | */ | |
1254 | virtual bool DeleteContents(); | |
1255 | ||
1256 | /** | |
1257 | Returns a pointer to the command processor associated with this | |
1258 | document. | |
1259 | ||
1260 | @see wxCommandProcessor | |
1261 | */ | |
1262 | virtual wxCommandProcessor* GetCommandProcessor() const; | |
1263 | ||
1264 | /** | |
1265 | Gets a pointer to the associated document manager. | |
1266 | */ | |
1267 | virtual wxDocManager* GetDocumentManager() const; | |
1268 | ||
1269 | /** | |
1270 | Gets the document type name for this document. See the comment for | |
1271 | @ref m_documentTypeName. | |
1272 | */ | |
1273 | wxString GetDocumentName() const; | |
1274 | ||
1275 | /** | |
1276 | Return true if this document had been already saved. | |
1277 | ||
1278 | @see IsModified() | |
1279 | */ | |
1280 | bool GetDocumentSaved() const; | |
1281 | ||
1282 | /** | |
1283 | Gets a pointer to the template that created the document. | |
1284 | */ | |
1285 | virtual wxDocTemplate* GetDocumentTemplate() const; | |
1286 | ||
1287 | /** | |
1288 | Intended to return a suitable window for using as a parent for | |
1289 | document-related dialog boxes. By default, uses the frame associated | |
1290 | with the first view. | |
1291 | */ | |
1292 | virtual wxWindow* GetDocumentWindow() const; | |
1293 | ||
1294 | /** | |
1295 | Gets the filename associated with this document, or "" if none is | |
1296 | associated. | |
1297 | */ | |
1298 | wxString GetFilename() const; | |
1299 | ||
1300 | /** | |
1301 | A convenience function to get the first view for a document, because in | |
1302 | many cases a document will only have a single view. | |
1303 | ||
1304 | @see GetViews() | |
1305 | */ | |
1306 | wxView* GetFirstView() const; | |
1307 | ||
1308 | /** | |
1309 | Gets the title for this document. The document title is used for an | |
1310 | associated frame (if any), and is usually constructed by the framework | |
1311 | from the filename. | |
1312 | */ | |
1313 | wxString GetTitle() const; | |
1314 | ||
1315 | /** | |
1316 | Return the document name suitable to be shown to the user. The default | |
1317 | implementation uses the document title, if any, of the name part of the | |
1318 | document filename if it was set or, otherwise, the string @b unnamed. | |
1319 | */ | |
1320 | virtual wxString GetUserReadableName() const; | |
1321 | ||
1322 | //@{ | |
1323 | /** | |
1324 | Returns the list whose elements are the views on the document. | |
1325 | ||
1326 | @see GetFirstView() | |
1327 | */ | |
1328 | wxList& GetViews(); | |
1329 | const wxList& GetViews() const; | |
1330 | //@} | |
1331 | ||
1332 | /** | |
1333 | Returns true if this document is a child document corresponding to a | |
1334 | part of the parent document and not a disk file as usual. | |
1335 | ||
1336 | This method can be used to check whether file-related operations make | |
1337 | sense for this document as they only apply to top-level documents and | |
1338 | not child ones. | |
1339 | ||
1340 | @since 2.9.2 | |
1341 | */ | |
1342 | bool IsChildDocument() const; | |
1343 | ||
1344 | /** | |
1345 | Returns @true if the document has been modified since the last save, | |
1346 | @false otherwise. You may need to override this if your document view | |
1347 | maintains its own record of being modified. | |
1348 | ||
1349 | @see Modify() | |
1350 | */ | |
1351 | virtual bool IsModified() const; | |
1352 | ||
1353 | //@{ | |
1354 | /** | |
1355 | Override this function and call it from your own LoadObject() before | |
1356 | streaming your own data. LoadObject() is called by the framework | |
1357 | automatically when the document contents need to be loaded. | |
1358 | ||
1359 | @note This version of LoadObject() may not exist depending on how | |
1360 | wxWidgets was configured. | |
1361 | */ | |
1362 | virtual istream& LoadObject(istream& stream); | |
1363 | virtual wxInputStream& LoadObject(wxInputStream& stream); | |
1364 | //@} | |
1365 | ||
1366 | /** | |
1367 | Call with @true to mark the document as modified since the last save, | |
1368 | @false otherwise. You may need to override this if your document view | |
1369 | maintains its own record of being modified. | |
1370 | ||
1371 | @see IsModified() | |
1372 | */ | |
1373 | virtual void Modify(bool modify); | |
1374 | ||
1375 | /** | |
1376 | Called when a view is added to or deleted from this document. The | |
1377 | default implementation saves and deletes the document if no views exist | |
1378 | (the last one has just been removed). | |
1379 | */ | |
1380 | virtual void OnChangedViewList(); | |
1381 | ||
1382 | /** | |
1383 | This virtual function is called when the document is being closed. | |
1384 | ||
1385 | The default implementation calls DeleteContents() (which may be | |
1386 | overridden to perform additional cleanup) and sets the modified flag to | |
1387 | @false. You can override it to supply additional behaviour when the | |
1388 | document is closed with Close(). | |
1389 | ||
1390 | Notice that previous wxWidgets versions used to call this function also | |
1391 | from OnNewDocument(), rather counter-intuitively. This is no longer the | |
1392 | case since wxWidgets 2.9.0. | |
1393 | */ | |
1394 | virtual bool OnCloseDocument(); | |
1395 | ||
1396 | /** | |
1397 | Called just after the document object is created to give it a chance to | |
1398 | initialize itself. | |
1399 | ||
1400 | The default implementation uses the template associated with the | |
1401 | document to create an initial view. | |
1402 | ||
1403 | For compatibility reasons, this method may either delete the document | |
1404 | itself if its initialization fails or not do it in which case it is | |
1405 | deleted by caller. It is recommended to delete the document explicitly | |
1406 | in this function if it can't be initialized. | |
1407 | ||
1408 | @param path | |
1409 | The associated file path. | |
1410 | @param flags | |
1411 | Flags passed to CreateDocument(). | |
1412 | @return | |
1413 | @true if the initialization was successful or @false if it failed. | |
1414 | */ | |
1415 | virtual bool OnCreate(const wxString& path, long flags); | |
1416 | ||
1417 | /** | |
1418 | Override this function if you want a different (or no) command | |
1419 | processor to be created when the document is created. By default, it | |
1420 | returns an instance of wxCommandProcessor. | |
1421 | ||
1422 | @see wxCommandProcessor | |
1423 | */ | |
1424 | virtual wxCommandProcessor* OnCreateCommandProcessor(); | |
1425 | ||
1426 | /** | |
1427 | The default implementation calls OnSaveModified() and DeleteContents(), | |
1428 | makes a default title for the document, and notifies the views that the | |
1429 | filename (in fact, the title) has changed. | |
1430 | */ | |
1431 | virtual bool OnNewDocument(); | |
1432 | ||
1433 | /** | |
1434 | Constructs an input file stream for the given filename (which must not | |
1435 | be empty), and calls LoadObject(). If LoadObject() returns @true, the | |
1436 | document is set to unmodified; otherwise, an error message box is | |
1437 | displayed. The document's views are notified that the filename has | |
1438 | changed, to give windows an opportunity to update their titles. All of | |
1439 | the document's views are then updated. | |
1440 | */ | |
1441 | virtual bool OnOpenDocument(const wxString& filename); | |
1442 | ||
1443 | /** | |
1444 | Constructs an output file stream for the given filename (which must not | |
1445 | be empty), and calls SaveObject(). If SaveObject() returns @true, the | |
1446 | document is set to unmodified; otherwise, an error message box is | |
1447 | displayed. | |
1448 | */ | |
1449 | virtual bool OnSaveDocument(const wxString& filename); | |
1450 | ||
1451 | /** | |
1452 | If the document has been modified, prompts the user to ask if the | |
1453 | changes should be saved. If the user replies Yes, the Save() function | |
1454 | is called. If No, the document is marked as unmodified and the function | |
1455 | succeeds. If Cancel, the function fails. | |
1456 | */ | |
1457 | virtual bool OnSaveModified(); | |
1458 | ||
1459 | /** | |
1460 | Removes the view from the document's list of views, and calls | |
1461 | OnChangedViewList(). | |
1462 | */ | |
1463 | virtual bool RemoveView(wxView* view); | |
1464 | ||
1465 | /** | |
1466 | Saves the document by calling OnSaveDocument() if there is an | |
1467 | associated filename, or SaveAs() if there is no filename. | |
1468 | */ | |
1469 | virtual bool Save(); | |
1470 | ||
1471 | /** | |
1472 | Prompts the user for a file to save to, and then calls | |
1473 | OnSaveDocument(). | |
1474 | */ | |
1475 | virtual bool SaveAs(); | |
1476 | ||
1477 | /** | |
1478 | Discard changes and load last saved version. | |
1479 | ||
1480 | Prompts the user first, and then calls DoOpenDocument() to reload the | |
1481 | current file. | |
1482 | */ | |
1483 | virtual bool Revert(); | |
1484 | ||
1485 | //@{ | |
1486 | /** | |
1487 | Override this function and call it from your own SaveObject() before | |
1488 | streaming your own data. SaveObject() is called by the framework | |
1489 | automatically when the document contents need to be saved. | |
1490 | ||
1491 | @note This version of SaveObject() may not exist depending on how | |
1492 | wxWidgets was configured. | |
1493 | */ | |
1494 | virtual ostream& SaveObject(ostream& stream); | |
1495 | virtual wxOutputStream& SaveObject(wxOutputStream& stream); | |
1496 | //@} | |
1497 | ||
1498 | /** | |
1499 | Sets the command processor to be used for this document. The document | |
1500 | will then be responsible for its deletion. Normally you should not call | |
1501 | this; override OnCreateCommandProcessor() instead. | |
1502 | ||
1503 | @see wxCommandProcessor | |
1504 | */ | |
1505 | virtual void SetCommandProcessor(wxCommandProcessor* processor); | |
1506 | ||
1507 | /** | |
1508 | Sets the document type name for this document. See the comment for | |
1509 | @ref m_documentTypeName. | |
1510 | */ | |
1511 | void SetDocumentName(const wxString& name); | |
1512 | ||
1513 | /** | |
1514 | Sets the pointer to the template that created the document. Should only | |
1515 | be called by the framework. | |
1516 | */ | |
1517 | virtual void SetDocumentTemplate(wxDocTemplate* templ); | |
1518 | ||
1519 | /** | |
1520 | Sets if this document has been already saved or not. | |
1521 | ||
1522 | Normally there is no need to call this function as the document-view | |
1523 | framework does it itself as the documents are loaded from and saved to | |
1524 | the files. However it may be useful in some particular cases, for | |
1525 | example it may be called with @false argument to prevent the user | |
1526 | from saving the just opened document into the same file if this | |
1527 | shouldn't be done for some reason (e.g. file format version changes and | |
1528 | a new extension should be used for saving). | |
1529 | ||
1530 | @see GetDocumentSaved(), AlreadySaved() | |
1531 | */ | |
1532 | void SetDocumentSaved(bool saved = true); | |
1533 | ||
1534 | /** | |
1535 | Sets the filename for this document. Usually called by the framework. | |
1536 | ||
1537 | Calls OnChangeFilename() which in turn calls wxView::OnChangeFilename() for | |
1538 | all views if @a notifyViews is @true. | |
1539 | */ | |
1540 | void SetFilename(const wxString& filename, bool notifyViews = false); | |
1541 | ||
1542 | /** | |
1543 | If @a notifyViews is @true, wxView::OnChangeFilename() is called for | |
1544 | all views. | |
1545 | ||
1546 | @since 2.9.0 | |
1547 | */ | |
1548 | virtual void OnChangeFilename(bool notifyViews); | |
1549 | ||
1550 | /** | |
1551 | Sets the title for this document. The document title is used for an | |
1552 | associated frame (if any), and is usually constructed by the framework | |
1553 | from the filename. | |
1554 | */ | |
1555 | void SetTitle(const wxString& title); | |
1556 | ||
1557 | /** | |
1558 | Updates all views. If @a sender is non-@NULL, does not update this | |
1559 | view. @a hint represents optional information to allow a view to | |
1560 | optimize its update. | |
1561 | */ | |
1562 | virtual void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL); | |
1563 | ||
1564 | protected: | |
1565 | /** | |
1566 | This method is called by OnSaveDocument() to really save the document | |
1567 | contents to the specified file. | |
1568 | ||
1569 | Base class version creates a file-based stream and calls SaveObject(). | |
1570 | Override this if you need to do something else or prefer not to use | |
1571 | SaveObject() at all. | |
1572 | */ | |
1573 | virtual bool DoSaveDocument(const wxString& file); | |
1574 | ||
1575 | /** | |
1576 | This method is called by OnOpenDocument() to really load the document | |
1577 | contents from the specified file. | |
1578 | ||
1579 | Base class version creates a file-based stream and calls LoadObject(). | |
1580 | Override this if you need to do something else or prefer not to use | |
1581 | LoadObject() at all. | |
1582 | */ | |
1583 | virtual bool DoOpenDocument(const wxString& file); | |
1584 | ||
1585 | /** | |
1586 | A pointer to the command processor associated with this document. | |
1587 | */ | |
1588 | wxCommandProcessor* m_commandProcessor; | |
1589 | ||
1590 | /** | |
1591 | Filename associated with this document ("" if none). | |
1592 | */ | |
1593 | wxString m_documentFile; | |
1594 | ||
1595 | /** | |
1596 | @true if the document has been modified, @false otherwise. | |
1597 | */ | |
1598 | bool m_documentModified; | |
1599 | ||
1600 | /** | |
1601 | A pointer to the template from which this document was created. | |
1602 | */ | |
1603 | wxDocTemplate* m_documentTemplate; | |
1604 | ||
1605 | /** | |
1606 | Document title. The document title is used for an associated frame (if | |
1607 | any), and is usually constructed by the framework from the filename. | |
1608 | */ | |
1609 | wxString m_documentTitle; | |
1610 | ||
1611 | /** | |
1612 | The document type name given to the wxDocTemplate constructor, copied | |
1613 | to this variable when the document is created. If several document | |
1614 | templates are created that use the same document type, this variable is | |
1615 | used in wxDocManager::CreateView() to collate a list of alternative | |
1616 | view types that can be used on this kind of document. Do not change the | |
1617 | value of this variable. | |
1618 | */ | |
1619 | wxString m_documentTypeName; | |
1620 | ||
1621 | /** | |
1622 | List of wxView instances associated with this document. | |
1623 | */ | |
1624 | wxList m_documentViews; | |
1625 | }; | |
1626 | ||
1627 | ||
1628 | // ============================================================================ | |
1629 | // Global functions/macros | |
1630 | // ============================================================================ | |
1631 | ||
1632 | /** @addtogroup group_funcmacro_file */ | |
1633 | //@{ | |
1634 | ||
1635 | /** | |
1636 | Copies the given file to @a stream. Useful when converting an old | |
1637 | application to use streams (within the document/view framework, for | |
1638 | example). | |
1639 | ||
1640 | @header{wx/docview.h} | |
1641 | */ | |
1642 | bool wxTransferFileToStream(const wxString& filename, | |
1643 | ostream& stream); | |
1644 | ||
1645 | /** | |
1646 | Copies the given stream to the file @a filename. Useful when converting an | |
1647 | old application to use streams (within the document/view framework, for | |
1648 | example). | |
1649 | ||
1650 | @header{wx/docview.h} | |
1651 | */ | |
1652 | bool wxTransferStreamToFile(istream& stream, | |
1653 | const wxString& filename); | |
1654 | ||
1655 | //@} | |
1656 |