Version: 2.9.4
Public Member Functions | Protected Member Functions | Protected Attributes
wxDocument Class Reference

#include </home/zeitlin/src/wx/github/interface/wx/docview.h>

Inheritance diagram for wxDocument:

Detailed Description

The document class can be used to model an application's file-based data.

It is part of the document/view framework supported by wxWidgets, and cooperates with the wxView, wxDocTemplate and wxDocManager classes.

A normal document is the one created without parent document and is associated with a disk file. Since version 2.9.2 wxWidgets also supports a special kind of documents called child documents which are virtual in the sense that they do not correspond to a file but rather to a part of their parent document. Because of this, the child documents can't be created directly by user but can only be created by the parent document (usually when it's being created itself). They also can't be independently saved. A child document has its own view with the corresponding window. This view can be closed by user but, importantly, is also automatically closed when its parent document is closed. Thus, child documents may be convenient for creating additional windows which need to be closed when the main document is. The docview sample demonstrates this use of child documents by creating a child document containing the information about the parameters of the image opened in the main document.

Library:  wxCore
Category:  Document/View Framework
参照:
Document/View Framework, wxView, wxDocTemplate, wxDocManager

Public Member Functions

 wxDocument (wxDocument *parent=NULL)
 Constructor.
virtual ~wxDocument ()
 Destructor.
virtual bool AddView (wxView *view)
 If the view is not already in the list of views, adds the view and calls OnChangedViewList().
bool AlreadySaved () const
 Returns true if the document hasn't been modified since the last time it had been saved.
virtual bool Close ()
 Closes the document, by calling OnSaveModified() and then (if this returned true) OnCloseDocument().
virtual bool DeleteAllViews ()
 Calls wxView::Close() and deletes each view.
virtual bool DeleteContents ()
 Virtual method called from OnCloseDocument().
virtual wxCommandProcessorGetCommandProcessor () const
 Returns a pointer to the command processor associated with this document.
virtual wxDocManagerGetDocumentManager () const
 Gets a pointer to the associated document manager.
wxString GetDocumentName () const
 Gets the document type name for this document.
bool GetDocumentSaved () const
 Return true if this document had been already saved.
virtual wxDocTemplateGetDocumentTemplate () const
 Gets a pointer to the template that created the document.
virtual wxWindowGetDocumentWindow () const
 Intended to return a suitable window for using as a parent for document-related dialog boxes.
wxString GetFilename () const
 Gets the filename associated with this document, or "" if none is associated.
wxViewGetFirstView () const
 A convenience function to get the first view for a document, because in many cases a document will only have a single view.
wxString GetTitle () const
 Gets the title for this document.
virtual wxString GetUserReadableName () const
 Return the document name suitable to be shown to the user.
bool IsChildDocument () const
 Returns true if this document is a child document corresponding to a part of the parent document and not a disk file as usual.
virtual bool IsModified () const
 Returns true if the document has been modified since the last save, false otherwise.
virtual void Modify (bool modify)
 Call with true to mark the document as modified since the last save, false otherwise.
virtual void OnChangedViewList ()
 Called when a view is added to or deleted from this document.
virtual bool OnCloseDocument ()
 This virtual function is called when the document is being closed.
virtual bool OnCreate (const wxString &path, long flags)
 Called just after the document object is created to give it a chance to initialize itself.
virtual wxCommandProcessorOnCreateCommandProcessor ()
 Override this function if you want a different (or no) command processor to be created when the document is created.
virtual bool OnNewDocument ()
 The default implementation calls OnSaveModified() and DeleteContents(), makes a default title for the document, and notifies the views that the filename (in fact, the title) has changed.
virtual bool OnOpenDocument (const wxString &filename)
 Constructs an input file stream for the given filename (which must not be empty), and calls LoadObject().
virtual bool OnSaveDocument (const wxString &filename)
 Constructs an output file stream for the given filename (which must not be empty), and calls SaveObject().
virtual bool OnSaveModified ()
 If the document has been modified, prompts the user to ask if the changes should be saved.
virtual bool RemoveView (wxView *view)
 Removes the view from the document's list of views, and calls OnChangedViewList().
virtual bool Save ()
 Saves the document by calling OnSaveDocument() if there is an associated filename, or SaveAs() if there is no filename.
virtual bool SaveAs ()
 Prompts the user for a file to save to, and then calls OnSaveDocument().
virtual bool Revert ()
 Discard changes and load last saved version.
virtual void SetCommandProcessor (wxCommandProcessor *processor)
 Sets the command processor to be used for this document.
void SetDocumentName (const wxString &name)
 Sets the document type name for this document.
