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