1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of various doc/view framework classes
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
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 wxCLASSINFO() macro, e.g. wxCLASSINFO(MyDocumentClass). If this is
47 not supplied, you will need to derive a new wxDocTemplate class and
48 override the CreateDocument() member to return a new document
51 A pointer to the run-time view class information as returned by the
52 wxCLASSINFO() macro, e.g. wxCLASSINFO(MyViewClass). If this is not
53 supplied, you will need to derive a new wxDocTemplate class and
54 override the CreateView() member to return a new view instance on
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.
66 In wxPerl @a docClassInfo and @a viewClassInfo can be either
67 @c Wx::ClassInfo objects or strings containing the name of the
68 perl packages which are to be used as @c Wx::Document and
69 @c Wx::View classes (they must have a constructor named new);
72 - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
73 docTypeName, viewTypeName, docClassInfo, viewClassInfo,
74 flags): will construct document and view objects from the
76 - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
77 docTypeName, viewTypeName, docClassName, viewClassName,
78 flags): will construct document and view objects from perl
80 - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
81 docTypeName, viewTypeName):
82 in this case @c Wx::DocTemplate::CreateDocument() and
83 @c Wx::DocTemplate::CreateView() must be overridden
86 wxDocTemplate(wxDocManager
* manager
, const wxString
& descr
,
87 const wxString
& filter
, const wxString
& dir
,
88 const wxString
& ext
, const wxString
& docTypeName
,
89 const wxString
& viewTypeName
, wxClassInfo
* docClassInfo
= 0,
90 wxClassInfo
* viewClassInfo
= 0,
91 long flags
= wxTEMPLATE_VISIBLE
);
96 virtual ~wxDocTemplate();
99 Creates a new instance of the associated document class. If you have
100 not supplied a wxClassInfo parameter to the template constructor, you
101 will need to override this function to return an appropriate document
104 This function calls InitDocument() which in turns calls
105 wxDocument::OnCreate().
107 virtual wxDocument
* CreateDocument(const wxString
& path
, long flags
= 0);
110 Creates a new instance of the associated view class.
112 If you have not supplied a wxClassInfo parameter to the template
113 constructor, you will need to override this function to return an
114 appropriate view instance.
116 If the new view initialization fails, it must call
117 wxDocument::RemoveView() for consistency with the default behaviour of
120 virtual wxView
* CreateView(wxDocument
* doc
, long flags
= 0);
123 This function implements the default (very primitive) format detection
124 which checks if the extension is that of the template.
127 The path to be checked against the template.
129 virtual bool FileMatchesTemplate(const wxString
& path
);
132 Returns the default file extension for the document data, as passed to
133 the document template constructor.
135 wxString
GetDefaultExtension() const;
138 Returns the text description of this template, as passed to the
139 document template constructor.
141 wxString
GetDescription() const;
144 Returns the default directory, as passed to the document template
147 wxString
GetDirectory() const;
150 Returns the run-time class information that allows document
151 instances to be constructed dynamically, as passed to the document
152 template constructor.
154 wxClassInfo
* GetDocClassInfo() const;
157 Returns a pointer to the document manager instance for which this
158 template was created.
160 wxDocManager
* GetDocumentManager() const;
163 Returns the document type name, as passed to the document template
166 virtual wxString
GetDocumentName() const;
169 Returns the file filter, as passed to the document template
172 wxString
GetFileFilter() const;
175 Returns the flags, as passed to the document template constructor.
177 long GetFlags() const;
180 Returns a reference to the wxPageSetupDialogData associated with the
181 printing operations of this document manager.
184 wxPageSetupDialogData
& GetPageSetupDialogData();
185 const wxPageSetupDialogData
& GetPageSetupDialogData() const;
189 Returns the run-time class information that allows view instances
190 to be constructed dynamically, as passed to the document template
193 wxClassInfo
* GetViewClassInfo() const;
196 Returns the view type name, as passed to the document template
199 virtual wxString
GetViewName() const;
202 Initialises the document, calling wxDocument::OnCreate().
204 This is called from CreateDocument().
206 If you override this method, notice that you must @em delete the @a doc
207 if its initialization fails for consistency with the default behaviour.
210 The document to initialize.
212 The associated file path.
214 Flags passed to CreateDocument().
216 @true if the initialization was successful or @false if it failed
217 in which case @a doc should be deleted by this function.
219 virtual bool InitDocument(wxDocument
* doc
,
220 const wxString
& path
,
224 Returns @true if the document template can be shown in user dialogs,
227 bool IsVisible() const;
230 Sets the default file extension.
232 void SetDefaultExtension(const wxString
& ext
);
235 Sets the template description.
237 void SetDescription(const wxString
& descr
);
240 Sets the default directory.
242 void SetDirectory(const wxString
& dir
);
245 Sets the pointer to the document manager instance for which this
246 template was created. Should not be called by the application.
248 void SetDocumentManager(wxDocManager
* manager
);
251 Sets the file filter.
253 void SetFileFilter(const wxString
& filter
);
256 Sets the internal document template flags (see the constructor
257 description for more details).
259 void SetFlags(long flags
);
262 The default extension for files of this type.
264 wxString m_defaultExt
;
267 A short description of this template.
269 wxString m_description
;
272 The default directory for files of this type.
274 wxString m_directory
;
277 Run-time class information that allows document instances to be
278 constructed dynamically.
280 wxClassInfo
* m_docClassInfo
;
283 The named type of the document associated with this template.
285 wxString m_docTypeName
;
288 A pointer to the document manager for which this template was created.
290 wxDocTemplate
* m_documentManager
;
293 The file filter (such as "*.txt") to be used in file selector dialogs.
295 wxString m_fileFilter
;
298 The flags passed to the constructor.
303 Run-time class information that allows view instances to be constructed
306 wxClassInfo
* m_viewClassInfo
;
309 The named type of the view associated with this template.
311 wxString m_viewTypeName
;
319 The wxDocManager class is part of the document/view framework supported by
320 wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate
326 @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate,
329 class wxDocManager
: public wxEvtHandler
333 Constructor. Create a document manager instance dynamically near the
334 start of your application before doing any document or view operations.
336 If @a initialize is @true, the Initialize() function will be called to
337 create a default history list object. If you derive from wxDocManager,
338 you may wish to call the base constructor with @false, and then call
339 Initialize() in your own constructor, to allow your own Initialize() or
340 OnCreateFileHistory functions to be called.
345 Indicates whether Initialize() should be called by this ctor.
347 wxDocManager(long flags
= 0, bool initialize
= true);
352 virtual ~wxDocManager();
355 Sets the current view.
357 virtual void ActivateView(wxView
* doc
, bool activate
= true);
360 Adds the document to the list of documents.
362 void AddDocument(wxDocument
* doc
);
365 Adds a file to the file history list, if we have a pointer to an
366 appropriate file menu.
368 virtual void AddFileToHistory(const wxString
& filename
);
371 Adds the template to the document manager's template list.
373 void AssociateTemplate(wxDocTemplate
* temp
);
376 Search for a particular document template.
380 // creating a document instance of the specified document type:
381 m_doc = (MyDoc*)docManager->FindTemplate(CLASSINFO(MyDoc))->
382 CreateDocument(wxEmptyString, wxDOC_SILENT);
386 Class info of a document class for which a wxDocTemplate had been
390 Pointer to a wxDocTemplate, or @NULL if none found.
394 wxDocTemplate
* FindTemplate(const wxClassInfo
* classinfo
);
397 Closes the specified document.
399 If @a force is @true, the document is closed even if it has unsaved
403 The document to close, must be non-@NULL.
405 If @true, close the document even if wxDocument::Close() returns
408 @true if the document was closed or @false if closing it was
409 cancelled by user (only in @a force = @false case).
411 bool CloseDocument(wxDocument
*doc
, bool force
= false);
414 Closes all currently opened documents.
418 bool CloseDocuments(bool force
= true);
421 Creates a new document.
423 This function can either create a document corresponding to a new
424 file or to an already existing one depending on whether @c wxDOC_NEW is
425 specified in the @a flags.
427 By default, this function asks the user for the type of document to
428 open and the path to its file if it's not specified, i.e. if @a path is
429 empty. Specifying @c wxDOC_SILENT flag suppresses any prompts and means
430 that the @a path must be non-empty and there must be a registered
431 document template handling the extension of this file, otherwise a
432 warning message is logged and the function returns @NULL. Notice that
433 @c wxDOC_SILENT can be combined with @c wxDOC_NEW, however in this case
434 the @a path must still be specified, even if the file with this path
435 typically won't exist.
437 Finally notice that if this document manager was configured to allow
438 only a limited number of simultaneously opened documents using
439 SetMaxDocsOpen(), this function will try to close the oldest existing
440 document if this number was reached before creating a new document.
441 And if closing the old document fails (e.g. because it was vetoed by
442 user), this function fails as well.
445 Path to a file or an empty string. If the path is empty, the user
446 will be asked to select it (thus, this is incompatible with the use
447 of @c wxDOC_SILENT). The file should exist unless @a flags includes
450 By default, none. May include @c wxDOC_NEW to indicate that the new
451 document corresponds to a new file and not an existing one and
452 @c wxDOC_SILENT to suppress any dialogs asking the user about the
454 @return a new document object or @NULL on failure.
456 virtual wxDocument
* CreateDocument(const wxString
& path
, long flags
= 0);
459 Creates an empty new document.
461 This is equivalent to calling CreateDocument() with @c wxDOC_NEW flags
462 and without the file name.
464 wxDocument
*CreateNewDocument();
467 Creates a new view for the given document. If more than one view is
468 allowed for the document (by virtue of multiple templates mentioning
469 the same document type), a choice of view is presented to the user.
471 virtual wxView
* CreateView(wxDocument
* doc
, long flags
= 0);
474 Removes the template from the list of templates.
476 void DisassociateTemplate(wxDocTemplate
* temp
);
479 Appends the files in the history list to all menus managed by the file
482 virtual void FileHistoryAddFilesToMenu();
484 Appends the files in the history list to the given @a menu only.
486 virtual void FileHistoryAddFilesToMenu(wxMenu
* menu
);
489 Loads the file history from a config object.
493 virtual void FileHistoryLoad(const wxConfigBase
& config
);
496 Removes the given menu from the list of menus managed by the file
499 virtual void FileHistoryRemoveMenu(wxMenu
* menu
);
502 Saves the file history into a config object. This must be called
503 explicitly by the application.
507 virtual void FileHistorySave(wxConfigBase
& resourceFile
);
510 Use this menu for appending recently-visited document filenames, for
511 convenient access. Calling this function with a valid menu pointer
512 enables the history list functionality.
514 @note You can add multiple menus using this function, to be managed by
515 the file history object.
517 virtual void FileHistoryUseMenu(wxMenu
* menu
);
520 Given a path, try to find template that matches the extension. This is
521 only an approximate method of finding a template for creating a
524 virtual wxDocTemplate
* FindTemplateForPath(const wxString
& path
);
527 Returns the document associated with the currently active view (if
530 wxDocument
* GetCurrentDocument() const;
533 Returns the currently active view
535 virtual wxView
* GetCurrentView() const;
538 Returns a reference to the list of documents.
540 wxList
& GetDocuments();
543 Returns a pointer to file history.
545 virtual wxFileHistory
* GetFileHistory() const;
548 Returns the number of files currently stored in the file history.
550 virtual size_t GetHistoryFilesCount() const;
553 Returns the directory last selected by the user when opening a file.
556 wxString
GetLastDirectory() const;
559 Returns the number of documents that can be open simultaneously.
561 int GetMaxDocsOpen() const;
564 Returns a reference to the list of associated templates.
566 wxList
& GetTemplates();
569 Create the frame used for print preview.
571 This method can be overridden if you need to change the behaviour or
572 appearance of the preview window. By default, a standard wxPreviewFrame
577 @param preview The associated preview object.
578 @param parent The parent window for the frame.
579 @param title The suggested title for the print preview frame.
580 @return A new print preview frame, must not return @NULL.
582 virtual wxPreviewFrame
* CreatePreviewFrame(wxPrintPreviewBase
* preview
,
584 const wxString
& title
);
587 Initializes data; currently just calls OnCreateFileHistory().
589 Some data cannot always be initialized in the constructor because the
590 programmer must be given the opportunity to override functionality. If
591 OnCreateFileHistory() was called from the constructor, an overridden
592 virtual OnCreateFileHistory() would not be called due to C++'s
593 'interesting' constructor semantics. In fact Initialize() @e is called
594 from the wxDocManager constructor, but this can be vetoed by passing
595 @false to the second argument, allowing the derived class's constructor
596 to call Initialize(), possibly calling a different
597 OnCreateFileHistory() from the default.
599 The bottom line: if you're not deriving from Initialize(), forget it
600 and construct wxDocManager with no arguments.
602 virtual bool Initialize();
605 Return a string containing a suitable default name for a new document.
606 By default this is implemented by appending an integer counter to the
607 string @b unnamed but can be overridden in the derived classes to do
608 something more appropriate.
610 virtual wxString
MakeNewDocumentName();
613 A hook to allow a derived class to create a different type of file
614 history. Called from Initialize().
616 virtual wxFileHistory
* OnCreateFileHistory();
619 Closes and deletes the currently active document.
621 void OnFileClose(wxCommandEvent
& event
);
624 Closes and deletes all the currently opened documents.
626 void OnFileCloseAll(wxCommandEvent
& event
);
629 Creates a document from a list of templates (if more than one
632 void OnFileNew(wxCommandEvent
& event
);
635 Creates a new document and reads in the selected file.
637 void OnFileOpen(wxCommandEvent
& event
);
640 Reverts the current document by calling wxDocument::Revert() for the
643 void OnFileRevert(wxCommandEvent
& event
);
646 Saves the current document by calling wxDocument::Save() for the
649 void OnFileSave(wxCommandEvent
& event
);
652 Calls wxDocument::SaveAs() for the current document.
654 void OnFileSaveAs(wxCommandEvent
& event
);
657 Removes the document from the list of documents.
659 void RemoveDocument(wxDocument
* doc
);
662 Under Windows, pops up a file selector with a list of filters
663 corresponding to document templates. The wxDocTemplate corresponding to
664 the selected file's extension is returned.
666 On other platforms, if there is more than one document template a
667 choice list is popped up, followed by a file selector.
669 This function is used in CreateDocument().
672 In wxPerl @a templates is a reference to a list of templates.
673 If you override this method in your document manager it must
674 return two values, eg:
677 (doctemplate, path) = My::DocManager->SelectDocumentPath(...);
681 virtual wxDocTemplate
* SelectDocumentPath(wxDocTemplate
** templates
,
682 int noTemplates
, wxString
& path
,
683 long flags
, bool save
= false);
686 Returns a document template by asking the user (if there is more than
687 one template). This function is used in CreateDocument().
690 Pointer to an array of templates from which to choose a desired
693 Number of templates being pointed to by the templates pointer.
695 If more than one template is passed into templates, then this
696 parameter indicates whether the list of templates that the user
697 will have to choose from is sorted or not when shown the choice box
698 dialog. Default is @false.
701 In wxPerl @a templates is a reference to a list of templates.
704 virtual wxDocTemplate
* SelectDocumentType(wxDocTemplate
** templates
,
709 Returns a document template by asking the user (if there is more than
710 one template), displaying a list of valid views. This function is used
711 in CreateView(). The dialog normally will not appear because the array
712 of templates only contains those relevant to the document in question,
713 and often there will only be one such.
716 Pointer to an array of templates from which to choose a desired
719 Number of templates being pointed to by the templates pointer.
721 If more than one template is passed into templates, then this
722 parameter indicates whether the list of templates that the user
723 will have to choose from is sorted or not when shown the choice box
724 dialog. Default is @false.
727 In wxPerl @a templates is a reference to a list of templates.
730 virtual wxDocTemplate
* SelectViewType(wxDocTemplate
** templates
,
731 int noTemplates
, bool sort
= false);
734 Sets the directory to be displayed to the user when opening a file.
735 Initially this is empty.
737 void SetLastDirectory(const wxString
& dir
);
740 Sets the maximum number of documents that can be open at a time. By
741 default, this is @c INT_MAX, i.e. the number of documents is unlimited.
742 If you set it to 1, existing documents will be saved and deleted when
743 the user tries to open or create a new one (similar to the behaviour of
744 Windows Write, for example). Allowing multiple documents gives
745 behaviour more akin to MS Word and other Multiple Document Interface
748 void SetMaxDocsOpen(int n
);
753 The currently active view.
755 wxView
* m_currentView
;
758 Stores the integer to be used for the next default document name.
760 int m_defaultDocumentNameCounter
;
763 A list of all documents.
768 A pointer to an instance of wxFileHistory, which manages the history of
769 recently-visited files on the File menu.
771 wxFileHistory
* m_fileHistory
;
774 The directory last selected by the user when opening a file.
776 wxString m_lastDirectory
;
779 Stores the maximum number of documents that can be opened before
780 existing documents are closed.
782 By default, this is @c INT_MAX i.e. practically unlimited.
792 The view class can be used to model the viewing and editing component of
793 an application's file-based data. It is part of the document/view framework
794 supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
795 and wxDocManager classes.
800 @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager
802 class wxView
: public wxEvtHandler
806 Constructor. Define your own default constructor to initialize
807 application-specific data.
812 Destructor. Removes itself from the document's list of views.
817 Call this from your view frame's wxDocChildFrame::OnActivate() member
818 to tell the framework which view is currently active. If your windowing
819 system doesn't call wxDocChildFrame::OnActivate(), you may need to call
820 this function from any place where you know the view must be active,
821 and the framework will need to get the current view.
823 The prepackaged view frame wxDocChildFrame calls Activate() from its
824 wxDocChildFrame::OnActivate() member.
826 This function calls OnActivateView().
828 virtual void Activate(bool activate
);
831 Closes the view by calling OnClose(). If @a deleteWindow is @true, this
832 function should delete the window associated with the view.
834 virtual bool Close(bool deleteWindow
= true);
837 Gets a pointer to the document associated with the view.
839 wxDocument
* GetDocument() const;
842 Returns a pointer to the document manager instance associated with this
845 wxDocManager
* GetDocumentManager() const;
848 Gets the frame associated with the view (if any). Note that this
849 "frame" is not a wxFrame at all in the generic MDI implementation which
850 uses notebook pages instead of frames and this is why this method
851 returns a wxWindow and not a wxFrame.
853 wxWindow
* GetFrame() const;
856 Gets the name associated with the view (passed to the wxDocTemplate
857 constructor). Not currently used by the framework.
859 wxString
GetViewName() const;
862 Called when a view is activated by means of Activate(). The default
863 implementation does nothing.
865 virtual void OnActivateView(bool activate
, wxView
* activeView
,
866 wxView
* deactiveView
);
869 Called when the filename has changed. The default implementation
870 constructs a suitable title and sets the title of the view frame (if any).
872 virtual void OnChangeFilename();
875 Implements closing behaviour. The default implementation calls
876 wxDocument::Close() to close the associated document. Does not delete
877 the view. The application may wish to do some cleaning up operations in
878 this function, @e if a call to wxDocument::Close() succeeded. For
879 example, if your views all share the same window, you need to
880 disassociate the window from the view and perhaps clear the window. If
881 @a deleteWindow is @true, delete the frame associated with the view.
883 virtual bool OnClose(bool deleteWindow
);
886 Override this to clean up the view when the document is being closed.
888 virtual void OnClosingDocument();
891 wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just
892 after the wxDocTemplate creates the wxView, it calls OnCreate(). The
893 wxView can create a wxDocChildFrame (or derived class) in its
894 wxView::OnCreate() member function. This wxDocChildFrame provides user
895 interface elements to view and/or edit the contents of the wxDocument.
897 By default, simply returns @true. If the function returns @false, the
898 view will be deleted.
900 virtual bool OnCreate(wxDocument
* doc
, long flags
);
903 If the printing framework is enabled in the library, this function
904 returns a wxPrintout object for the purposes of printing. It should
905 create a new object every time it is called; the framework will delete
908 By default, this function returns an instance of wxDocPrintout, which
909 prints and previews one page by calling OnDraw().
911 Override to return an instance of a class other than wxDocPrintout.
913 virtual wxPrintout
* OnCreatePrintout();
916 Override this function to render the view on the given device context.
918 virtual void OnDraw(wxDC
* dc
) = 0;
921 Called when the view should be updated.
924 A pointer to the wxView that sent the update request, or @NULL if
925 no single view requested the update (for instance, when the
928 This is unused currently, but may in future contain
929 application-specific information for making updating more
932 virtual void OnUpdate(wxView
* sender
, wxObject
* hint
= 0);
935 Associates the given document with the view. Normally called by the
938 virtual void SetDocument(wxDocument
* doc
);
941 Sets the frame associated with this view. The application should call
942 this if possible, to tell the view about the frame.
944 See GetFrame() for the explanation about the mismatch between the
945 "Frame" in the method name and the type of its parameter.
947 void SetFrame(wxWindow
* frame
);
950 Sets the view type name. Should only be called by the framework.
952 void SetViewName(const wxString
& name
);
955 The document associated with this view. There may be more than one view
956 per document, but there can never be more than one document for one
959 wxDocument
* m_viewDocument
;
962 Frame associated with the view, if any.
964 wxFrame
* m_viewFrame
;
967 The view type name given to the wxDocTemplate constructor, copied to
968 this variable when the view is created. Not currently used by the
971 wxString m_viewTypeName
;
977 @class wxDocChildFrame
979 The wxDocChildFrame class provides a default frame for displaying documents
980 on separate windows. This class can only be used for SDI (not MDI) child
983 The class is part of the document/view framework supported by wxWidgets,
984 and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
990 @see @ref overview_docview, @ref page_samples_docview, wxFrame
992 class wxDocChildFrame
: public wxFrame
998 wxDocChildFrame(wxDocument
* doc
, wxView
* view
, wxFrame
* parent
,
999 wxWindowID id
, const wxString
& title
,
1000 const wxPoint
& pos
= wxDefaultPosition
,
1001 const wxSize
& size
= wxDefaultSize
,
1002 long style
= wxDEFAULT_FRAME_STYLE
,
1003 const wxString
& name
= wxFrameNameStr
);
1008 virtual ~wxDocChildFrame();
1011 Returns the document associated with this frame.
1013 wxDocument
* GetDocument() const;
1016 Returns the view associated with this frame.
1018 wxView
* GetView() const;
1021 Sets the currently active view to be the frame's view. You may need to
1022 override (but still call) this function in order to set the keyboard
1023 focus for your subwindow.
1025 void OnActivate(wxActivateEvent
& event
);
1028 Closes and deletes the current view and document.
1030 void OnCloseWindow(wxCloseEvent
& event
);
1033 Sets the document for this frame.
1035 void SetDocument(wxDocument
* doc
);
1038 Sets the view for this frame.
1040 void SetView(wxView
* view
);
1043 The document associated with the frame.
1045 wxDocument
* m_childDocument
;
1048 The view associated with the frame.
1050 wxView
* m_childView
;
1056 @class wxDocParentFrame
1058 The wxDocParentFrame class provides a default top-level frame for
1059 applications using the document/view framework. This class can only be used
1060 for SDI (not MDI) parent frames.
1062 It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
1068 @see @ref overview_docview, @ref page_samples_docview, wxFrame
1070 class wxDocParentFrame
: public wxFrame
1074 Default constructor.
1080 wxDocParentFrame(wxDocManager
* manager
, wxFrame
* parent
,
1081 wxWindowID id
, const wxString
& title
,
1082 const wxPoint
& pos
= wxDefaultPosition
,
1083 const wxSize
& size
= wxDefaultSize
,
1084 long style
= wxDEFAULT_FRAME_STYLE
,
1085 const wxString
& name
= wxFrameNameStr
);
1090 virtual ~wxDocParentFrame();
1093 Used in two-step construction.
1095 bool Create(wxDocManager
* manager
, wxFrame
* parent
, wxWindowID id
,
1096 const wxString
& title
, const wxPoint
& pos
= wxDefaultPosition
,
1097 const wxSize
& size
= wxDefaultSize
, long style
= 541072960,
1098 const wxString
& name
= wxFrameNameStr
);
1101 Returns the associated document manager object.
1103 wxDocManager
* GetDocumentManager() const;
1106 Deletes all views and documents. If no user input cancelled the
1107 operation, the frame will be destroyed and the application will exit.
1108 Since understanding how document/view clean-up takes place can be
1109 difficult, the implementation of this function is shown below:
1112 void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event)
1114 if (m_docManager->Clear(!event.CanVeto()))
1123 void OnCloseWindow(wxCloseEvent
& event
);
1131 The document class can be used to model an application's file-based data.
1133 It is part of the document/view framework supported by wxWidgets, and
1134 cooperates with the wxView, wxDocTemplate and wxDocManager classes.
1136 A normal document is the one created without parent document and is
1137 associated with a disk file. Since version 2.9.2 wxWidgets also supports a
1138 special kind of documents called <em>child documents</em> which are virtual
1139 in the sense that they do not correspond to a file but rather to a part of
1140 their parent document. Because of this, the child documents can't be
1141 created directly by user but can only be created by the parent document
1142 (usually when it's being created itself). They also can't be independently
1143 saved. A child document has its own view with the corresponding window.
1144 This view can be closed by user but, importantly, is also automatically
1145 closed when its parent document is closed. Thus, child documents may be
1146 convenient for creating additional windows which need to be closed when the
1147 main document is. The docview sample demonstrates this use of child
1148 documents by creating a child document containing the information about the
1149 parameters of the image opened in the main document.
1154 @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager
1156 class wxDocument
: public wxEvtHandler
1160 Constructor. Define your own default constructor to initialize
1161 application-specific data.
1164 Specifying a non-@c NULL parent document here makes this document a
1165 special <em>child document</em>, see their description in the class
1166 documentation. Notice that this parameter exists but is ignored in
1167 wxWidgets versions prior to 2.9.1.
1169 wxDocument(wxDocument
* parent
= NULL
);
1172 Destructor. Removes itself from the document manager.
1174 virtual ~wxDocument();
1177 If the view is not already in the list of views, adds the view and
1178 calls OnChangedViewList().
1180 virtual bool AddView(wxView
* view
);
1183 Returns true if the document hasn't been modified since the last time
1186 Notice that this function returns @false if the document had been never
1187 saved at all, so it may be also used to test whether it makes sense to
1188 save the document: if it returns @true, there is nothing to save but if
1189 @false is returned, it can be saved, even if it might be not modified
1190 (this can be used to create an empty document file by the user).
1192 @see IsModified(), GetDocumentSaved()
1196 bool AlreadySaved() const;
1199 Closes the document, by calling OnSaveModified() and then (if this
1200 returned @true) OnCloseDocument(). This does not normally delete the
1201 document object, use DeleteAllViews() to do this implicitly.
1203 virtual bool Close();
1206 Calls wxView::Close() and deletes each view. Deleting the final view
1207 will implicitly delete the document itself, because the wxView
1208 destructor calls RemoveView(). This in turns calls OnChangedViewList(),
1209 whose default implemention is to save and delete the document if no
1212 virtual bool DeleteAllViews();
1215 Virtual method called from OnCloseDocument().
1217 This method may be overridden to perform any additional cleanup which
1218 might be needed when the document is closed.
1220 The return value of this method is currently ignored.
1222 The default version does nothing and simply returns @true.
1224 virtual bool DeleteContents();
1227 Returns a pointer to the command processor associated with this
1230 @see wxCommandProcessor
1232 virtual wxCommandProcessor
* GetCommandProcessor() const;
1235 Gets a pointer to the associated document manager.
1237 virtual wxDocManager
* GetDocumentManager() const;
1240 Gets the document type name for this document. See the comment for
1241 @ref m_documentTypeName.
1243 wxString
GetDocumentName() const;
1246 Return true if this document had been already saved.
1250 bool GetDocumentSaved() const;
1253 Gets a pointer to the template that created the document.
1255 virtual wxDocTemplate
* GetDocumentTemplate() const;
1258 Intended to return a suitable window for using as a parent for
1259 document-related dialog boxes. By default, uses the frame associated
1260 with the first view.
1262 virtual wxWindow
* GetDocumentWindow() const;
1265 Gets the filename associated with this document, or "" if none is
1268 wxString
GetFilename() const;
1271 A convenience function to get the first view for a document, because in
1272 many cases a document will only have a single view.
1276 wxView
* GetFirstView() const;
1279 Gets the title for this document. The document title is used for an
1280 associated frame (if any), and is usually constructed by the framework
1283 wxString
GetTitle() const;
1286 Return the document name suitable to be shown to the user. The default
1287 implementation uses the document title, if any, of the name part of the
1288 document filename if it was set or, otherwise, the string @b unnamed.
1290 virtual wxString
GetUserReadableName() const;
1294 Returns the list whose elements are the views on the document.
1299 const wxList
& GetViews() const;
1303 Returns true if this document is a child document corresponding to a
1304 part of the parent document and not a disk file as usual.
1306 This method can be used to check whether file-related operations make
1307 sense for this document as they only apply to top-level documents and
1312 bool IsChildDocument() const;
1315 Returns @true if the document has been modified since the last save,
1316 @false otherwise. You may need to override this if your document view
1317 maintains its own record of being modified.
1321 virtual bool IsModified() const;
1325 Override this function and call it from your own LoadObject() before
1326 streaming your own data. LoadObject() is called by the framework
1327 automatically when the document contents need to be loaded.
1329 @note This version of LoadObject() may not exist depending on how
1330 wxWidgets was configured.
1332 virtual istream
& LoadObject(istream
& stream
);
1333 virtual wxInputStream
& LoadObject(wxInputStream
& stream
);
1337 Call with @true to mark the document as modified since the last save,
1338 @false otherwise. You may need to override this if your document view
1339 maintains its own record of being modified.
1343 virtual void Modify(bool modify
);
1346 Called when a view is added to or deleted from this document. The
1347 default implementation saves and deletes the document if no views exist
1348 (the last one has just been removed).
1350 virtual void OnChangedViewList();
1353 This virtual function is called when the document is being closed.
1355 The default implementation calls DeleteContents() (which may be
1356 overridden to perform additional cleanup) and sets the modified flag to
1357 @false. You can override it to supply additional behaviour when the
1358 document is closed with Close().
1360 Notice that previous wxWidgets versions used to call this function also
1361 from OnNewDocument(), rather counter-intuitively. This is no longer the
1362 case since wxWidgets 2.9.0.
1364 virtual bool OnCloseDocument();
1367 Called just after the document object is created to give it a chance to
1370 The default implementation uses the template associated with the
1371 document to create an initial view.
1373 For compatibility reasons, this method may either delete the document
1374 itself if its initialization fails or not do it in which case it is
1375 deleted by caller. It is recommended to delete the document explicitly
1376 in this function if it can't be initialized.
1379 The associated file path.
1381 Flags passed to CreateDocument().
1383 @true if the initialization was successful or @false if it failed.
1385 virtual bool OnCreate(const wxString
& path
, long flags
);
1388 Override this function if you want a different (or no) command
1389 processor to be created when the document is created. By default, it
1390 returns an instance of wxCommandProcessor.
1392 @see wxCommandProcessor
1394 virtual wxCommandProcessor
* OnCreateCommandProcessor();
1397 The default implementation calls OnSaveModified() and DeleteContents(),
1398 makes a default title for the document, and notifies the views that the
1399 filename (in fact, the title) has changed.
1401 virtual bool OnNewDocument();
1404 Constructs an input file stream for the given filename (which must not
1405 be empty), and calls LoadObject(). If LoadObject() returns @true, the
1406 document is set to unmodified; otherwise, an error message box is
1407 displayed. The document's views are notified that the filename has
1408 changed, to give windows an opportunity to update their titles. All of
1409 the document's views are then updated.
1411 virtual bool OnOpenDocument(const wxString
& filename
);
1414 Constructs an output file stream for the given filename (which must not
1415 be empty), and calls SaveObject(). If SaveObject() returns @true, the
1416 document is set to unmodified; otherwise, an error message box is
1419 virtual bool OnSaveDocument(const wxString
& filename
);
1422 If the document has been modified, prompts the user to ask if the
1423 changes should be saved. If the user replies Yes, the Save() function
1424 is called. If No, the document is marked as unmodified and the function
1425 succeeds. If Cancel, the function fails.
1427 virtual bool OnSaveModified();
1430 Removes the view from the document's list of views, and calls
1431 OnChangedViewList().
1433 virtual bool RemoveView(wxView
* view
);
1436 Saves the document by calling OnSaveDocument() if there is an
1437 associated filename, or SaveAs() if there is no filename.
1439 virtual bool Save();
1442 Prompts the user for a file to save to, and then calls
1445 virtual bool SaveAs();
1448 Discard changes and load last saved version.
1450 Prompts the user first, and then calls DoOpenDocument() to reload the
1453 virtual bool Revert();
1457 Override this function and call it from your own SaveObject() before
1458 streaming your own data. SaveObject() is called by the framework
1459 automatically when the document contents need to be saved.
1461 @note This version of SaveObject() may not exist depending on how
1462 wxWidgets was configured.
1464 virtual ostream
& SaveObject(ostream
& stream
);
1465 virtual wxOutputStream
& SaveObject(wxOutputStream
& stream
);
1469 Sets the command processor to be used for this document. The document
1470 will then be responsible for its deletion. Normally you should not call
1471 this; override OnCreateCommandProcessor() instead.
1473 @see wxCommandProcessor
1475 virtual void SetCommandProcessor(wxCommandProcessor
* processor
);
1478 Sets the document type name for this document. See the comment for
1479 @ref m_documentTypeName.
1481 void SetDocumentName(const wxString
& name
);
1484 Sets the pointer to the template that created the document. Should only
1485 be called by the framework.
1487 virtual void SetDocumentTemplate(wxDocTemplate
* templ
);
1490 Sets if this document has been already saved or not.
1492 Normally there is no need to call this function as the document-view
1493 framework does it itself as the documents are loaded from and saved to
1494 the files. However it may be useful in some particular cases, for
1495 example it may be called with @false argument to prevent the user
1496 from saving the just opened document into the same file if this
1497 shouldn't be done for some reason (e.g. file format version changes and
1498 a new extension should be used for saving).
1500 @see GetDocumentSaved(), AlreadySaved()
1502 void SetDocumentSaved(bool saved
= true);
1505 Sets the filename for this document. Usually called by the framework.
1507 Calls OnChangeFilename() which in turn calls wxView::OnChangeFilename() for
1508 all views if @a notifyViews is @true.
1510 void SetFilename(const wxString
& filename
, bool notifyViews
= false);
1513 If @a notifyViews is @true, wxView::OnChangeFilename() is called for
1518 virtual void OnChangeFilename(bool notifyViews
);
1521 Sets the title for this document. The document title is used for an
1522 associated frame (if any), and is usually constructed by the framework
1525 void SetTitle(const wxString
& title
);
1528 Updates all views. If @a sender is non-@NULL, does not update this
1529 view. @a hint represents optional information to allow a view to
1530 optimize its update.
1532 virtual void UpdateAllViews(wxView
* sender
= NULL
, wxObject
* hint
= NULL
);
1536 This method is called by OnSaveDocument() to really save the document
1537 contents to the specified file.
1539 Base class version creates a file-based stream and calls SaveObject().
1540 Override this if you need to do something else or prefer not to use
1541 SaveObject() at all.
1543 virtual bool DoSaveDocument(const wxString
& file
);
1546 This method is called by OnOpenDocument() to really load the document
1547 contents from the specified file.
1549 Base class version creates a file-based stream and calls LoadObject().
1550 Override this if you need to do something else or prefer not to use
1551 LoadObject() at all.
1553 virtual bool DoOpenDocument(const wxString
& file
);
1556 A pointer to the command processor associated with this document.
1558 wxCommandProcessor
* m_commandProcessor
;
1561 Filename associated with this document ("" if none).
1563 wxString m_documentFile
;
1566 @true if the document has been modified, @false otherwise.
1568 bool m_documentModified
;
1571 A pointer to the template from which this document was created.
1573 wxDocTemplate
* m_documentTemplate
;
1576 Document title. The document title is used for an associated frame (if
1577 any), and is usually constructed by the framework from the filename.
1579 wxString m_documentTitle
;
1582 The document type name given to the wxDocTemplate constructor, copied
1583 to this variable when the document is created. If several document
1584 templates are created that use the same document type, this variable is
1585 used in wxDocManager::CreateView() to collate a list of alternative
1586 view types that can be used on this kind of document. Do not change the
1587 value of this variable.
1589 wxString m_documentTypeName
;
1592 List of wxView instances associated with this document.
1594 wxList m_documentViews
;
1598 // ============================================================================
1599 // Global functions/macros
1600 // ============================================================================
1602 /** @addtogroup group_funcmacro_file */
1606 Copies the given file to @a stream. Useful when converting an old
1607 application to use streams (within the document/view framework, for
1610 @header{wx/docview.h}
1612 bool wxTransferFileToStream(const wxString
& filename
,
1616 Copies the given stream to the file @a filename. Useful when converting an
1617 old application to use streams (within the document/view framework, for
1620 @header{wx/docview.h}
1622 bool wxTransferStreamToFile(istream
& stream
,
1623 const wxString
& filename
);