virtual void SetDocumentTemplate (wxDocTemplate *templ)
 Sets the pointer to the template that created the document.
void SetDocumentSaved (bool saved=true)
 Sets if this document has been already saved or not.
void SetFilename (const wxString &filename, bool notifyViews=false)
 Sets the filename for this document.
virtual void OnChangeFilename (bool notifyViews)
 If notifyViews is true, wxView::OnChangeFilename() is called for all views.
void SetTitle (const wxString &title)
 Sets the title for this document.
virtual void UpdateAllViews (wxView *sender=NULL, wxObject *hint=NULL)
 Updates all views.
wxList & GetViews ()
 Returns the list whose elements are the views on the document.
const wxList & GetViews () const
 Returns the list whose elements are the views on the document.
virtual istream & LoadObject (istream &stream)
 Override this function and call it from your own LoadObject() before streaming your own data.
virtual wxInputStreamLoadObject (wxInputStream &stream)
 Override this function and call it from your own LoadObject() before streaming your own data.
virtual ostream & SaveObject (ostream &stream)
 Override this function and call it from your own SaveObject() before streaming your own data.
virtual wxOutputStreamSaveObject (wxOutputStream &stream)
 Override this function and call it from your own SaveObject() before streaming your own data.

Protected Member Functions

virtual bool DoSaveDocument (const wxString &file)
 This method is called by OnSaveDocument() to really save the document contents to the specified file.
virtual bool DoOpenDocument (const wxString &file)
 This method is called by OnOpenDocument() to really load the document contents from the specified file.

Protected Attributes

wxCommandProcessorm_commandProcessor
 A pointer to the command processor associated with this document.
wxString m_documentFile
 Filename associated with this document ("" if none).
bool m_documentModified
 true if the document has been modified, false otherwise.
wxDocTemplatem_documentTemplate
 A pointer to the template from which this document was created.
wxString m_documentTitle
 Document title.
wxString m_documentTypeName
 The document type name given to the wxDocTemplate constructor, copied to this variable when the document is created.
wxList m_documentViews
 List of wxView instances associated with this document.

List of all members.


Constructor & Destructor Documentation

wxDocument::wxDocument ( wxDocument parent = NULL)

Constructor.

Define your own default constructor to initialize application-specific data.

Parameters:
parentSpecifying a non-NULL parent document here makes this document a special child document, see their description in the class documentation. Notice that this parameter exists but is ignored in wxWidgets versions prior to 2.9.1.
virtual wxDocument::~wxDocument ( ) [virtual]

Destructor.

Removes itself from the document manager.


Member Function Documentation

virtual bool wxDocument::AddView ( wxView view) [virtual]

If the view is not already in the list of views, adds the view and calls OnChangedViewList().

bool wxDocument::AlreadySaved ( ) const

Returns true if the document hasn't been modified since the last time it had been saved.

Notice that this function returns false if the document had been never saved at all, so it may be also used to test whether it makes sense to save the document: if it returns true, there is nothing to save but if false is returned, it can be saved, even if it might be not modified (this can be used to create an empty document file by the user).

参照:
IsModified(), GetDocumentSaved()
Since:
2.9.0
virtual bool wxDocument::Close ( ) [virtual]

Closes the document, by calling OnSaveModified() and then (if this returned true) OnCloseDocument().

This does not normally delete the document object, use DeleteAllViews() to do this implicitly.

virtual bool wxDocument::DeleteAllViews ( ) [virtual]

Calls wxView::Close() and deletes each view.

Deleting the final view will implicitly delete the document itself, because the wxView destructor calls RemoveView(). This in turns calls OnChangedViewList(), whose default implemention is to save and delete the document if no views exist.

virtual bool wxDocument::DeleteContents ( ) [virtual]

Virtual method called from OnCloseDocument().

This method may be overridden to perform any additional cleanup which might be needed when the document is closed.

The return value of this method is currently ignored.

The default version does nothing and simply returns true.

virtual bool wxDocument::DoOpenDocument ( const wxString file) [protected, virtual]

This method is called by OnOpenDocument() to really load the document contents from the specified file.

Base class version creates a file-based stream and calls LoadObject(). Override this if you need to do something else or prefer not to use LoadObject() at all.

virtual bool wxDocument::DoSaveDocument ( const wxString file) [protected, virtual]

This method is called by OnSaveDocument() to really save the document contents to the specified file.

Base class version creates a file-based stream and calls SaveObject(). Override this if you need to do something else or prefer not to use SaveObject() at all.

