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