| Version: 3.3.1

Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
wxDocument Class Reference
Class List by Category » Document/View Framework

`#include <wx/docview.h>`

Inheritance diagram for wxDocument:
[legend]

## 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

See also
  Document/View Framework, wxView, wxDocTemplate, wxDocManager

## Public Member Functions
| wxDocument (wxDocument *parent=nullptr)
| Constructor. More...
virtual | ~wxDocument ()
| Destructor. More...
virtual bool | AddView (wxView *view)
| If the view is not already in the list of views, adds the view and calls OnChangedViewList(). More...
bool | AlreadySaved () const
| Returns true if the document hasn't been modified since the last time it had been saved. More...
void | Activate () const
| Activate the first view of the document if any. More...
virtual bool | Close ()
| Closes the document, by calling OnSaveModified() and then (if this returned true) OnCloseDocument(). More...
virtual bool | DeleteAllViews ()
| Calls wxView::Close() and deletes each view. More...
virtual bool | DeleteContents ()
| Virtual method called from OnCloseDocument(). More...
virtual wxCommandProcessor * | GetCommandProcessor () const
| Returns a pointer to the command processor associated with this document. More...
virtual wxDocManager * | GetDocumentManager () const
| Gets a pointer to the associated document manager. More...
wxString | GetDocumentName () const
| Gets the document type name for this document. More...
bool | GetDocumentSaved () const
| Return true if this document had been already saved. More...
virtual wxDocTemplate * | GetDocumentTemplate () const
| Gets a pointer to the template that created the document. More...
virtual wxWindow * | GetDocumentWindow () const
| Intended to return a suitable window for using as a parent for document-related dialog boxes. More...
wxString | GetFilename () const
| Gets the filename associated with this document, or "" if none is associated. More...
wxView * | 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. More...
wxString | GetTitle () const
| Gets the title for this document. More...
virtual wxString | GetUserReadableName () const
| Return the document name suitable to be shown to the user. More...
wxViewVector | GetViewsVector () const
| Returns a vector of wxView pointers. More...
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. More...
virtual bool | IsModified () const
| Returns true if the document has been modified since the last save, false otherwise. More...
virtual std::istream & | LoadObject (std::istream &stream)
| Override this function to load the object data from the provided stream. More...
virtual wxInputStream & | LoadObject (wxInputStream &stream)
| Override this function to load the object data from the provided stream. More...
virtual void | Modify (bool modify)
| Call with true to mark the document as modified since the last save, false otherwise. More...
virtual void | OnChangedViewList ()
| Called when a view is added to or deleted from this document. More...
virtual bool | OnCloseDocument ()
| This virtual function is called when the document is being closed. More...
virtual bool | OnCreate (const wxString &path, long flags)
| Called just after the document object is created to give it a chance to initialize itself. More...
virtual wxCommandProcessor * | OnCreateCommandProcessor ()
| Override this function if you want a different (or no) command processor to be created when the document is created. More...
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. More...
virtual bool | OnOpenDocument (const wxString &filename)
| Constructs an input file stream for the given filename (which must not be empty), and calls LoadObject(). More...
virtual bool | OnSaveDocument (const wxString &filename)
| Constructs an output file stream for the given filename (which must not be empty), and calls SaveObject(). More...
virtual bool | OnSaveModified ()
| If the document has been modified, prompts the user to ask if the changes should be saved. More...
virtual void | OnSaveBeforeForceClose ()
| This function is called when a document is forced to close. More...
virtual bool | RemoveView (wxView *view)
| Removes the view from the document's list of views. More...
virtual bool | Save ()
| Saves the document by calling OnSaveDocument() if there is an associated filename, or SaveAs() if there is no filename. More...
virtual bool | SaveAs ()
| Prompts the user for a file to save to, and then calls OnSaveDocument(). More...
virtual bool | Revert ()
| Discard changes and load last saved version. More...
virtual std::ostream & | SaveObject (std::ostream &stream)
| Override this function to save the object data into the provided stream. More...
virtual wxOutputStream & | SaveObject (wxOutputStream &stream)
| Override this function to load the object data from the provided stream. More...
virtual void | SetCommandProcessor (wxCommandProcessor *processor)
| Sets the command processor to be used for this document. More...
void | SetDocumentName (const wxString &name)
| Sets the document type name for this document. More...
virtual void | SetDocumentTemplate (wxDocTemplate *templ)
| Sets the pointer to the template that created the document. More...
void | SetDocumentSaved (bool saved=true)
| Sets if this document has been already saved or not. More...
void | SetFilename (const wxString &filename, bool notifyViews=false)
| Sets the filename for this document. More...
virtual void | OnChangeFilename (bool notifyViews)
| If notifyViews is true, wxView::OnChangeFilename() is called for all views. More...
void | SetTitle (const wxString &title)
| Sets the title for this document. More...
virtual void | UpdateAllViews (wxView *sender=nullptr, wxObject *hint=nullptr)
| Updates all views. More...
wxList & | GetViews ()
| Returns the list whose elements are the views on the document. More...
const wxList & | GetViews () const
| Returns the list whose elements are the views on the document. More...
Public Member Functions inherited from wxEvtHandler
| wxEvtHandler ()
| Constructor. More...
virtual | ~wxEvtHandler ()
| Destructor. More...
virtual void | QueueEvent (wxEvent *event)
| Queue event for a later processing. More...
virtual void | AddPendingEvent (const wxEvent &event)
| Post an event to be processed later. More...
template<typename T , typename T1 , ... >
void | CallAfter (void(T::*method)(T1,...), T1 x1,...)
| Asynchronously call the given method. More...
template<typename T >
void | CallAfter (const T &functor)
| Asynchronously call the given functor. More...
virtual bool | ProcessEvent (wxEvent &event)
| Processes an event, searching event tables and calling zero or more suitable event handler function(s). More...
bool | ProcessEventLocally (wxEvent &event)
| Try to process the event in this handler and all those chained to it. More...
bool | SafelyProcessEvent (wxEvent &event)
| Processes an event by calling ProcessEvent() and handles any exceptions that occur in the process. More...
void | ProcessPendingEvents ()
| Processes the pending events previously queued using QueueEvent() or AddPendingEvent(); you must call this function only if you are sure there are pending events for this handler, otherwise a `wxCHECK` will fail. More...
void | DeletePendingEvents ()
| Deletes all events queued on this event handler using QueueEvent() or AddPendingEvent(). More...
void | Connect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| Connects the given function dynamically with the event handler, id and event type. More...
void | Connect (int id, wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
void | Connect (wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
bool | Disconnect (wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| Disconnects the given function dynamically from the event handler, using the specified parameters as search criteria and returning true if a matching function has been found and removed. More...
bool | Disconnect (int id=wxID_ANY, wxEventType eventType=wxEVT_NULL, wxObjectEventFunction function=nullptr, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
bool | Disconnect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function=nullptr, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
template<typename EventTag , typename Functor >
void | Bind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
| Binds the given function, functor or method dynamically with the event. More...
template<typename EventTag , typename Class , typename EventArg , typename EventHandler >
void | Bind (const EventTag &eventType, void(Class::*method)(EventArg &), EventHandler *handler, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
| See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info. More...
template<typename EventTag , typename Functor >
bool | Unbind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
| Unbinds the given function, functor or method dynamically from the event handler, using the specified parameters as search criteria and returning true if a matching function has been found and removed. More...
template<typename EventTag , typename Class , typename EventArg , typename EventHandler >
bool | Unbind (const EventTag &eventType, void(Class::*method)(EventArg &), EventHandler *handler, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
| See the Unbind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info. More...
void * | GetClientData () const
| Returns user-supplied client data. More...
wxClientData * | GetClientObject () const
| Returns a pointer to the user-supplied client data object. More...
void | SetClientData (void *data)
| Sets user-supplied client data. More...
void | SetClientObject (wxClientData *data)
| Set the client data object. More...
bool | GetEvtHandlerEnabled () const
| Returns true if the event handler is enabled, false otherwise. More...
wxEvtHandler * | GetNextHandler () const
| Returns the pointer to the next handler in the chain. More...
wxEvtHandler * | GetPreviousHandler () const
| Returns the pointer to the previous handler in the chain. More...
void | SetEvtHandlerEnabled (bool enabled)
| Enables or disables the event handler. More...
virtual void | SetNextHandler (wxEvtHandler *handler)
| Sets the pointer to the next handler. More...
virtual void | SetPreviousHandler (wxEvtHandler *handler)
| Sets the pointer to the previous handler. More...
void | Unlink ()
| Unlinks this event handler from the chain it's part of (if any); then links the "previous" event handler to the "next" one (so that the chain won't be interrupted). More...
bool | IsUnlinked () const
| Returns true if the next and the previous handler pointers of this event handler instance are nullptr. More...
Public Member Functions inherited from wxObject
| wxObject ()
| Default ctor; initializes to nullptr the internal reference data. More...
| wxObject (const wxObject &other)
| Copy ctor. More...
virtual | ~wxObject ()
| Destructor. More...
virtual wxClassInfo * | GetClassInfo () const
| This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...
wxObjectRefData * | GetRefData () const
| Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...
bool | IsKindOf (const wxClassInfo *info) const
| Determines whether this class is a subclass of (or the same class as) the given class. More...
bool | IsSameAs (const wxObject &obj) const
| Returns true if this object has the same data pointer as obj. More...
void | Ref (const wxObject &clone)
| Makes this object refer to the data in clone. More...
void | SetRefData (wxObjectRefData *data)
| Sets the wxObject::m_refData pointer. More...
void | UnRef ()
| Decrements the reference count in the associated data, and if it is zero, deletes the data. More...
void | UnShare ()
| This is the same of AllocExclusive() but this method is public. More...
void | operator delete (void *buf)
| The delete operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...
void * | operator new (size_t size, const wxString &filename=nullptr, int lineNum=0)
| The new operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

## 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. More...
virtual bool | DoOpenDocument (const wxString &file)
| This method is called by OnOpenDocument() to really load the document contents from the specified file. More...
Protected Member Functions inherited from wxEvtHandler
virtual bool | TryBefore (wxEvent &event)
| Method called by ProcessEvent() before examining this object event tables. More...
virtual bool | TryAfter (wxEvent &event)
| Method called by ProcessEvent() as last resort. More...
Protected Member Functions inherited from wxObject
void | AllocExclusive ()
| Ensure that this object's data is not shared with any other object. More...
virtual wxObjectRefData * | CreateRefData () const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...
virtual wxObjectRefData * | CloneRefData (const wxObjectRefData *data) const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...

## Protected Attributes
wxCommandProcessor * | m_commandProcessor
| A pointer to the command processor associated with this document. More...
wxString | m_documentFile
| Filename associated with this document ("" if none). More...
bool | m_documentModified
| true if the document has been modified, false otherwise. More...
wxDocTemplate * | m_documentTemplate
| A pointer to the template from which this document was created. More...
wxString | m_documentTitle
| Document title. More...
wxString | m_documentTypeName
| The document type name given to the wxDocTemplate constructor, copied to this variable when the document is created. More...
wxList | m_documentViews
| List of wxView instances associated with this document. More...
Protected Attributes inherited from wxObject
wxObjectRefData * | m_refData
| Pointer to an object which is the object's reference-counted data. More...

## Additional Inherited Members
Static Public Member Functions inherited from wxEvtHandler
static void | AddFilter (wxEventFilter *filter)
| Add an event filter whose FilterEvent() method will be called for each and every event processed by wxWidgets. More...
static void | RemoveFilter (wxEventFilter *filter)
| Remove a filter previously installed with AddFilter(). More...

## Constructor & Destructor Documentation

## ◆ wxDocument()

wxDocument::wxDocument | ( | wxDocument * | parent = `nullptr` | ) |

Constructor.

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

Parameters

  parent | Specifying 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.

## ◆ ~wxDocument()

virtual wxDocument::~wxDocument | ( |  | ) |
| virtual

Destructor.

Removes itself from the document manager.

## Member Function Documentation

## ◆ Activate()

void wxDocument::Activate | ( |  | ) | const

Activate the first view of the document if any.

This function simply calls the Raise() method of the frame of the first view. You may need to override the Raise() method to get the desired effect if you are not using a standard wxFrame for your view. For instance, if your document is inside its own notebook tab you could implement Raise() like this:

void MyNotebookPage::Raise()
{
wxNotebook* notebook = wxStaticCast(GetParent(), wxNotebook);
notebook->SetSelection(notebook->FindPage(this));
}
wxBookCtrlBase::FindPage
int FindPage(const wxWindow *page) const
Returns the index of the specified tab window or wxNOT_FOUND if not found.
wxNotebook
This class represents a notebook control, which manages multiple windows with associated tabs.
Definition: notebook.h:114
wxNotebook::SetSelection
virtual int SetSelection(size_t page)
Sets the selection to the given page, returning the previous selection.
wxStaticCast
#define wxStaticCast(ptr, classname)
This macro checks that the cast is valid in debug mode (an assert failure will result if wxDynamicCas...
Definition: object.h:894

See also
  GetFirstView()

Since
  2.9.5

## ◆ AddView()

virtual bool wxDocument::AddView | ( | wxView * | view | ) |
| virtual

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

## ◆ AlreadySaved()

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).

See also
  IsModified(), GetDocumentSaved()

Since
  2.9.0

## ◆ Close()

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.

Returns
  true if the document was closed

## ◆ DeleteAllViews()

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 implementation is to save and delete the document if no views exist.

## ◆ DeleteContents()

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.

## ◆ DoOpenDocument()

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.

## ◆ DoSaveDocument()

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.

## ◆ GetCommandProcessor()

virtual wxCommandProcessor* wxDocument::GetCommandProcessor | ( |  | ) | const
| virtual

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

See also
  wxCommandProcessor

## ◆ GetDocumentManager()

virtual wxDocManager* wxDocument::GetDocumentManager | ( |  | ) | const
| virtual

Gets a pointer to the associated document manager.

## ◆ GetDocumentName()

wxString wxDocument::GetDocumentName | ( |  | ) | const

Gets the document type name for this document.

See the comment for m_documentTypeName.

## ◆ GetDocumentSaved()

bool wxDocument::GetDocumentSaved | ( |  | ) | const

Return true if this document had been already saved.

See also
  IsModified()

## ◆ GetDocumentTemplate()

virtual wxDocTemplate* wxDocument::GetDocumentTemplate | ( |  | ) | const
| virtual

Gets a pointer to the template that created the document.

## ◆ GetDocumentWindow()

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.

## ◆ GetFilename()

wxString wxDocument::GetFilename | ( |  | ) | const

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

## ◆ GetFirstView()

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.

See also
  GetViews()

## ◆ GetTitle()

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.

## ◆ GetUserReadableName()

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.

## ◆ GetViews() [1/2]

wxList& wxDocument::GetViews | ( |  | ) |

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

See also
  GetFirstView()

## ◆ GetViews() [2/2]

const wxList& wxDocument::GetViews | ( |  | ) | const

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

See also
  GetFirstView()

## ◆ GetViewsVector()

wxViewVector wxDocument::GetViewsVector | ( |  | ) | const

Returns a vector of wxView pointers.

Since
  2.9.5

## ◆ IsChildDocument()

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

## ◆ IsModified()

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.

See also
  Modify()

## ◆ LoadObject() [1/2]

virtual std::istream& wxDocument::LoadObject | ( | std::istream & | stream | ) |
| virtual

Override this function to load the object data from the provided stream.

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

Note that if stream is in the failed state when this function returns, i.e. its `failbit` is set, it indicates that loading the object failed and an error is given. As `failbit` may be set by trying to read after reaching the end of the stream, you may need to call `stream.clear()` to reset it if necessary.

Note
  This overload of LoadObject() is not available if `wxUSE_STD_IOSTREAM` is set to 0 (which is done by `--disable-std_iostreams` option when using configure).

## ◆ LoadObject() [2/2]

virtual wxInputStream& wxDocument::LoadObject | ( | wxInputStream & | stream | ) |
| virtual

Override this function to load the object data from the provided stream.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Note
  This overload of LoadObject() is only available if `wxUSE_STD_IOSTREAM` is set to 0 (which is done by `--disable-std_iostreams` option when using configure). Otherwise, i.e. in the default build of the library, only the overload taking `std::istream` exists.

## ◆ Modify()

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.

See also
  IsModified()

## ◆ OnChangedViewList()

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).

## ◆ OnChangeFilename()

virtual void wxDocument::OnChangeFilename | ( | bool | notifyViews | ) |
| virtual

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

Since
  2.9.0

## ◆ OnCloseDocument()

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.

Returning false from this function prevents the document from closing. Note that there is no need to ask the user if the changes to the document should be saved, as this was already checked by OnSaveModified() by the time this function is called, if necessary, and so, typically, this function should always return true to allow the document to be closed, as leaving it open after asking the user about saving the changes would be confusing.

## ◆ OnCreate()

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

  path | The associated file path.
  flags | Flags passed to CreateDocument().

Returns
  true if the initialization was successful or false if it failed.

## ◆ OnCreateCommandProcessor()

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.

See also
  wxCommandProcessor

## ◆ OnNewDocument()

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.

## ◆ OnOpenDocument()

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.

## ◆ OnSaveBeforeForceClose()

virtual void wxDocument::OnSaveBeforeForceClose | ( |  | ) |
| virtual

This function is called when a document is forced to close.

The default implementation asks the user whether to save the changes but, unlike OnSaveModified(), does not allow to cancel closing.

The document is force closed when wxDocManager::CloseDocument() is called with its `force` argument set to true.

Since
  3.3.0

## ◆ OnSaveDocument()

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.

## ◆ OnSaveModified()

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.

## ◆ RemoveView()

virtual bool wxDocument::RemoveView | ( | wxView * | view | ) |
| virtual

Removes the view from the document's list of views.

If the view was really removed, also calls OnChangedViewList().

Returns
  true if the view was removed or false if the document didn't have this view in the first place.

## ◆ Revert()

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.

## ◆ Save()

virtual bool wxDocument::Save | ( |  | ) |
| virtual

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

## ◆ SaveAs()

virtual bool wxDocument::SaveAs | ( |  | ) |
| virtual

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

## ◆ SaveObject() [1/2]

virtual std::ostream& wxDocument::SaveObject | ( | std::ostream & | stream | ) |
| virtual

Override this function to save the object data into the provided stream.

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

Note
  This overload of SaveObject() is not available if `wxUSE_STD_IOSTREAM` is set to 0 (which is done by `--disable-std_iostreams` option when using configure).

## ◆ SaveObject() [2/2]

virtual wxOutputStream& wxDocument::SaveObject | ( | wxOutputStream & | stream | ) |
| virtual

Override this function to load the object data from the provided stream.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Note
  This overload of SaveObject() is only available if `wxUSE_STD_IOSTREAM` is set to 0 (which is done by `--disable-std_iostreams` option when using configure). Otherwise, i.e. in the default build of the library, only the overload taking `std::ostream` exists.

## ◆ SetCommandProcessor()

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.

See also
  wxCommandProcessor

## ◆ SetDocumentName()

void wxDocument::SetDocumentName | ( | const wxString & | name | ) |

Sets the document type name for this document.

See the comment for m_documentTypeName.

## ◆ SetDocumentSaved()

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).

See also
  GetDocumentSaved(), AlreadySaved()

## ◆ SetDocumentTemplate()

virtual void wxDocument::SetDocumentTemplate | ( | wxDocTemplate * | templ | ) |
| virtual

Sets the pointer to the template that created the document.

Should only be called by the framework.

## ◆ SetFilename()

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.

## ◆ SetTitle()

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.

## ◆ UpdateAllViews()

virtual void wxDocument::UpdateAllViews | ( | wxView * | sender = `nullptr`,
|  | wxObject * | hint = `nullptr`
| ) |  |
| 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

## ◆ m_commandProcessor

wxCommandProcessor* wxDocument::m_commandProcessor
| protected

A pointer to the command processor associated with this document.

## ◆ m_documentFile

wxString wxDocument::m_documentFile
| protected

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

## ◆ m_documentModified

bool wxDocument::m_documentModified
| protected

true if the document has been modified, false otherwise.

## ◆ m_documentTemplate

wxDocTemplate* wxDocument::m_documentTemplate
| protected

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

## ◆ m_documentTitle

wxString wxDocument::m_documentTitle
| protected

Document title.

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

## ◆ m_documentTypeName

wxString wxDocument::m_documentTypeName
| protected

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.

## ◆ m_documentViews

wxList wxDocument::m_documentViews
| protected

List of wxView instances associated with this document.