1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of various doc/view framework classes
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 The wxDocTemplate class is used to model the relationship between a
13 document class and a view class.
18 @see @ref overview_docview_wxdoctemplate, wxDocument, wxView
20 class wxDocTemplate
: public wxObject
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.
29 The document manager object which manages this template.
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.
34 An appropriate file filter such as "*.txt".
36 The default directory to use for file selectors.
38 The default file extension (such as "txt").
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.
43 A name that should be unique for a given view.
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
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
57 A bit list of the following:
58 - wxTEMPLATE_VISIBLE - The template may be displayed to the
60 - wxTEMPLATE_INVISIBLE - The template may not be displayed to
62 - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE.
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
,
68 wxClassInfo
* docClassInfo
= NULL
,
69 wxClassInfo
* viewClassInfo
= NULL
,
70 long flags
= wxDEFAULT_TEMPLATE_FLAGS
);
78 Creates a new instance of the associated document class. If you have
79 not supplied a wxClassInfo parameter to the template constructor, you
80 will need to override this function to return an appropriate document
83 This function calls InitDocument() which in turns calls
84 wxDocument::OnCreate().
86 wxDocument
* CreateDocument(const wxString
& path
, long flags
= 0);
89 Creates a new instance of the associated view class. If you have not
90 supplied a wxClassInfo parameter to the template constructor, you will
91 need to override this function to return an appropriate view instance.
93 wxView
* CreateView(wxDocument
* doc
, long flags
= 0);
96 Returns the default file extension for the document data, as passed to
97 the document template constructor.
99 wxString
GetDefaultExtension();
102 Returns the text description of this template, as passed to the
103 document template constructor.
105 wxString
GetDescription();
108 Returns the default directory, as passed to the document template
111 wxString
GetDirectory();
114 Returns a pointer to the document manager instance for which this
115 template was created.
117 wxDocManager
* GetDocumentManager();
120 Returns the document type name, as passed to the document template
123 wxString
GetDocumentName();
126 Returns the file filter, as passed to the document template
129 wxString
GetFileFilter();
132 Returns the flags, as passed to the document template constructor.
137 Returns the view type name, as passed to the document template
140 wxString
GetViewName();
143 Initialises the document, calling wxDocument::OnCreate(). This is
144 called from CreateDocument().
146 bool InitDocument(wxDocument
* doc
, const wxString
& path
, long flags
= 0);
149 Returns @true if the document template can be shown in user dialogs,
155 Sets the default file extension.
157 void SetDefaultExtension(const wxString
& ext
);
160 Sets the template description.
162 void SetDescription(const wxString
& descr
);
165 Sets the default directory.
167 void SetDirectory(const wxString
& dir
);
170 Sets the pointer to the document manager instance for which this
171 template was created. Should not be called by the application.
173 void SetDocumentManager(wxDocManager
* manager
);
176 Sets the file filter.
178 void SetFileFilter(const wxString
& filter
);
181 Sets the internal document template flags (see the constructor
182 description for more details).
184 void SetFlags(long flags
);
187 The default extension for files of this type.
189 wxString m_defaultExt
;
192 A short description of this template.
194 wxString m_description
;
197 The default directory for files of this type.
199 wxString m_directory
;
202 Run-time class information that allows document instances to be
203 constructed dynamically.
205 wxClassInfo
* m_docClassInfo
;
208 The named type of the document associated with this template.
210 wxString m_docTypeName
;
213 A pointer to the document manager for which this template was created.
215 wxDocTemplate
* m_documentManager
;
218 The file filter (such as "*.txt") to be used in file selector dialogs.
220 wxString m_fileFilter
;
223 The flags passed to the constructor.
228 Run-time class information that allows view instances to be constructed
231 wxClassInfo
* m_viewClassInfo
;
234 The named type of the view associated with this template.
236 wxString m_viewTypeName
;
244 The wxDocManager class is part of the document/view framework supported by
245 wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate
251 @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate,
254 class wxDocManager
: public wxEvtHandler
258 Constructor. Create a document manager instance dynamically near the
259 start of your application before doing any document or view operations.
261 @a flags is currently unused.
263 If @a initialize is @true, the Initialize() function will be called to
264 create a default history list object. If you derive from wxDocManager,
265 you may wish to call the base constructor with @false, and then call
266 Initialize() in your own constructor, to allow your own Initialize() or
267 OnCreateFileHistory functions to be called.
269 wxDocManager(long flags
= wxDEFAULT_DOCMAN_FLAGS
,
270 bool initialize
= true);
278 Sets the current view.
280 void ActivateView(wxView
* doc
, bool activate
= true);
283 Adds the document to the list of documents.
285 void AddDocument(wxDocument
* doc
);
288 Adds a file to the file history list, if we have a pointer to an
289 appropriate file menu.
291 void AddFileToHistory(const wxString
& filename
);
294 Adds the template to the document manager's template list.
296 void AssociateTemplate(wxDocTemplate
* temp
);
299 Closes all currently opened documents.
301 bool CloseDocuments(bool force
= true);
304 Creates a new document in a manner determined by the @a flags
305 parameter, which can be:
307 - wxDOC_NEW - Creates a fresh document.
308 - wxDOC_SILENT - Silently loads the given document file.
310 If wxDOC_NEW is present, a new document will be created and returned,
311 possibly after asking the user for a template to use if there is more
312 than one document template. If wxDOC_SILENT is present, a new document
313 will be created and the given file loaded into it. If neither of these
314 flags is present, the user will be presented with a file selector for
315 the file to load, and the template to use will be determined by the
316 extension (Windows) or by popping up a template choice list (other
319 If the maximum number of documents has been reached, this function will
320 delete the oldest currently loaded document before creating a new one.
322 wxDocument
* CreateDocument(const wxString
& path
, long flags
);
325 Creates a new view for the given document. If more than one view is
326 allowed for the document (by virtue of multiple templates mentioning
327 the same document type), a choice of view is presented to the user.
329 wxView
* CreateView(wxDocument
* doc
, long flags
);
332 Removes the template from the list of templates.
334 void DisassociateTemplate(wxDocTemplate
* temp
);
337 Appends the files in the history list to all menus managed by the file
340 void FileHistoryAddFilesToMenu();
342 Appends the files in the history list to the given @a menu only.
344 void FileHistoryAddFilesToMenu(wxMenu
* menu
);
347 Loads the file history from a config object.
351 void FileHistoryLoad(const wxConfigBase
& config
);
354 Removes the given menu from the list of menus managed by the file
357 void FileHistoryRemoveMenu(wxMenu
* menu
);
360 Saves the file history into a config object. This must be called
361 explicitly by the application.
365 void FileHistorySave(wxConfigBase
& resourceFile
);
368 Use this menu for appending recently-visited document filenames, for
369 convenient access. Calling this function with a valid menu pointer
370 enables the history list functionality.
372 @note You can add multiple menus using this function, to be managed by
373 the file history object.
375 void FileHistoryUseMenu(wxMenu
* menu
);
378 Given a path, try to find template that matches the extension. This is
379 only an approximate method of finding a template for creating a
382 wxDocTemplate
* FindTemplateForPath(const wxString
& path
);
385 Returns the document associated with the currently active view (if
388 wxDocument
* GetCurrentDocument();
391 Returns the currently active view
393 wxView
* GetCurrentView();
396 Returns a reference to the list of documents.
398 wxList
GetDocuments();
401 Returns a pointer to file history.
403 wxFileHistory
* GetFileHistory();
406 Returns the number of files currently stored in the file history.
408 size_t GetHistoryFilesCount();
411 Returns the directory last selected by the user when opening a file.
414 wxString
GetLastDirectory() const;
417 Returns the number of documents that can be open simultaneously.
419 int GetMaxDocsOpen();
422 Returns a reference to the list of associated templates.
424 wxList
GetTemplates();
427 Initializes data; currently just calls OnCreateFileHistory().
429 Some data cannot always be initialized in the constructor because the
430 programmer must be given the opportunity to override functionality. If
431 OnCreateFileHistory() was called from the constructor, an overridden
432 virtual OnCreateFileHistory() would not be called due to C++'s
433 'interesting' constructor semantics. In fact Initialize() @e is called
434 from the wxDocManager constructor, but this can be vetoed by passing
435 @false to the second argument, allowing the derived class's constructor
436 to call Initialize(), possibly calling a different
437 OnCreateFileHistory() from the default.
439 The bottom line: if you're not deriving from Initialize(), forget it
440 and construct wxDocManager with no arguments.
445 Return a string containing a suitable default name for a new document.
446 By default this is implemented by appending an integer counter to the
447 string @b unnamed but can be overridden in the derived classes to do
448 something more appropriate.
450 wxString
MakeNewDocumentName();
453 A hook to allow a derived class to create a different type of file
454 history. Called from Initialize().
456 wxFileHistory
* OnCreateFileHistory();
459 Closes and deletes the currently active document.
461 void OnFileClose(wxCommandEvent
& event
);
464 Closes and deletes all the currently opened documents.
466 void OnFileCloseAll(wxCommandEvent
& event
);
469 Creates a document from a list of templates (if more than one
472 void OnFileNew(wxCommandEvent
& event
);
475 Creates a new document and reads in the selected file.
477 void OnFileOpen(wxCommandEvent
& event
);
480 Reverts the current document by calling wxDocument::Revert() for the
483 void OnFileRevert(wxCommandEvent
& event
);
486 Saves the current document by calling wxDocument::Save() for the
489 void OnFileSave(wxCommandEvent
& event
);
492 Calls wxDocument::SaveAs() for the current document.
494 void OnFileSaveAs(wxCommandEvent
& event
);
497 Removes the document from the list of documents.
499 void RemoveDocument(wxDocument
* doc
);
502 Under Windows, pops up a file selector with a list of filters
503 corresponding to document templates. The wxDocTemplate corresponding to
504 the selected file's extension is returned.
506 On other platforms, if there is more than one document template a
507 choice list is popped up, followed by a file selector.
509 This function is used in CreateDocument().
511 wxDocTemplate
* SelectDocumentPath(wxDocTemplate
** templates
,
512 int noTemplates
, wxString
& path
,
513 long flags
, bool save
);
516 Returns a document template by asking the user (if there is more than
517 one template). This function is used in CreateDocument().
520 Pointer to an array of templates from which to choose a desired
523 Number of templates being pointed to by the templates pointer.
525 If more than one template is passed in in templates, then this
526 parameter indicates whether the list of templates that the user
527 will have to choose from is sorted or not when shown the choice box
528 dialog. Default is @false.
530 wxDocTemplate
* SelectDocumentType(wxDocTemplate
** templates
,
531 int noTemplates
, bool sort
= false);
534 Returns a document template by asking the user (if there is more than
535 one template), displaying a list of valid views. This function is used
536 in CreateView(). The dialog normally will not appear because the array
537 of templates only contains those relevant to the document in question,
538 and often there will only be one such.
541 Pointer to an array of templates from which to choose a desired
544 Number of templates being pointed to by the templates pointer.
546 If more than one template is passed in in templates, then this
547 parameter indicates whether the list of templates that the user
548 will have to choose from is sorted or not when shown the choice box
549 dialog. Default is @false.
551 wxDocTemplate
* SelectViewType(wxDocTemplate
** templates
,
552 int noTemplates
, bool sort
= false);
555 Sets the directory to be displayed to the user when opening a file.
556 Initially this is empty.
558 void SetLastDirectory(const wxString
& dir
);
561 Sets the maximum number of documents that can be open at a time. By
562 default, this is 10,000. If you set it to 1, existing documents will be
563 saved and deleted when the user tries to open or create a new one
564 (similar to the behaviour of Windows Write, for example). Allowing
565 multiple documents gives behaviour more akin to MS Word and other
566 Multiple Document Interface applications.
568 void SetMaxDocsOpen(int n
);
571 The currently active view.
573 wxView
* m_currentView
;
576 Stores the integer to be used for the next default document name.
578 int m_defaultDocumentNameCounter
;
581 A list of all documents.
586 A pointer to an instance of wxFileHistory, which manages the history of
587 recently-visited files on the File menu.
589 wxFileHistory
* m_fileHistory
;
592 Stores the flags passed to the constructor.
597 The directory last selected by the user when opening a file.
599 wxFileHistory
* m_fileHistory
;
602 Stores the maximum number of documents that can be opened before
603 existing documents are closed. By default, this is 10,000.
613 The view class can be used to model the viewing and editing component of
614 an application's file-based data. It is part of the document/view framework
615 supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
616 and wxDocManager classes.
621 @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager
623 class wxView
: public wxEvtHandler
627 Constructor. Define your own default constructor to initialize
628 application-specific data.
633 Destructor. Removes itself from the document's list of views.
638 Call this from your view frame's wxDocChildFrame::OnActivate() member
639 to tell the framework which view is currently active. If your windowing
640 system doesn't call wxDocChildFrame::OnActivate(), you may need to call
641 this function from any place where you know the view must be active,
642 and the framework will need to get the current view.
644 The prepackaged view frame wxDocChildFrame calls Activate() from its
645 wxDocChildFrame::OnActivate() member.
647 This function calls OnActivateView().
649 virtual void Activate(bool activate
);
652 Closes the view by calling OnClose(). If @a deleteWindow is @true, this
653 function should delete the window associated with the view.
655 virtual bool Close(bool deleteWindow
= true);
658 Gets a pointer to the document associated with the view.
660 wxDocument
* GetDocument() const;
663 Returns a pointer to the document manager instance associated with this
666 wxDocManager
* GetDocumentManager() const;
669 Gets the frame associated with the view (if any). Note that this
670 "frame" is not a wxFrame at all in the generic MDI implementation which
671 uses notebook pages instead of frames and this is why this method
672 returns a wxWindow and not a wxFrame.
674 wxWindow
* GetFrame();
677 Gets the name associated with the view (passed to the wxDocTemplate
678 constructor). Not currently used by the framework.
680 wxString
GetViewName() const;
683 Called when a view is activated by means of Activate(). The default
684 implementation does nothing.
686 virtual void OnActivateView(bool activate
, wxView
* activeView
,
687 wxView
* deactiveView
);
690 Called when the filename has changed. The default implementation
691 constructs a suitable title and sets the title of the view frame (if
694 virtual void OnChangeFilename();
697 Implements closing behaviour. The default implementation calls
698 wxDocument::Close() to close the associated document. Does not delete
699 the view. The application may wish to do some cleaning up operations in
700 this function, @e if a call to wxDocument::Close() succeeded. For
701 example, if your views all share the same window, you need to
702 disassociate the window from the view and perhaps clear the window. If
703 @a deleteWindow is @true, delete the frame associated with the view.
705 virtual bool OnClose(bool deleteWindow
);
708 Override this to clean up the view when the document is being closed.
710 virtual void OnClosingDocument();
713 wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just
714 after the wxDocTemplate creates the wxView, it calls OnCreate(). The
715 wxView can create a wxDocChildFrame (or derived class) in its
716 wxView::OnCreate() member function. This wxDocChildFrame provides user
717 interface elements to view and/or edit the contents of the wxDocument.
719 By default, simply returns @true. If the function returns @false, the
720 view will be deleted.
722 virtual bool OnCreate(wxDocument
* doc
, long flags
);
725 If the printing framework is enabled in the library, this function
726 returns a wxPrintout object for the purposes of printing. It should
727 create a new object every time it is called; the framework will delete
730 By default, this function returns an instance of wxDocPrintout, which
731 prints and previews one page by calling OnDraw().
733 Override to return an instance of a class other than wxDocPrintout.
735 virtual wxPrintout
* OnCreatePrintout();
738 Override this function to render the view on the given device context.
740 virtual void OnDraw(wxDC
* dc
);
743 Called when the view should be updated.
746 A pointer to the wxView that sent the update request, or @NULL if
747 no single view requested the update (for instance, when the
750 This is unused currently, but may in future contain
751 application-specific information for making updating more
754 virtual void OnUpdate(wxView
* sender
, wxObject
* hint
);
757 Associates the given document with the view. Normally called by the
760 void SetDocument(wxDocument
* doc
);
763 Sets the frame associated with this view. The application should call
764 this if possible, to tell the view about the frame.
766 See GetFrame() for the explanation about the mismatch between the
767 "Frame" in the method name and the type of its parameter.
769 void SetFrame(wxWindow
* frame
);
772 Sets the view type name. Should only be called by the framework.
774 void SetViewName(const wxString
& name
);
777 The document associated with this view. There may be more than one view
778 per document, but there can never be more than one document for one
781 wxDocument
* m_viewDocument
;
784 Frame associated with the view, if any.
786 wxFrame
* m_viewFrame
;
789 The view type name given to the wxDocTemplate constructor, copied to
790 this variable when the view is created. Not currently used by the
793 wxString m_viewTypeName
;
799 @class wxDocChildFrame
801 The wxDocChildFrame class provides a default frame for displaying documents
802 on separate windows. This class can only be used for SDI (not MDI) child
805 The class is part of the document/view framework supported by wxWidgets,
806 and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
812 @see @ref overview_docview, @ref page_samples_docview, wxFrame
814 class wxDocChildFrame
: public wxFrame
820 wxDocChildFrame(wxDocument
* doc
, wxView
* view
, wxFrame
* parent
,
821 wxWindowID id
, const wxString
& title
,
822 const wxPoint
& pos
= wxDefaultPosition
,
823 const wxSize
& size
= wxDefaultSize
,
824 long style
= wxDEFAULT_FRAME_STYLE
,
825 const wxString
& name
= "frame");
833 Returns the document associated with this frame.
835 wxDocument
* GetDocument() const;
838 Returns the view associated with this frame.
840 wxView
* GetView() const;
843 Sets the currently active view to be the frame's view. You may need to
844 override (but still call) this function in order to set the keyboard
845 focus for your subwindow.
847 void OnActivate(wxActivateEvent event
);
850 Closes and deletes the current view and document.
852 void OnCloseWindow(wxCloseEvent
& event
);
855 Sets the document for this frame.
857 void SetDocument(wxDocument
* doc
);
860 Sets the view for this frame.
862 void SetView(wxView
* view
);
865 The document associated with the frame.
867 wxDocument
* m_childDocument
;
870 The view associated with the frame.
878 @class wxDocParentFrame
880 The wxDocParentFrame class provides a default top-level frame for
881 applications using the document/view framework. This class can only be used
882 for SDI (not MDI) parent frames.
884 It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
890 @see @ref overview_docview, @ref page_samples_docview, wxFrame
892 class wxDocParentFrame
: public wxFrame
902 wxDocParentFrame(wxDocManager
* manager
, wxFrame
* parent
,
903 wxWindowID id
, const wxString
& title
,
904 const wxPoint
& pos
= wxDefaultPosition
,
905 const wxSize
& size
= wxDefaultSize
,
906 long style
= wxDEFAULT_FRAME_STYLE
,
907 const wxString
& name
= "frame");
915 Used in two-step construction.
917 bool Create(wxDocManager
* manager
, wxFrame
* parent
,
918 wxWindowID id
, const wxString
& title
,
919 const wxPoint
& pos
= wxDefaultPosition
,
920 const wxSize
& size
= wxDefaultSize
,
921 long style
= wxDEFAULT_FRAME_STYLE
,
922 const wxString
& name
= "frame");
925 Returns the associated document manager object.
927 wxDocManager
* GetDocumentManager() const;
930 Deletes all views and documents. If no user input cancelled the
931 operation, the frame will be destroyed and the application will exit.
932 Since understanding how document/view clean-up takes place can be
933 difficult, the implementation of this function is shown below:
936 void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event)
938 if (m_docManager->Clear(!event.CanVeto()))
947 void OnCloseWindow(wxCloseEvent
& event
);
955 The document class can be used to model an application's file-based data.
956 It is part of the document/view framework supported by wxWidgets, and
957 cooperates with the wxView, wxDocTemplate and wxDocManager classes.
962 @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager
964 class wxDocument
: public wxEvtHandler
968 Constructor. Define your own default constructor to initialize
969 application-specific data.
974 Destructor. Removes itself from the document manager.
979 If the view is not already in the list of views, adds the view and
980 calls OnChangedViewList().
982 virtual bool AddView(wxView
* view
);
985 Closes the document, by calling OnSaveModified() and then (if this
986 returned @true) OnCloseDocument(). This does not normally delete the
987 document object, use DeleteAllViews() to do this implicitly.
989 virtual bool Close();
992 Calls wxView::Close() and deletes each view. Deleting the final view
993 will implicitly delete the document itself, because the wxView
994 destructor calls RemoveView(). This in turns calls OnChangedViewList(),
995 whose default implemention is to save and delete the document if no
998 virtual bool DeleteAllViews();
1001 Returns a pointer to the command processor associated with this
1004 @see wxCommandProcessor
1006 wxCommandProcessor
* GetCommandProcessor() const;
1009 Gets a pointer to the associated document manager.
1011 wxDocManager
* GetDocumentManager() const;
1014 Gets the document type name for this document. See the comment for
1015 @ref m_documentTypeName.
1017 wxString
GetDocumentName() const;
1020 Gets a pointer to the template that created the document.
1022 wxDocTemplate
* GetDocumentTemplate() const;
1025 Intended to return a suitable window for using as a parent for
1026 document-related dialog boxes. By default, uses the frame associated
1027 with the first view.
1029 wxWindow
* GetDocumentWindow() const;
1032 Gets the filename associated with this document, or "" if none is
1035 wxString
GetFilename() const;
1038 A convenience function to get the first view for a document, because in
1039 many cases a document will only have a single view.
1043 wxView
* GetFirstView() const;
1046 Gets the title for this document. The document title is used for an
1047 associated frame (if any), and is usually constructed by the framework
1050 wxString
GetTitle() const;
1053 Return the document name suitable to be shown to the user. The default
1054 implementation uses the document title, if any, of the name part of the
1055 document filename if it was set or, otherwise, the string @b unnamed.
1057 virtual wxString
GetUserReadableName() const;
1060 Returns the list whose elements are the views on the document.
1064 wxList
GetViews() const;
1067 Returns @true if the document has been modified since the last save,
1068 @false otherwise. You may need to override this if your document view
1069 maintains its own record of being modified.
1073 virtual bool IsModified() const;
1077 Override this function and call it from your own LoadObject() before
1078 streaming your own data. LoadObject() is called by the framework
1079 automatically when the document contents need to be loaded.
1081 @note This version of LoadObject() may not exist depending on how
1082 wxWidgets was configured.
1084 virtual istream
& LoadObject(istream
& stream
);
1085 virtual wxInputStream
& LoadObject(wxInputStream
& stream
);
1089 Call with @true to mark the document as modified since the last save,
1090 @false otherwise. You may need to override this if your document view
1091 maintains its own record of being modified.
1095 virtual void Modify(bool modify
);
1098 Called when a view is added to or deleted from this document. The
1099 default implementation saves and deletes the document if no views exist
1100 (the last one has just been removed).
1102 virtual void OnChangedViewList();
1105 The default implementation calls DeleteContents() (an empty
1106 implementation) and sets the modified flag to @false. Override this to
1107 supply additional behaviour when the document is closed with Close().
1109 virtual bool OnCloseDocument();
1112 Called just after the document object is created to give it a chance to
1113 initialize itself. The default implementation uses the template
1114 associated with the document to create an initial view. If this
1115 function returns @false, the document is deleted.
1117 virtual bool OnCreate(const wxString
& path
, long flags
);
1120 Override this function if you want a different (or no) command
1121 processor to be created when the document is created. By default, it
1122 returns an instance of wxCommandProcessor.
1124 @see wxCommandProcessor
1126 virtual wxCommandProcessor
* OnCreateCommandProcessor();
1129 The default implementation calls OnSaveModified() and DeleteContents(),
1130 makes a default title for the document, and notifies the views that the
1131 filename (in fact, the title) has changed.
1133 virtual bool OnNewDocument();
1136 Constructs an input file stream for the given filename (which must not
1137 be empty), and calls LoadObject(). If LoadObject() returns @true, the
1138 document is set to unmodified; otherwise, an error message box is
1139 displayed. The document's views are notified that the filename has
1140 changed, to give windows an opportunity to update their titles. All of
1141 the document's views are then updated.
1143 virtual bool OnOpenDocument(const wxString
& filename
);
1146 Constructs an output file stream for the given filename (which must not
1147 be empty), and calls SaveObject(). If SaveObject() returns @true, the
1148 document is set to unmodified; otherwise, an error message box is
1151 virtual bool OnSaveDocument(const wxString
& filename
);
1154 If the document has been modified, prompts the user to ask if the
1155 changes should be changed. If the user replies Yes, the Save() function
1156 is called. If No, the document is marked as unmodified and the function
1157 succeeds. If Cancel, the function fails.
1159 virtual bool OnSaveModified();
1162 Removes the view from the document's list of views, and calls
1163 OnChangedViewList().
1165 virtual bool RemoveView(wxView
* view
);
1168 Saves the document by calling OnSaveDocument() if there is an
1169 associated filename, or SaveAs() if there is no filename.
1171 virtual bool Save();
1174 Prompts the user for a file to save to, and then calls
1177 virtual bool SaveAs();
1181 Override this function and call it from your own SaveObject() before
1182 streaming your own data. SaveObject() is called by the framework
1183 automatically when the document contents need to be saved.
1185 @note This version of SaveObject() may not exist depending on how
1186 wxWidgets was configured.
1188 virtual ostream
& SaveObject(ostream
& stream
);
1189 virtual wxOutputStream
& SaveObject(wxOutputStream
& stream
);
1193 Sets the command processor to be used for this document. The document
1194 will then be responsible for its deletion. Normally you should not call
1195 this; override OnCreateCommandProcessor() instead.
1197 @see wxCommandProcessor
1199 virtual void SetCommandProcessor(wxCommandProcessor
* processor
);
1202 Sets the document type name for this document. See the comment for
1203 @ref m_documentTypeName.
1205 void SetDocumentName(const wxString
& name
);
1208 Sets the pointer to the template that created the document. Should only
1209 be called by the framework.
1211 void SetDocumentTemplate(wxDocTemplate
* templ
);
1214 Sets the filename for this document. Usually called by the framework.
1216 If @a notifyViews is @true, wxView::OnChangeFilename() is called for
1219 void SetFilename(const wxString
& filename
, bool notifyViews
= false);
1222 Sets the title for this document. The document title is used for an
1223 associated frame (if any), and is usually constructed by the framework
1226 void SetTitle(const wxString
& title
);
1229 Updates all views. If @a sender is non-@NULL, does not update this
1230 view. @a hint represents optional information to allow a view to
1231 optimize its update.
1233 void UpdateAllViews(wxView
* sender
= NULL
, wxObject
* hint
= NULL
);
1237 This method is called by OnSaveDocument() to really save the document
1238 contents to the specified file.
1240 Base class version creates a file-based stream and calls SaveObject().
1241 Override this if you need to do something else or prefer not to use
1242 SaveObject() at all.
1244 virtual bool DoSaveDocument(const wxString
& file
);
1247 This method is called by OnOpenDocument() to really load the document
1248 contents from the specified file.
1250 Base class version creates a file-based stream and calls LoadObject().
1251 Override this if you need to do something else or prefer not to use
1252 LoadObject() at all.
1254 virtual bool DoOpenDocument(const wxString
& file
);
1257 A pointer to the command processor associated with this document.
1259 wxCommandProcessor
* m_commandProcessor
;
1262 Filename associated with this document ("" if none).
1264 wxString m_documentFile
;
1267 @true if the document has been modified, @false otherwise.
1269 bool m_documentModified
;
1272 A pointer to the template from which this document was created.
1274 wxDocTemplate
* m_documentTemplate
;
1277 Document title. The document title is used for an associated frame (if
1278 any), and is usually constructed by the framework from the filename.
1280 wxString m_documentTitle
;
1283 The document type name given to the wxDocTemplate constructor, copied
1284 to this variable when the document is created. If several document
1285 templates are created that use the same document type, this variable is
1286 used in wxDocManager::CreateView() to collate a list of alternative
1287 view types that can be used on this kind of document. Do not change the
1288 value of this variable.
1290 wxString m_documentTypeName
;
1293 List of wxView instances associated with this document.
1295 wxList m_documentViews
;
1301 @class wxFileHistory
1303 The wxFileHistory encapsulates a user interface convenience, the list of
1304 most recently visited files as shown on a menu (usually the File menu).
1306 wxFileHistory can manage one or more file menus. More than one menu may be
1307 required in an MDI application, where the file history should appear on
1308 each MDI child menu as well as the MDI parent frame.
1313 @see @ref overview_docview, wxDocManager
1315 class wxFileHistory
: public wxObject
1319 Constructor. Pass the maximum number of files that should be stored and
1322 @a idBase defaults to wxID_FILE1 and represents the id given to the
1323 first history menu item. Since menu items can't share the same ID you
1324 should change @a idBase (to one of your own defined IDs) when using
1325 more than one wxFileHistory in your application.
1327 wxFileHistory(size_t maxFiles
= 9, wxWindowID idBase
= wxID_FILE1
);
1335 Adds a file to the file history list, if the object has a pointer to an
1336 appropriate file menu.
1338 void AddFileToHistory(const wxString
& filename
);
1341 Appends the files in the history list, to all menus managed by the file
1344 void AddFilesToMenu();
1346 Appends the files in the history list, to the given menu only.
1348 void AddFilesToMenu(wxMenu
* menu
);
1351 Returns the base identifier for the range used for appending items.
1353 wxWindowID
GetBaseId() const;
1356 Returns the number of files currently stored in the file history.
1358 size_t GetCount() const;
1361 Returns the file at this index (zero-based).
1363 wxString
GetHistoryFile(size_t index
) const;
1366 Returns the maximum number of files that can be stored.
1368 int GetMaxFiles() const;
1371 Returns the list of menus that are managed by this file history object.
1375 const wxList
& GetMenus() const;
1378 Loads the file history from the given config object. This function
1379 should be called explicitly by the application.
1383 void Load(const wxConfigBase
& config
);
1386 Removes the specified file from the history.
1388 void RemoveFileFromHistory(size_t i
);
1391 Removes this menu from the list of those managed by this object.
1393 void RemoveMenu(wxMenu
* menu
);
1396 Saves the file history into the given config object. This must be
1397 called explicitly by the application.
1401 void Save(wxConfigBase
& config
);
1404 Sets the base identifier for the range used for appending items.
1406 void SetBaseId(wxWindowID baseId
);
1409 Adds this menu to the list of those menus that are managed by this file
1410 history object. Also see AddFilesToMenu() for initializing the menu
1411 with filenames that are already in the history when this function is
1412 called, as this is not done automatically.
1414 void UseMenu(wxMenu
* menu
);
1417 A character array of strings corresponding to the most recently opened
1420 char** m_fileHistory
;
1423 The number of files stored in the history array.
1425 size_t m_fileHistoryN
;
1428 The maximum number of files to be stored and displayed on the menu.
1430 size_t m_fileMaxFiles
;
1433 The file menu used to display the file history list (if enabled).
1440 // ============================================================================
1441 // Global functions/macros
1442 // ============================================================================
1444 /** @ingroup group_funcmacro_file */
1448 Copies the given file to @a stream. Useful when converting an old
1449 application to use streams (within the document/view framework, for
1452 @header{wx/docview.h}
1454 bool wxTransferFileToStream(const wxString
& filename
,
1458 Copies the given stream to the file @a filename. Useful when converting an
1459 old application to use streams (within the document/view framework, for
1462 @header{wx/docview.h}
1464 bool wxTransferStreamToFile(istream
& stream
,
1465 const wxString
& filename
);