virtual wxCommandProcessor* wxDocument::GetCommandProcessor ( ) const [virtual]

Returns a pointer to the command processor associated with this document.

参照:
wxCommandProcessor
virtual wxDocManager* wxDocument::GetDocumentManager ( ) const [virtual]

Gets a pointer to the associated document manager.

wxString wxDocument::GetDocumentName ( ) const

Gets the document type name for this document.

See the comment for m_documentTypeName.

bool wxDocument::GetDocumentSaved ( ) const

Return true if this document had been already saved.

参照:
IsModified()
virtual wxDocTemplate* wxDocument::GetDocumentTemplate ( ) const [virtual]

Gets a pointer to the template that created the document.

virtual wxWindow* wxDocument::GetDocumentWindow ( ) const [virtual]

Intended to return a suitable window for using as a parent for document-related dialog boxes.

By default, uses the frame associated with the first view.

wxString wxDocument::GetFilename ( ) const

Gets the filename associated with this document, or "" if none is associated.

wxView* wxDocument::GetFirstView ( ) const

A convenience function to get the first view for a document, because in many cases a document will only have a single view.

参照:
GetViews()
wxString wxDocument::GetTitle ( ) const

Gets the title for this document.

The document title is used for an associated frame (if any), and is usually constructed by the framework from the filename.

virtual wxString wxDocument::GetUserReadableName ( ) const [virtual]

Return the document name suitable to be shown to the user.

The default implementation uses the document title, if any, of the name part of the document filename if it was set or, otherwise, the string unnamed.

wxList& wxDocument::GetViews ( )

Returns the list whose elements are the views on the document.

参照:
GetFirstView()
const wxList& wxDocument::GetViews ( ) const

Returns the list whose elements are the views on the document.

参照:
GetFirstView()
bool wxDocument::IsChildDocument ( ) const

Returns true if this document is a child document corresponding to a part of the parent document and not a disk file as usual.

This method can be used to check whether file-related operations make sense for this document as they only apply to top-level documents and not child ones.

Since:
2.9.2
virtual bool wxDocument::IsModified ( ) const [virtual]

Returns true if the document has been modified since the last save, false otherwise.

You may need to override this if your document view maintains its own record of being modified.

参照:
Modify()
virtual istream& wxDocument::LoadObject ( istream &  stream) [virtual]

Override this function and call it from your own LoadObject() before streaming your own data.

LoadObject() is called by the framework automatically when the document contents need to be loaded.

注:
This version of LoadObject() may not exist depending on how wxWidgets was configured.
virtual wxInputStream& wxDocument::LoadObject ( wxInputStream stream) [virtual]

Override this function and call it from your own LoadObject() before streaming your own data.

LoadObject() is called by the framework automatically when the document contents need to be loaded.

注:
This version of LoadObject() may not exist depending on how wxWidgets was configured.
virtual void wxDocument::Modify ( bool  modify) [virtual]

Call with true to mark the document as modified since the last save, false otherwise.

You may need to override this if your document view maintains its own record of being modified.

参照:
IsModified()
virtual void wxDocument::OnChangedViewList ( ) [virtual]

Called when a view is added to or deleted from this document.

The default implementation saves and deletes the document if no views exist (the last one has just been removed).

virtual void wxDocument::OnChangeFilename ( bool  notifyViews) [virtual]

If notifyViews is true, wxView::OnChangeFilename() is called for all views.

Since:
2.9.0
virtual bool wxDocument::OnCloseDocument ( ) [virtual]

This virtual function is called when the document is being closed.

The default implementation calls DeleteContents() (which may be overridden to perform additional cleanup) and sets the modified flag to false. You can override it to supply additional behaviour when the document is closed with Close().

Notice that previous wxWidgets versions used to call this function also from OnNewDocument(), rather counter-intuitively. This is no longer the case since wxWidgets 2.9.0.

virtual bool wxDocument::OnCreate ( const wxString path,
long  flags 
) [virtual]

Called just after the document object is created to give it a chance to initialize itself.

The default implementation uses the template associated with the document to create an initial view.

For compatibility reasons, this method may either delete the document itself if its initialization fails or not do it in which case it is deleted by caller. It is recommended to delete the document explicitly in this function if it can't be initialized.

Parameters:
pathThe associated file path.
flagsFlags passed to CreateDocument().
Returns:
true if the initialization was successful or false if it failed.
virtual wxCommandProcessor* wxDocument::OnCreateCommandProcessor ( ) [virtual]

Override this function if you want a different (or no) command processor to be created when the document is created.

By default, it returns an instance of wxCommandProcessor.

