1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of various doc/view framework classes
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 A vector of wxDocument pointers.
14 typedef wxVector
<wxDocument
*> wxDocVector
;
17 A vector of wxView pointers.
21 typedef wxVector
<wxView
*> wxViewVector
;
24 A vector of wxDocTemplate pointers.
28 typedef wxVector
<wxDocTemplate
*> wxDocTemplateVector
;
33 The wxDocTemplate class is used to model the relationship between a
34 document class and a view class.
39 @see @ref overview_docview_wxdoctemplate, wxDocument, wxView
41 class wxDocTemplate
: public wxObject
45 Constructor. Create instances dynamically near the start of your
46 application after creating a wxDocManager instance, and before doing
47 any document or view operations.
50 The document manager object which manages this template.
52 A short description of what the template is for. This string will
53 be displayed in the file filter list of Windows file selectors.
55 An appropriate file filter such as "*.txt".
57 The default directory to use for file selectors.
59 The default file extension (such as "txt").
61 A name that should be unique for a given type of document, used for
62 gathering a list of views relevant to a particular document.
64 A name that should be unique for a given view.
66 A pointer to the run-time document class information as returned by
67 the wxCLASSINFO() macro, e.g. wxCLASSINFO(MyDocumentClass). If this is
68 not supplied, you will need to derive a new wxDocTemplate class and
69 override the CreateDocument() member to return a new document
72 A pointer to the run-time view class information as returned by the
73 wxCLASSINFO() macro, e.g. wxCLASSINFO(MyViewClass). If this is not
74 supplied, you will need to derive a new wxDocTemplate class and
75 override the CreateView() member to return a new view instance on
78 A bit list of the following:
79 - wxTEMPLATE_VISIBLE - The template may be displayed to the
81 - wxTEMPLATE_INVISIBLE - The template may not be displayed to
83 - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE.
87 In wxPerl @a docClassInfo and @a viewClassInfo can be either
88 @c Wx::ClassInfo objects or strings containing the name of the
89 perl packages which are to be used as @c Wx::Document and
90 @c Wx::View classes (they must have a constructor named new);
93 - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
94 docTypeName, viewTypeName, docClassInfo, viewClassInfo,
95 flags): will construct document and view objects from the
97 - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
98 docTypeName, viewTypeName, docClassName, viewClassName,
99 flags): will construct document and view objects from perl
101 - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
102 docTypeName, viewTypeName):
103 in this case @c Wx::DocTemplate::CreateDocument() and
104 @c Wx::DocTemplate::CreateView() must be overridden
107 wxDocTemplate(wxDocManager
* manager
, const wxString
& descr
,
108 const wxString
& filter
, const wxString
& dir
,
109 const wxString
& ext
, const wxString
& docTypeName
,
110 const wxString
& viewTypeName
, wxClassInfo
* docClassInfo
= 0,
111 wxClassInfo
* viewClassInfo
= 0,
112 long flags
= wxTEMPLATE_VISIBLE
);
117 virtual ~wxDocTemplate();
120 Creates a new instance of the associated document class. If you have
121 not supplied a wxClassInfo parameter to the template constructor, you
122 will need to override this function to return an appropriate document
125 This function calls InitDocument() which in turns calls
126 wxDocument::OnCreate().
128 virtual wxDocument
* CreateDocument(const wxString
& path
, long flags
= 0);
131 Creates a new instance of the associated view class.
133 If you have not supplied a wxClassInfo parameter to the template
134 constructor, you will need to override this function to return an
135 appropriate view instance.
137 If the new view initialization fails, it must call
138 wxDocument::RemoveView() for consistency with the default behaviour of
141 virtual wxView
* CreateView(wxDocument
* doc
, long flags
= 0);
144 This function implements the default (very primitive) format detection
145 which checks if the extension is that of the template.
148 The path to be checked against the template.
150 virtual bool FileMatchesTemplate(const wxString
& path
);
153 Returns the default file extension for the document data, as passed to
154 the document template constructor.
156 wxString
GetDefaultExtension() const;
159 Returns the text description of this template, as passed to the
160 document template constructor.
162 wxString
GetDescription() const;
165 Returns the default directory, as passed to the document template
168 wxString
GetDirectory() const;
171 Returns the run-time class information that allows document
172 instances to be constructed dynamically, as passed to the document
173 template constructor.
175 wxClassInfo
* GetDocClassInfo() const;
178 Returns a pointer to the document manager instance for which this
179 template was created.
181 wxDocManager
* GetDocumentManager() const;
184 Returns the document type name, as passed to the document template
187 virtual wxString
GetDocumentName() const;
190 Returns the file filter, as passed to the document template
193 wxString
GetFileFilter() const;
196 Returns the flags, as passed to the document template constructor.
198 long GetFlags() const;
201 Returns a reference to the wxPageSetupDialogData associated with the
202 printing operations of this document manager.
205 wxPageSetupDialogData
& GetPageSetupDialogData();
206 const wxPageSetupDialogData
& GetPageSetupDialogData() const;
210 Returns the run-time class information that allows view instances
211 to be constructed dynamically, as passed to the document template
214 wxClassInfo
* GetViewClassInfo() const;
217 Returns the view type name, as passed to the document template
220 virtual wxString
GetViewName() const;
223 Initialises the document, calling wxDocument::OnCreate().
225 This is called from CreateDocument().
227 If you override this method, notice that you must @em delete the @a doc
228 if its initialization fails for consistency with the default behaviour.
231 The document to initialize.
233 The associated file path.
235 Flags passed to CreateDocument().
237 @true if the initialization was successful or @false if it failed
238 in which case @a doc should be deleted by this function.
240 virtual bool InitDocument(wxDocument
* doc
,
241 const wxString
& path
,
245 Returns @true if the document template can be shown in user dialogs,
248 bool IsVisible() const;
251 Sets the default file extension.
253 void SetDefaultExtension(const wxString
& ext
);
256 Sets the template description.
258 void SetDescription(const wxString
& descr
);
261 Sets the default directory.
263 void SetDirectory(const wxString
& dir
);
266 Sets the pointer to the document manager instance for which this
267 template was created. Should not be called by the application.
269 void SetDocumentManager(wxDocManager
* manager
);
272 Sets the file filter.
274 void SetFileFilter(const wxString
& filter
);
277 Sets the internal document template flags (see the constructor
278 description for more details).
280 void SetFlags(long flags
);
283 The default extension for files of this type.
285 wxString m_defaultExt
;
288 A short description of this template.
290 wxString m_description
;
293 The default directory for files of this type.
295 wxString m_directory
;
298 Run-time class information that allows document instances to be
299 constructed dynamically.
301 wxClassInfo
* m_docClassInfo
;
304 The named type of the document associated with this template.
306 wxString m_docTypeName
;
309 A pointer to the document manager for which this template was created.
311 wxDocTemplate
* m_documentManager
;
314 The file filter (such as "*.txt") to be used in file selector dialogs.
316 wxString m_fileFilter
;
319 The flags passed to the constructor.
324 Run-time class information that allows view instances to be constructed
327 wxClassInfo
* m_viewClassInfo
;
330 The named type of the view associated with this template.
332 wxString m_viewTypeName
;
340 The wxDocManager class is part of the document/view framework supported by
341 wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate
347 @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate,
350 class wxDocManager
: public wxEvtHandler
354 Constructor. Create a document manager instance dynamically near the
355 start of your application before doing any document or view operations.
357 If @a initialize is @true, the Initialize() function will be called to
358 create a default history list object. If you derive from wxDocManager,
359 you may wish to call the base constructor with @false, and then call
360 Initialize() in your own constructor, to allow your own Initialize() or
361 OnCreateFileHistory functions to be called.
366 Indicates whether Initialize() should be called by this ctor.
368 wxDocManager(long flags
= 0, bool initialize
= true);
373 virtual ~wxDocManager();
376 Sets the current view.
378 virtual void ActivateView(wxView
* doc
, bool activate
= true);
381 Adds the document to the list of documents.
383 void AddDocument(wxDocument
* doc
);
386 Adds a file to the file history list, if we have a pointer to an
387 appropriate file menu.
389 virtual void AddFileToHistory(const wxString
& filename
);
392 Adds the template to the document manager's template list.
394 void AssociateTemplate(wxDocTemplate
* temp
);
397 Search for a particular document template.
401 // creating a document instance of the specified document type:
402 m_doc = (MyDoc*)docManager->FindTemplate(CLASSINFO(MyDoc))->
403 CreateDocument(wxEmptyString, wxDOC_SILENT);
407 Class info of a document class for which a wxDocTemplate had been
411 Pointer to a wxDocTemplate, or @NULL if none found.
415 wxDocTemplate
* FindTemplate(const wxClassInfo
* classinfo
);
419 Search for the document corresponding to the given file.
424 Pointer to a wxDocument, or @NULL if none found.
428 wxDocument
* FindDocumentByPath(const wxString
& path
) const;
431 Closes the specified document.
433 If @a force is @true, the document is closed even if it has unsaved
437 The document to close, must be non-@NULL.
439 If @true, close the document even if wxDocument::Close() returns
442 @true if the document was closed or @false if closing it was
443 cancelled by user (only in @a force = @false case).
445 bool CloseDocument(wxDocument
*doc
, bool force
= false);
448 Closes all currently opened documents.
452 bool CloseDocuments(bool force
= true);
455 Creates a new document.
457 This function can either create a document corresponding to a new
458 file or to an already existing one depending on whether @c wxDOC_NEW is
459 specified in the @a flags.
461 By default, this function asks the user for the type of document to
462 open and the path to its file if it's not specified, i.e. if @a path is
463 empty. Specifying @c wxDOC_SILENT flag suppresses any prompts and means
464 that the @a path must be non-empty and there must be a registered
465 document template handling the extension of this file, otherwise a
466 warning message is logged and the function returns @NULL. Notice that
467 @c wxDOC_SILENT can be combined with @c wxDOC_NEW, however in this case
468 the @a path must still be specified, even if the file with this path
469 typically won't exist.
471 Finally notice that if this document manager was configured to allow
472 only a limited number of simultaneously opened documents using
473 SetMaxDocsOpen(), this function will try to close the oldest existing
474 document if this number was reached before creating a new document.
475 And if closing the old document fails (e.g. because it was vetoed by
476 user), this function fails as well.
479 Path to a file or an empty string. If the path is empty, the user
480 will be asked to select it (thus, this is incompatible with the use
481 of @c wxDOC_SILENT). The file should exist unless @a flags includes
484 By default, none. May include @c wxDOC_NEW to indicate that the new
485 document corresponds to a new file and not an existing one and
486 @c wxDOC_SILENT to suppress any dialogs asking the user about the
488 @return a new document object or @NULL on failure.
490 virtual wxDocument
* CreateDocument(const wxString
& path
, long flags
= 0);
493 Creates an empty new document.
495 This is equivalent to calling CreateDocument() with @c wxDOC_NEW flags
496 and without the file name.
498 wxDocument
*CreateNewDocument();
501 Creates a new view for the given document. If more than one view is
502 allowed for the document (by virtue of multiple templates mentioning
503 the same document type), a choice of view is presented to the user.
505 virtual wxView
* CreateView(wxDocument
* doc
, long flags
= 0);
508 Removes the template from the list of templates.
510 void DisassociateTemplate(wxDocTemplate
* temp
);
513 Appends the files in the history list to all menus managed by the file
516 virtual void FileHistoryAddFilesToMenu();
518 Appends the files in the history list to the given @a menu only.
520 virtual void FileHistoryAddFilesToMenu(wxMenu
* menu
);
523 Loads the file history from a config object.
527 virtual void FileHistoryLoad(const wxConfigBase
& config
);
530 Removes the given menu from the list of menus managed by the file
533 virtual void FileHistoryRemoveMenu(wxMenu
* menu
);
536 Saves the file history into a config object. This must be called
537 explicitly by the application.
541 virtual void FileHistorySave(wxConfigBase
& resourceFile
);
544 Use this menu for appending recently-visited document filenames, for
545 convenient access. Calling this function with a valid menu pointer
546 enables the history list functionality.
548 @note You can add multiple menus using this function, to be managed by
549 the file history object.
551 virtual void FileHistoryUseMenu(wxMenu
* menu
);
554 Given a path, try to find template that matches the extension. This is
555 only an approximate method of finding a template for creating a
558 virtual wxDocTemplate
* FindTemplateForPath(const wxString
& path
);
561 Returns the document associated with the currently active view (if
564 wxDocument
* GetCurrentDocument() const;
567 Returns the currently active view
569 virtual wxView
* GetCurrentView() const;
572 Returns a vector of wxDocument pointers.
576 wxDocVector
GetDocumentsVector() const;
579 Returns a vector of wxDocTemplate pointers.
583 wxDocTemplateVector
GetTemplatesVector() const;
586 Returns a reference to the list of documents.
588 wxList
& GetDocuments();
591 Returns a pointer to file history.
593 virtual wxFileHistory
* GetFileHistory() const;
596 Returns the number of files currently stored in the file history.
598 virtual size_t GetHistoryFilesCount() const;
601 Returns the directory last selected by the user when opening a file.
604 wxString
GetLastDirectory() const;
607 Returns the number of documents that can be open simultaneously.
609 int GetMaxDocsOpen() const;
612 Returns a reference to the list of associated templates.
614 wxList
& GetTemplates();
617 Initializes data; currently just calls OnCreateFileHistory().
619 Some data cannot always be initialized in the constructor because the
620 programmer must be given the opportunity to override functionality. If
621 OnCreateFileHistory() was called from the constructor, an overridden
622 virtual OnCreateFileHistory() would not be called due to C++'s
623 'interesting' constructor semantics. In fact Initialize() @e is called
624 from the wxDocManager constructor, but this can be vetoed by passing
625 @false to the second argument, allowing the derived class's constructor
626 to call Initialize(), possibly calling a different
627 OnCreateFileHistory() from the default.
629 The bottom line: if you're not deriving from Initialize(), forget it
630 and construct wxDocManager with no arguments.
632 virtual bool Initialize();
635 Return a string containing a suitable default name for a new document.
636 By default this is implemented by appending an integer counter to the
637 string @b unnamed but can be overridden in the derived classes to do
638 something more appropriate.
640 virtual wxString
MakeNewDocumentName();
643 A hook to allow a derived class to create a different type of file
644 history. Called from Initialize().
646 virtual wxFileHistory
* OnCreateFileHistory();
649 Closes and deletes the currently active document.
651 void OnFileClose(wxCommandEvent
& event
);
654 Closes and deletes all the currently opened documents.
656 void OnFileCloseAll(wxCommandEvent
& event
);
659 Creates a document from a list of templates (if more than one
662 void OnFileNew(wxCommandEvent
& event
);
665 Creates a new document and reads in the selected file.
667 void OnFileOpen(wxCommandEvent
& event
);
670 Reverts the current document by calling wxDocument::Revert() for the
673 void OnFileRevert(wxCommandEvent
& event
);
676 Saves the current document by calling wxDocument::Save() for the
679 void OnFileSave(wxCommandEvent
& event
);
682 Calls wxDocument::SaveAs() for the current document.
684 void OnFileSaveAs(wxCommandEvent
& event
);
687 Removes the document from the list of documents.
689 void RemoveDocument(wxDocument
* doc
);
692 Under Windows, pops up a file selector with a list of filters
693 corresponding to document templates. The wxDocTemplate corresponding to
694 the selected file's extension is returned.
696 On other platforms, if there is more than one document template a
697 choice list is popped up, followed by a file selector.
699 This function is used in CreateDocument().
702 In wxPerl @a templates is a reference to a list of templates.
703 If you override this method in your document manager it must
704 return two values, eg:
707 (doctemplate, path) = My::DocManager->SelectDocumentPath(...);
711 virtual wxDocTemplate
* SelectDocumentPath(wxDocTemplate
** templates
,
712 int noTemplates
, wxString
& path
,
713 long flags
, bool save
= false);
716 Returns a document template by asking the user (if there is more than
717 one template). This function is used in CreateDocument().
720 Pointer to an array of templates from which to choose a desired
723 Number of templates being pointed to by the templates pointer.
725 If more than one template is passed into templates, then this
726 parameter indicates whether the list of templates that the user
727 will have to choose from is sorted or not when shown the choice box
728 dialog. Default is @false.
731 In wxPerl @a templates is a reference to a list of templates.
734 virtual wxDocTemplate
* SelectDocumentType(wxDocTemplate
** templates
,
739 Returns a document template by asking the user (if there is more than
740 one template), displaying a list of valid views. This function is used
741 in CreateView(). The dialog normally will not appear because the array
742 of templates only contains those relevant to the document in question,
743 and often there will only be one such.
746 Pointer to an array of templates from which to choose a desired
749 Number of templates being pointed to by the templates pointer.
751 If more than one template is passed into templates, then this
752 parameter indicates whether the list of templates that the user
753 will have to choose from is sorted or not when shown the choice box
754 dialog. Default is @false.
757 In wxPerl @a templates is a reference to a list of templates.
760 virtual wxDocTemplate
* SelectViewType(wxDocTemplate
** templates
,
761 int noTemplates
, bool sort
= false);
764 Sets the directory to be displayed to the user when opening a file.
765 Initially this is empty.
767 void SetLastDirectory(const wxString
& dir
);
770 Sets the maximum number of documents that can be open at a time. By
771 default, this is @c INT_MAX, i.e. the number of documents is unlimited.
772 If you set it to 1, existing documents will be saved and deleted when
773 the user tries to open or create a new one (similar to the behaviour of
774 Windows Write, for example). Allowing multiple documents gives
775 behaviour more akin to MS Word and other Multiple Document Interface
778 void SetMaxDocsOpen(int n
);
783 Called when a file selected from the MRU list doesn't exist any more.
785 The default behaviour is to remove the file from the MRU (most recently
786 used) files list and the corresponding menu and notify the user about
787 it but this method can be overridden to customize it.
789 For example, an application may want to just give an error about the
790 missing file @a filename but not remove it from the file history. Or it
791 could ask the user whether the file should be kept or removed.
793 Notice that this method is called only if the file selected by user
794 from the MRU files in the menu doesn't exist, but not if opening it
795 failed for any other reason because in the latter case the default
796 behaviour of removing the file from the MRU list is inappropriate.
797 If you still want to do it, you would need to do it by calling
798 RemoveFileFromHistory() explicitly in the part of the file opening code
804 The index of the file in the MRU list, it can be passed to
805 RemoveFileFromHistory() to remove this file from the list.
807 The full name of the file.
809 virtual void OnMRUFileNotExist(unsigned n
, const wxString
& filename
);
812 Create the frame used for print preview.
814 This method can be overridden if you need to change the behaviour or
815 appearance of the preview window. By default, a standard wxPreviewFrame
820 @param preview The associated preview object.
821 @param parent The parent window for the frame.
822 @param title The suggested title for the print preview frame.
823 @return A new print preview frame, must not return @NULL.
825 virtual wxPreviewFrame
* CreatePreviewFrame(wxPrintPreviewBase
* preview
,
827 const wxString
& title
);
830 The currently active view.
832 wxView
* m_currentView
;
835 Stores the integer to be used for the next default document name.
837 int m_defaultDocumentNameCounter
;
840 A list of all documents.
845 A pointer to an instance of wxFileHistory, which manages the history of
846 recently-visited files on the File menu.
848 wxFileHistory
* m_fileHistory
;
851 The directory last selected by the user when opening a file.
853 wxString m_lastDirectory
;
856 Stores the maximum number of documents that can be opened before
857 existing documents are closed.
859 By default, this is @c INT_MAX i.e. practically unlimited.
869 The view class can be used to model the viewing and editing component of
870 an application's file-based data. It is part of the document/view framework
871 supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
872 and wxDocManager classes.
877 @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager
879 class wxView
: public wxEvtHandler
883 Constructor. Define your own default constructor to initialize
884 application-specific data.
889 Destructor. Removes itself from the document's list of views.
894 Call this from your view frame's wxDocChildFrame::OnActivate() member
895 to tell the framework which view is currently active. If your windowing
896 system doesn't call wxDocChildFrame::OnActivate(), you may need to call
897 this function from any place where you know the view must be active,
898 and the framework will need to get the current view.
900 The prepackaged view frame wxDocChildFrame calls Activate() from its
901 wxDocChildFrame::OnActivate() member.
903 This function calls OnActivateView().
905 virtual void Activate(bool activate
);
908 Closes the view by calling OnClose(). If @a deleteWindow is @true, this
909 function should delete the window associated with the view.
911 virtual bool Close(bool deleteWindow
= true);
914 Gets a pointer to the document associated with the view.
916 wxDocument
* GetDocument() const;
919 Returns a pointer to the document manager instance associated with this
922 wxDocManager
* GetDocumentManager() const;
925 Gets the frame associated with the view (if any). Note that this
926 "frame" is not a wxFrame at all in the generic MDI implementation which
927 uses notebook pages instead of frames and this is why this method
928 returns a wxWindow and not a wxFrame.
930 wxWindow
* GetFrame() const;
933 Gets the name associated with the view (passed to the wxDocTemplate
934 constructor). Not currently used by the framework.
936 wxString
GetViewName() const;
939 Called when a view is activated by means of Activate(). The default
940 implementation does nothing.
942 virtual void OnActivateView(bool activate
, wxView
* activeView
,
943 wxView
* deactiveView
);
946 Called when the filename has changed. The default implementation
947 constructs a suitable title and sets the title of the view frame (if any).
949 virtual void OnChangeFilename();
952 Implements closing behaviour. The default implementation calls
953 wxDocument::Close() to close the associated document. Does not delete
954 the view. The application may wish to do some cleaning up operations in
955 this function, @e if a call to wxDocument::Close() succeeded. For
956 example, if your views all share the same window, you need to
957 disassociate the window from the view and perhaps clear the window. If
958 @a deleteWindow is @true, delete the frame associated with the view.
960 virtual bool OnClose(bool deleteWindow
);
963 Override this to clean up the view when the document is being closed.
965 virtual void OnClosingDocument();
968 wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just
969 after the wxDocTemplate creates the wxView, it calls OnCreate(). The
970 wxView can create a wxDocChildFrame (or derived class) in its
971 wxView::OnCreate() member function. This wxDocChildFrame provides user
972 interface elements to view and/or edit the contents of the wxDocument.
974 By default, simply returns @true. If the function returns @false, the
975 view will be deleted.
977 virtual bool OnCreate(wxDocument
* doc
, long flags
);
980 If the printing framework is enabled in the library, this function
981 returns a wxPrintout object for the purposes of printing. It should
982 create a new object every time it is called; the framework will delete
985 By default, this function returns an instance of wxDocPrintout, which
986 prints and previews one page by calling OnDraw().
988 Override to return an instance of a class other than wxDocPrintout.
990 virtual wxPrintout
* OnCreatePrintout();
993 Override this function to render the view on the given device context.
995 virtual void OnDraw(wxDC
* dc
) = 0;
998 Called when the view should be updated.
1001 A pointer to the wxView that sent the update request, or @NULL if
1002 no single view requested the update (for instance, when the
1003 document is opened).
1005 This is unused currently, but may in future contain
1006 application-specific information for making updating more
1009 virtual void OnUpdate(wxView
* sender
, wxObject
* hint
= 0);
1012 Associates the given document with the view. Normally called by the
1015 virtual void SetDocument(wxDocument
* doc
);
1018 Sets the frame associated with this view. The application should call
1019 this if possible, to tell the view about the frame.
1021 See GetFrame() for the explanation about the mismatch between the
1022 "Frame" in the method name and the type of its parameter.
1024 void SetFrame(wxWindow
* frame
);
1027 Sets the view type name. Should only be called by the framework.
1029 void SetViewName(const wxString
& name
);
1032 The document associated with this view. There may be more than one view
1033 per document, but there can never be more than one document for one
1036 wxDocument
* m_viewDocument
;
1039 Frame associated with the view, if any.
1041 wxFrame
* m_viewFrame
;
1044 The view type name given to the wxDocTemplate constructor, copied to
1045 this variable when the view is created. Not currently used by the
1048 wxString m_viewTypeName
;
1054 @class wxDocChildFrame
1056 The wxDocChildFrame class provides a default frame for displaying documents
1057 on separate windows. This class can only be used for SDI (not MDI) child
1060 The class is part of the document/view framework supported by wxWidgets,
1061 and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
1064 Notice that this class handles ::wxEVT_ACTIVATE event and activates the
1065 child view on receiving it. Don't intercept this event unless you want to
1066 prevent from this happening.
1068 The same remark applies to ::wxEVT_CLOSE_WINDOW, as wxDocParentFrame the
1069 frame handles this event by trying to close the associated view.
1074 @see @ref overview_docview, @ref page_samples_docview, wxFrame
1076 class wxDocChildFrame
: public wxFrame
1082 wxDocChildFrame(wxDocument
* doc
, wxView
* view
, wxFrame
* parent
,
1083 wxWindowID id
, const wxString
& title
,
1084 const wxPoint
& pos
= wxDefaultPosition
,
1085 const wxSize
& size
= wxDefaultSize
,
1086 long style
= wxDEFAULT_FRAME_STYLE
,
1087 const wxString
& name
= wxFrameNameStr
);
1092 virtual ~wxDocChildFrame();
1095 Returns the document associated with this frame.
1097 wxDocument
* GetDocument() const;
1100 Returns the view associated with this frame.
1102 wxView
* GetView() const;
1105 Sets the document for this frame.
1107 void SetDocument(wxDocument
* doc
);
1110 Sets the view for this frame.
1112 void SetView(wxView
* view
);
1115 The document associated with the frame.
1117 wxDocument
* m_childDocument
;
1120 The view associated with the frame.
1122 wxView
* m_childView
;
1128 @class wxDocParentFrame
1130 The wxDocParentFrame class provides a default top-level frame for
1131 applications using the document/view framework. This class can only be used
1132 for SDI (not MDI) parent frames.
1134 It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
1137 Notice that this class processes ::wxEVT_CLOSE_WINDOW event and tries to
1138 close all open views from its handler. If all the views can be closed, i.e.
1139 if none of them contains unsaved changes or the user decides to not save
1140 them, the window is destroyed. Don't intercept this event in your code
1141 unless you want to replace this logic.
1146 @see @ref overview_docview, @ref page_samples_docview, wxFrame
1148 class wxDocParentFrame
: public wxFrame
1152 Default constructor.
1158 wxDocParentFrame(wxDocManager
* manager
, wxFrame
* parent
,
1159 wxWindowID id
, const wxString
& title
,
1160 const wxPoint
& pos
= wxDefaultPosition
,
1161 const wxSize
& size
= wxDefaultSize
,
1162 long style
= wxDEFAULT_FRAME_STYLE
,
1163 const wxString
& name
= wxFrameNameStr
);
1168 virtual ~wxDocParentFrame();
1171 Used in two-step construction.
1173 bool Create(wxDocManager
* manager
, wxFrame
* parent
, wxWindowID id
,
1174 const wxString
& title
, const wxPoint
& pos
= wxDefaultPosition
,
1175 const wxSize
& size
= wxDefaultSize
, long style
= 541072960,
1176 const wxString
& name
= wxFrameNameStr
);
1179 Returns the associated document manager object.
1181 wxDocManager
* GetDocumentManager() const;
1189 The document class can be used to model an application's file-based data.
1191 It is part of the document/view framework supported by wxWidgets, and
1192 cooperates with the wxView, wxDocTemplate and wxDocManager classes.
1194 A normal document is the one created without parent document and is
1195 associated with a disk file. Since version 2.9.2 wxWidgets also supports a
1196 special kind of documents called <em>child documents</em> which are virtual
1197 in the sense that they do not correspond to a file but rather to a part of
1198 their parent document. Because of this, the child documents can't be
1199 created directly by user but can only be created by the parent document
1200 (usually when it's being created itself). They also can't be independently
1201 saved. A child document has its own view with the corresponding window.
1202 This view can be closed by user but, importantly, is also automatically
1203 closed when its parent document is closed. Thus, child documents may be
1204 convenient for creating additional windows which need to be closed when the
1205 main document is. The docview sample demonstrates this use of child
1206 documents by creating a child document containing the information about the
1207 parameters of the image opened in the main document.
1212 @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager
1214 class wxDocument
: public wxEvtHandler
1218 Constructor. Define your own default constructor to initialize
1219 application-specific data.
1222 Specifying a non-@c NULL parent document here makes this document a
1223 special <em>child document</em>, see their description in the class
1224 documentation. Notice that this parameter exists but is ignored in
1225 wxWidgets versions prior to 2.9.1.
1227 wxDocument(wxDocument
* parent
= NULL
);
1230 Destructor. Removes itself from the document manager.
1232 virtual ~wxDocument();
1235 If the view is not already in the list of views, adds the view and
1236 calls OnChangedViewList().
1238 virtual bool AddView(wxView
* view
);
1241 Returns true if the document hasn't been modified since the last time
1244 Notice that this function returns @false if the document had been never
1245 saved at all, so it may be also used to test whether it makes sense to
1246 save the document: if it returns @true, there is nothing to save but if
1247 @false is returned, it can be saved, even if it might be not modified
1248 (this can be used to create an empty document file by the user).
1250 @see IsModified(), GetDocumentSaved()
1254 bool AlreadySaved() const;
1257 Activate the first view of the document if any.
1263 void Activate() const;
1266 Closes the document, by calling OnSaveModified() and then (if this
1267 returned @true) OnCloseDocument(). This does not normally delete the
1268 document object, use DeleteAllViews() to do this implicitly.
1270 virtual bool Close();
1273 Calls wxView::Close() and deletes each view. Deleting the final view
1274 will implicitly delete the document itself, because the wxView
1275 destructor calls RemoveView(). This in turns calls OnChangedViewList(),
1276 whose default implemention is to save and delete the document if no
1279 virtual bool DeleteAllViews();
1282 Virtual method called from OnCloseDocument().
1284 This method may be overridden to perform any additional cleanup which
1285 might be needed when the document is closed.
1287 The return value of this method is currently ignored.
1289 The default version does nothing and simply returns @true.
1291 virtual bool DeleteContents();
1294 Returns a pointer to the command processor associated with this
1297 @see wxCommandProcessor
1299 virtual wxCommandProcessor
* GetCommandProcessor() const;
1302 Gets a pointer to the associated document manager.
1304 virtual wxDocManager
* GetDocumentManager() const;
1307 Gets the document type name for this document. See the comment for
1308 @ref m_documentTypeName.
1310 wxString
GetDocumentName() const;
1313 Return true if this document had been already saved.
1317 bool GetDocumentSaved() const;
1320 Gets a pointer to the template that created the document.
1322 virtual wxDocTemplate
* GetDocumentTemplate() const;
1325 Intended to return a suitable window for using as a parent for
1326 document-related dialog boxes. By default, uses the frame associated
1327 with the first view.
1329 virtual wxWindow
* GetDocumentWindow() const;
1332 Gets the filename associated with this document, or "" if none is
1335 wxString
GetFilename() const;
1338 A convenience function to get the first view for a document, because in
1339 many cases a document will only have a single view.
1343 wxView
* GetFirstView() const;
1346 Gets the title for this document. The document title is used for an
1347 associated frame (if any), and is usually constructed by the framework
1350 wxString
GetTitle() const;
1353 Return the document name suitable to be shown to the user. The default
1354 implementation uses the document title, if any, of the name part of the
1355 document filename if it was set or, otherwise, the string @b unnamed.
1357 virtual wxString
GetUserReadableName() const;
1360 Returns a vector of wxView pointers.
1364 wxViewVector
GetViewsVector() const;
1368 Returns the list whose elements are the views on the document.
1373 const wxList
& GetViews() const;
1377 Returns true if this document is a child document corresponding to a
1378 part of the parent document and not a disk file as usual.
1380 This method can be used to check whether file-related operations make
1381 sense for this document as they only apply to top-level documents and
1386 bool IsChildDocument() const;
1389 Returns @true if the document has been modified since the last save,
1390 @false otherwise. You may need to override this if your document view
1391 maintains its own record of being modified.
1395 virtual bool IsModified() const;
1399 Override this function and call it from your own LoadObject() before
1400 streaming your own data. LoadObject() is called by the framework
1401 automatically when the document contents need to be loaded.
1403 @note This version of LoadObject() may not exist depending on how
1404 wxWidgets was configured.
1406 virtual istream
& LoadObject(istream
& stream
);
1407 virtual wxInputStream
& LoadObject(wxInputStream
& stream
);
1411 Call with @true to mark the document as modified since the last save,
1412 @false otherwise. You may need to override this if your document view
1413 maintains its own record of being modified.
1417 virtual void Modify(bool modify
);
1420 Called when a view is added to or deleted from this document. The
1421 default implementation saves and deletes the document if no views exist
1422 (the last one has just been removed).
1424 virtual void OnChangedViewList();
1427 This virtual function is called when the document is being closed.
1429 The default implementation calls DeleteContents() (which may be
1430 overridden to perform additional cleanup) and sets the modified flag to
1431 @false. You can override it to supply additional behaviour when the
1432 document is closed with Close().
1434 Notice that previous wxWidgets versions used to call this function also
1435 from OnNewDocument(), rather counter-intuitively. This is no longer the
1436 case since wxWidgets 2.9.0.
1438 virtual bool OnCloseDocument();
1441 Called just after the document object is created to give it a chance to
1444 The default implementation uses the template associated with the
1445 document to create an initial view.
1447 For compatibility reasons, this method may either delete the document
1448 itself if its initialization fails or not do it in which case it is
1449 deleted by caller. It is recommended to delete the document explicitly
1450 in this function if it can't be initialized.
1453 The associated file path.
1455 Flags passed to CreateDocument().
1457 @true if the initialization was successful or @false if it failed.
1459 virtual bool OnCreate(const wxString
& path
, long flags
);
1462 Override this function if you want a different (or no) command
1463 processor to be created when the document is created. By default, it
1464 returns an instance of wxCommandProcessor.
1466 @see wxCommandProcessor
1468 virtual wxCommandProcessor
* OnCreateCommandProcessor();
1471 The default implementation calls OnSaveModified() and DeleteContents(),
1472 makes a default title for the document, and notifies the views that the
1473 filename (in fact, the title) has changed.
1475 virtual bool OnNewDocument();
1478 Constructs an input file stream for the given filename (which must not
1479 be empty), and calls LoadObject(). If LoadObject() returns @true, the
1480 document is set to unmodified; otherwise, an error message box is
1481 displayed. The document's views are notified that the filename has
1482 changed, to give windows an opportunity to update their titles. All of
1483 the document's views are then updated.
1485 virtual bool OnOpenDocument(const wxString
& filename
);
1488 Constructs an output file stream for the given filename (which must not
1489 be empty), and calls SaveObject(). If SaveObject() returns @true, the
1490 document is set to unmodified; otherwise, an error message box is
1493 virtual bool OnSaveDocument(const wxString
& filename
);
1496 If the document has been modified, prompts the user to ask if the
1497 changes should be saved. If the user replies Yes, the Save() function
1498 is called. If No, the document is marked as unmodified and the function
1499 succeeds. If Cancel, the function fails.
1501 virtual bool OnSaveModified();
1504 Removes the view from the document's list of views, and calls
1505 OnChangedViewList().
1507 virtual bool RemoveView(wxView
* view
);
1510 Saves the document by calling OnSaveDocument() if there is an
1511 associated filename, or SaveAs() if there is no filename.
1513 virtual bool Save();
1516 Prompts the user for a file to save to, and then calls
1519 virtual bool SaveAs();
1522 Discard changes and load last saved version.
1524 Prompts the user first, and then calls DoOpenDocument() to reload the
1527 virtual bool Revert();
1531 Override this function and call it from your own SaveObject() before
1532 streaming your own data. SaveObject() is called by the framework
1533 automatically when the document contents need to be saved.
1535 @note This version of SaveObject() may not exist depending on how
1536 wxWidgets was configured.
1538 virtual ostream
& SaveObject(ostream
& stream
);
1539 virtual wxOutputStream
& SaveObject(wxOutputStream
& stream
);
1543 Sets the command processor to be used for this document. The document
1544 will then be responsible for its deletion. Normally you should not call
1545 this; override OnCreateCommandProcessor() instead.
1547 @see wxCommandProcessor
1549 virtual void SetCommandProcessor(wxCommandProcessor
* processor
);
1552 Sets the document type name for this document. See the comment for
1553 @ref m_documentTypeName.
1555 void SetDocumentName(const wxString
& name
);
1558 Sets the pointer to the template that created the document. Should only
1559 be called by the framework.
1561 virtual void SetDocumentTemplate(wxDocTemplate
* templ
);
1564 Sets if this document has been already saved or not.
1566 Normally there is no need to call this function as the document-view
1567 framework does it itself as the documents are loaded from and saved to
1568 the files. However it may be useful in some particular cases, for
1569 example it may be called with @false argument to prevent the user
1570 from saving the just opened document into the same file if this
1571 shouldn't be done for some reason (e.g. file format version changes and
1572 a new extension should be used for saving).
1574 @see GetDocumentSaved(), AlreadySaved()
1576 void SetDocumentSaved(bool saved
= true);
1579 Sets the filename for this document. Usually called by the framework.
1581 Calls OnChangeFilename() which in turn calls wxView::OnChangeFilename() for
1582 all views if @a notifyViews is @true.
1584 void SetFilename(const wxString
& filename
, bool notifyViews
= false);
1587 If @a notifyViews is @true, wxView::OnChangeFilename() is called for
1592 virtual void OnChangeFilename(bool notifyViews
);
1595 Sets the title for this document. The document title is used for an
1596 associated frame (if any), and is usually constructed by the framework
1599 void SetTitle(const wxString
& title
);
1602 Updates all views. If @a sender is non-@NULL, does not update this
1603 view. @a hint represents optional information to allow a view to
1604 optimize its update.
1606 virtual void UpdateAllViews(wxView
* sender
= NULL
, wxObject
* hint
= NULL
);
1610 This method is called by OnSaveDocument() to really save the document
1611 contents to the specified file.
1613 Base class version creates a file-based stream and calls SaveObject().
1614 Override this if you need to do something else or prefer not to use
1615 SaveObject() at all.
1617 virtual bool DoSaveDocument(const wxString
& file
);
1620 This method is called by OnOpenDocument() to really load the document
1621 contents from the specified file.
1623 Base class version creates a file-based stream and calls LoadObject().
1624 Override this if you need to do something else or prefer not to use
1625 LoadObject() at all.
1627 virtual bool DoOpenDocument(const wxString
& file
);
1630 A pointer to the command processor associated with this document.
1632 wxCommandProcessor
* m_commandProcessor
;
1635 Filename associated with this document ("" if none).
1637 wxString m_documentFile
;
1640 @true if the document has been modified, @false otherwise.
1642 bool m_documentModified
;
1645 A pointer to the template from which this document was created.
1647 wxDocTemplate
* m_documentTemplate
;
1650 Document title. The document title is used for an associated frame (if
1651 any), and is usually constructed by the framework from the filename.
1653 wxString m_documentTitle
;
1656 The document type name given to the wxDocTemplate constructor, copied
1657 to this variable when the document is created. If several document
1658 templates are created that use the same document type, this variable is
1659 used in wxDocManager::CreateView() to collate a list of alternative
1660 view types that can be used on this kind of document. Do not change the
1661 value of this variable.
1663 wxString m_documentTypeName
;
1666 List of wxView instances associated with this document.
1668 wxList m_documentViews
;
1672 // ============================================================================
1673 // Global functions/macros
1674 // ============================================================================
1676 /** @addtogroup group_funcmacro_file */
1680 Copies the given file to @a stream. Useful when converting an old
1681 application to use streams (within the document/view framework, for
1684 @header{wx/docview.h}
1686 bool wxTransferFileToStream(const wxString
& filename
,
1690 Copies the given stream to the file @a filename. Useful when converting an
1691 old application to use streams (within the document/view framework, for
1694 @header{wx/docview.h}
1696 bool wxTransferStreamToFile(istream
& stream
,
1697 const wxString
& filename
);