参照:
wxCommandProcessor
virtual bool wxDocument::OnNewDocument ( ) [virtual]

The default implementation calls OnSaveModified() and DeleteContents(), makes a default title for the document, and notifies the views that the filename (in fact, the title) has changed.

virtual bool wxDocument::OnOpenDocument ( const wxString filename) [virtual]

Constructs an input file stream for the given filename (which must not be empty), and calls LoadObject().

If LoadObject() returns true, the document is set to unmodified; otherwise, an error message box is displayed. The document's views are notified that the filename has changed, to give windows an opportunity to update their titles. All of the document's views are then updated.

virtual bool wxDocument::OnSaveDocument ( const wxString filename) [virtual]

Constructs an output file stream for the given filename (which must not be empty), and calls SaveObject().

If SaveObject() returns true, the document is set to unmodified; otherwise, an error message box is displayed.

virtual bool wxDocument::OnSaveModified ( ) [virtual]

If the document has been modified, prompts the user to ask if the changes should be saved.

If the user replies Yes, the Save() function is called. If No, the document is marked as unmodified and the function succeeds. If Cancel, the function fails.

virtual bool wxDocument::RemoveView ( wxView view) [virtual]

Removes the view from the document's list of views, and calls OnChangedViewList().

virtual bool wxDocument::Revert ( ) [virtual]

Discard changes and load last saved version.

Prompts the user first, and then calls DoOpenDocument() to reload the current file.

virtual bool wxDocument::Save ( ) [virtual]

Saves the document by calling OnSaveDocument() if there is an associated filename, or SaveAs() if there is no filename.

virtual bool wxDocument::SaveAs ( ) [virtual]

Prompts the user for a file to save to, and then calls OnSaveDocument().

virtual wxOutputStream& wxDocument::SaveObject ( wxOutputStream stream) [virtual]

Override this function and call it from your own SaveObject() before streaming your own data.

SaveObject() is called by the framework automatically when the document contents need to be saved.

注:
This version of SaveObject() may not exist depending on how wxWidgets was configured.
virtual ostream& wxDocument::SaveObject ( ostream &  stream) [virtual]

Override this function and call it from your own SaveObject() before streaming your own data.

SaveObject() is called by the framework automatically when the document contents need to be saved.

注:
This version of SaveObject() may not exist depending on how wxWidgets was configured.
virtual void wxDocument::SetCommandProcessor ( wxCommandProcessor processor) [virtual]

Sets the command processor to be used for this document.

The document will then be responsible for its deletion. Normally you should not call this; override OnCreateCommandProcessor() instead.

参照:
wxCommandProcessor
void wxDocument::SetDocumentName ( const wxString name)

Sets the document type name for this document.

See the comment for m_documentTypeName.

void wxDocument::SetDocumentSaved ( bool  saved = true)

Sets if this document has been already saved or not.

Normally there is no need to call this function as the document-view framework does it itself as the documents are loaded from and saved to the files. However it may be useful in some particular cases, for example it may be called with false argument to prevent the user from saving the just opened document into the same file if this shouldn't be done for some reason (e.g. file format version changes and a new extension should be used for saving).

参照:
GetDocumentSaved(), AlreadySaved()
virtual void wxDocument::SetDocumentTemplate ( wxDocTemplate templ) [virtual]

Sets the pointer to the template that created the document.

Should only be called by the framework.

void wxDocument::SetFilename ( const wxString filename,
bool  notifyViews = false 
)

Sets the filename for this document.

Usually called by the framework.

Calls OnChangeFilename() which in turn calls wxView::OnChangeFilename() for all views if notifyViews is true.

void wxDocument::SetTitle ( const wxString title)

Sets the title for this document.

The document title is used for an associated frame (if any), and is usually constructed by the framework from the filename.

virtual void wxDocument::UpdateAllViews ( wxView sender = NULL,
wxObject hint = NULL 
) [virtual]

Updates all views.

If sender is non-NULL, does not update this view. hint represents optional information to allow a view to optimize its update.


Member Data Documentation

A pointer to the command processor associated with this document.

Filename associated with this document ("" if none).

true if the document has been modified, false otherwise.

A pointer to the template from which this document was created.

Document title.

The document title is used for an associated frame (if any), and is usually constructed by the framework from the filename.

The document type name given to the wxDocTemplate constructor, copied to this variable when the document is created.

If several document templates are created that use the same document type, this variable is used in wxDocManager::CreateView() to collate a list of alternative view types that can be used on this kind of document. Do not change the value of this variable.

wxList wxDocument::m_documentViews [protected]

List of wxView instances associated with this document.

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines