/**
@class wxDocTemplate
- @wxheader{docview.h}
The wxDocTemplate class is used to model the relationship between a
document class and a view class.
wxDocTemplate(wxDocManager* manager, const wxString& descr,
const wxString& filter, const wxString& dir,
const wxString& ext, const wxString& docTypeName,
- const wxString& viewTypeName,
- wxClassInfo* docClassInfo = NULL,
- wxClassInfo* viewClassInfo = NULL,
- long flags = wxDEFAULT_TEMPLATE_FLAGS);
+ const wxString& viewTypeName, wxClassInfo* docClassInfo = 0,
+ wxClassInfo* viewClassInfo = 0,
+ long flags = wxTEMPLATE_VISIBLE);
/**
Destructor.
*/
- ~wxDocTemplate();
+ virtual ~wxDocTemplate();
/**
Creates a new instance of the associated document class. If you have
This function calls InitDocument() which in turns calls
wxDocument::OnCreate().
*/
- wxDocument* CreateDocument(const wxString& path, long flags = 0);
+ virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
/**
- Creates a new instance of the associated view class. If you have not
- supplied a wxClassInfo parameter to the template constructor, you will
- need to override this function to return an appropriate view instance.
+ Creates a new instance of the associated view class.
+
+ If you have not supplied a wxClassInfo parameter to the template
+ constructor, you will need to override this function to return an
+ appropriate view instance.
+
+ If the new view initialization fails, it must call
+ wxDocument::RemoveView() for consistency with the default behaviour of
+ this function.
*/
- wxView* CreateView(wxDocument* doc, long flags = 0);
+ virtual wxView* CreateView(wxDocument* doc, long flags = 0);
+
+ /**
+ This function implements the default (very primitive) format detection
+ which checks if the extension is that of the template.
+
+ @param path
+ The path to be checked against the template.
+ */
+ virtual bool FileMatchesTemplate(const wxString& path);
/**
Returns the default file extension for the document data, as passed to
the document template constructor.
*/
- wxString GetDefaultExtension();
+ wxString GetDefaultExtension() const;
/**
Returns the text description of this template, as passed to the
document template constructor.
*/
- wxString GetDescription();
+ wxString GetDescription() const;
/**
Returns the default directory, as passed to the document template
constructor.
*/
- wxString GetDirectory();
+ wxString GetDirectory() const;
+
+ /**
+ Returns the run-time class information that allows document
+ instances to be constructed dynamically, as passed to the document
+ template constructor.
+ */
+ wxClassInfo* GetDocClassInfo() const;
/**
Returns a pointer to the document manager instance for which this
template was created.
*/
- wxDocManager* GetDocumentManager();
+ wxDocManager* GetDocumentManager() const;
/**
Returns the document type name, as passed to the document template
constructor.
*/
- wxString GetDocumentName();
+ virtual wxString GetDocumentName() const;
/**
Returns the file filter, as passed to the document template
constructor.
*/
- wxString GetFileFilter();
+ wxString GetFileFilter() const;
/**
Returns the flags, as passed to the document template constructor.
*/
- long GetFlags();
+ long GetFlags() const;
+
+ /**
+ Returns the run-time class information that allows view instances
+ to be constructed dynamically, as passed to the document template
+ constructor.
+ */
+ wxClassInfo* GetViewClassInfo() const;
/**
Returns the view type name, as passed to the document template
constructor.
*/
- wxString GetViewName();
+ virtual wxString GetViewName() const;
/**
- Initialises the document, calling wxDocument::OnCreate(). This is
- called from CreateDocument().
+ Initialises the document, calling wxDocument::OnCreate().
+
+ This is called from CreateDocument().
+
+ If you override this method, notice that you must @em delete the @a doc
+ if its initialization fails for consistency with the default behaviour.
+
+ @param doc
+ The document to initialize.
+ @param path
+ The associated file path.
+ @param flags
+ Flags passed to CreateDocument().
+ @return
+ @true if the initialization was successful or @false if it failed
+ in which case @a doc should be deleted by this function.
*/
- bool InitDocument(wxDocument* doc, const wxString& path, long flags = 0);
+ virtual bool InitDocument(wxDocument* doc,
+ const wxString& path,
+ long flags = 0);
/**
Returns @true if the document template can be shown in user dialogs,
@false otherwise.
*/
- bool IsVisible();
+ bool IsVisible() const;
/**
Sets the default file extension.
/**
@class wxDocManager
- @wxheader{docview.h}
The wxDocManager class is part of the document/view framework supported by
wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate
Constructor. Create a document manager instance dynamically near the
start of your application before doing any document or view operations.
- @a flags is currently unused.
-
If @a initialize is @true, the Initialize() function will be called to
create a default history list object. If you derive from wxDocManager,
you may wish to call the base constructor with @false, and then call
Initialize() in your own constructor, to allow your own Initialize() or
OnCreateFileHistory functions to be called.
+
+ @param flags
+ Currently unused.
+ @param initialize
+ Indicates whether Initialize() should be called by this ctor.
*/
- wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS,
- bool initialize = true);
+ wxDocManager(long flags = 0, bool initialize = true);
/**
Destructor.
*/
- ~wxDocManager();
+ virtual ~wxDocManager();
/**
Sets the current view.
*/
- void ActivateView(wxView* doc, bool activate = true);
+ virtual void ActivateView(wxView* doc, bool activate = true);
/**
Adds the document to the list of documents.
Adds a file to the file history list, if we have a pointer to an
appropriate file menu.
*/
- void AddFileToHistory(const wxString& filename);
+ virtual void AddFileToHistory(const wxString& filename);
/**
Adds the template to the document manager's template list.
bool CloseDocuments(bool force = true);
/**
- Creates a new document in a manner determined by the @a flags
- parameter, which can be:
-
- - wxDOC_NEW - Creates a fresh document.
- - wxDOC_SILENT - Silently loads the given document file.
+ Creates a new document.
+
+ This function can either create a document corresponding to a new
+ file or to an already existing one depending on whether @c wxDOC_NEW is
+ specified in the @a flags.
+
+ By default, this function asks the user for the type of document to
+ open and the path to its file if it's not specified, i.e. if @a path is
+ empty. Specifying @c wxDOC_SILENT flag suppresses any prompts and means
+ that the @a path must be non-empty and there must be a registered
+ document template handling the extension of this file, otherwise a
+ warning message is logged and the function returns @NULL. Notice that
+ @c wxDOC_SILENT can be combined with @c wxDOC_NEW, however in this case
+ the @a path must still be specified, even if the file with this path
+ typically won't exist.
+
+ Finally notice that if this document manager was configured to allow
+ only a limited number of simultaneously opened documents using
+ SetMaxDocsOpen(), this function will try to close the oldest existing
+ document if this number was reached before creating a new document.
+ And if closing the old document fails (e.g. because it was vetoed by
+ user), this function fails as well.
+
+ @param path
+ Path to a file or an empty string. If the path is empty, the user
+ will be asked to select it (thus, this is incompatible with the use
+ of @c wxDOC_SILENT). The file should exist unless @a flags includes
+ @c wxDOC_NEW.
+ @param flags
+ By default, none. May include @c wxDOC_NEW to indicate that the new
+ document corresponds to a new file and not an existing one and
+ @c wxDOC_SILENT to suppress any dialogs asking the user about the
+ file path and type.
+ @return a new document object or @NULL on failure.
+ */
+ virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
- If wxDOC_NEW is present, a new document will be created and returned,
- possibly after asking the user for a template to use if there is more
- than one document template. If wxDOC_SILENT is present, a new document
- will be created and the given file loaded into it. If neither of these
- flags is present, the user will be presented with a file selector for
- the file to load, and the template to use will be determined by the
- extension (Windows) or by popping up a template choice list (other
- platforms).
+ /**
+ Creates an empty new document.
- If the maximum number of documents has been reached, this function will
- delete the oldest currently loaded document before creating a new one.
- */
- wxDocument* CreateDocument(const wxString& path, long flags);
+ This is equivalent to calling CreateDocument() with @c wxDOC_NEW flags
+ and without the file name.
+ */
+ wxDocument *CreateNewDocument();
/**
Creates a new view for the given document. If more than one view is
allowed for the document (by virtue of multiple templates mentioning
the same document type), a choice of view is presented to the user.
*/
- wxView* CreateView(wxDocument* doc, long flags);
+ virtual wxView* CreateView(wxDocument* doc, long flags = 0);
/**
Removes the template from the list of templates.
Appends the files in the history list to all menus managed by the file
history object.
*/
- void FileHistoryAddFilesToMenu();
+ virtual void FileHistoryAddFilesToMenu();
/**
Appends the files in the history list to the given @a menu only.
*/
- void FileHistoryAddFilesToMenu(wxMenu* menu);
+ virtual void FileHistoryAddFilesToMenu(wxMenu* menu);
/**
Loads the file history from a config object.
@see wxConfigBase
*/
- void FileHistoryLoad(const wxConfigBase& config);
+ virtual void FileHistoryLoad(const wxConfigBase& config);
/**
Removes the given menu from the list of menus managed by the file
history object.
*/
- void FileHistoryRemoveMenu(wxMenu* menu);
+ virtual void FileHistoryRemoveMenu(wxMenu* menu);
/**
Saves the file history into a config object. This must be called
@see wxConfigBase
*/
- void FileHistorySave(wxConfigBase& resourceFile);
+ virtual void FileHistorySave(wxConfigBase& resourceFile);
/**
Use this menu for appending recently-visited document filenames, for
@note You can add multiple menus using this function, to be managed by
the file history object.
*/
- void FileHistoryUseMenu(wxMenu* menu);
+ virtual void FileHistoryUseMenu(wxMenu* menu);
/**
Given a path, try to find template that matches the extension. This is
only an approximate method of finding a template for creating a
document.
*/
- wxDocTemplate* FindTemplateForPath(const wxString& path);
+ virtual wxDocTemplate* FindTemplateForPath(const wxString& path);
/**
Returns the document associated with the currently active view (if
any).
*/
- wxDocument* GetCurrentDocument();
+ wxDocument* GetCurrentDocument() const;
/**
Returns the currently active view
*/
- wxView* GetCurrentView();
+ virtual wxView* GetCurrentView() const;
/**
Returns a reference to the list of documents.
*/
- wxList GetDocuments();
+ wxList& GetDocuments();
/**
Returns a pointer to file history.
*/
- wxFileHistory* GetFileHistory();
+ virtual wxFileHistory* GetFileHistory() const;
/**
Returns the number of files currently stored in the file history.
*/
- size_t GetHistoryFilesCount();
+ virtual size_t GetHistoryFilesCount() const;
/**
Returns the directory last selected by the user when opening a file.
/**
Returns the number of documents that can be open simultaneously.
*/
- int GetMaxDocsOpen();
+ int GetMaxDocsOpen() const;
/**
Returns a reference to the list of associated templates.
*/
- wxList GetTemplates();
+ wxList& GetTemplates();
/**
Initializes data; currently just calls OnCreateFileHistory().
The bottom line: if you're not deriving from Initialize(), forget it
and construct wxDocManager with no arguments.
*/
- bool Initialize();
+ virtual bool Initialize();
/**
Return a string containing a suitable default name for a new document.
string @b unnamed but can be overridden in the derived classes to do
something more appropriate.
*/
- wxString MakeNewDocumentName();
+ virtual wxString MakeNewDocumentName();
/**
A hook to allow a derived class to create a different type of file
history. Called from Initialize().
*/
- wxFileHistory* OnCreateFileHistory();
+ virtual wxFileHistory* OnCreateFileHistory();
/**
Closes and deletes the currently active document.
This function is used in CreateDocument().
*/
- wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates,
- int noTemplates, wxString& path,
- long flags, bool save);
+ virtual wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates,
+ int noTemplates, wxString& path,
+ long flags, bool save = false);
/**
Returns a document template by asking the user (if there is more than
will have to choose from is sorted or not when shown the choice box
dialog. Default is @false.
*/
- wxDocTemplate* SelectDocumentType(wxDocTemplate** templates,
- int noTemplates, bool sort = false);
+ virtual wxDocTemplate* SelectDocumentType(wxDocTemplate** templates,
+ int noTemplates,
+ bool sort = false);
/**
Returns a document template by asking the user (if there is more than
will have to choose from is sorted or not when shown the choice box
dialog. Default is @false.
*/
- wxDocTemplate* SelectViewType(wxDocTemplate** templates,
- int noTemplates, bool sort = false);
+ virtual wxDocTemplate* SelectViewType(wxDocTemplate** templates,
+ int noTemplates, bool sort = false);
/**
Sets the directory to be displayed to the user when opening a file.
/**
Sets the maximum number of documents that can be open at a time. By
- default, this is 10,000. If you set it to 1, existing documents will be
- saved and deleted when the user tries to open or create a new one
- (similar to the behaviour of Windows Write, for example). Allowing
- multiple documents gives behaviour more akin to MS Word and other
- Multiple Document Interface applications.
+ default, this is @c INT_MAX, i.e. the number of documents is unlimited.
+ If you set it to 1, existing documents will be saved and deleted when
+ the user tries to open or create a new one (similar to the behaviour of
+ Windows Write, for example). Allowing multiple documents gives
+ behaviour more akin to MS Word and other Multiple Document Interface
+ applications.
*/
void SetMaxDocsOpen(int n);
/**
@class wxView
- @wxheader{docview.h}
The view class can be used to model the viewing and editing component of
an application's file-based data. It is part of the document/view framework
/**
Destructor. Removes itself from the document's list of views.
*/
- ~wxView();
+ virtual ~wxView();
/**
Call this from your view frame's wxDocChildFrame::OnActivate() member
uses notebook pages instead of frames and this is why this method
returns a wxWindow and not a wxFrame.
*/
- wxWindow* GetFrame();
+ wxWindow* GetFrame() const;
/**
Gets the name associated with the view (passed to the wxDocTemplate
/**
Called when the filename has changed. The default implementation
- constructs a suitable title and sets the title of the view frame (if
- any).
+ constructs a suitable title and sets the title of the view frame (if any).
*/
virtual void OnChangeFilename();
/**
Override this function to render the view on the given device context.
*/
- virtual void OnDraw(wxDC* dc);
+ virtual void OnDraw(wxDC* dc) = 0;
/**
Called when the view should be updated.
application-specific information for making updating more
efficient.
*/
- virtual void OnUpdate(wxView* sender, wxObject* hint);
+ virtual void OnUpdate(wxView* sender, wxObject* hint = 0);
/**
Associates the given document with the view. Normally called by the
framework.
*/
- void SetDocument(wxDocument* doc);
+ virtual void SetDocument(wxDocument* doc);
/**
Sets the frame associated with this view. The application should call
/**
@class wxDocChildFrame
- @wxheader{docview.h}
The wxDocChildFrame class provides a default frame for displaying documents
on separate windows. This class can only be used for SDI (not MDI) child
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxDEFAULT_FRAME_STYLE,
- const wxString& name = "frame");
+ const wxString& name = wxFrameNameStr);
/**
Destructor.
*/
- ~wxDocChildFrame();
+ virtual ~wxDocChildFrame();
/**
Returns the document associated with this frame.
override (but still call) this function in order to set the keyboard
focus for your subwindow.
*/
- void OnActivate(wxActivateEvent event);
+ void OnActivate(wxActivateEvent& event);
/**
Closes and deletes the current view and document.
/**
@class wxDocParentFrame
- @wxheader{docview.h}
The wxDocParentFrame class provides a default top-level frame for
applications using the document/view framework. This class can only be used
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxDEFAULT_FRAME_STYLE,
- const wxString& name = "frame");
+ const wxString& name = wxFrameNameStr);
/**
Destructor.
*/
- ~wxDocParentFrame();
+ virtual ~wxDocParentFrame();
/**
Used in two-step construction.
*/
- bool Create(wxDocManager* manager, wxFrame* parent,
- wxWindowID id, const wxString& title,
- const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = wxDEFAULT_FRAME_STYLE,
- const wxString& name = "frame");
+ bool Create(wxDocManager* manager, wxFrame* parent, wxWindowID id,
+ const wxString& title, const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize, long style = 541072960,
+ const wxString& name = wxFrameNameStr);
/**
Returns the associated document manager object.
/**
@class wxDocument
- @wxheader{docview.h}
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
Constructor. Define your own default constructor to initialize
application-specific data.
*/
- wxDocument();
+ wxDocument(wxDocument* parent = 0);
/**
Destructor. Removes itself from the document manager.
*/
- ~wxDocument();
+ virtual ~wxDocument();
/**
If the view is not already in the list of views, adds the view and
*/
virtual bool AddView(wxView* view);
+ /**
+ 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 IsModified(), GetDocumentSaved()
+
+ @since 2.9.0
+ */
+ bool AlreadySaved() const;
+
/**
Closes the document, by calling OnSaveModified() and then (if this
returned @true) OnCloseDocument(). This does not normally delete the
@see wxCommandProcessor
*/
- wxCommandProcessor* GetCommandProcessor() const;
+ virtual wxCommandProcessor* GetCommandProcessor() const;
/**
Gets a pointer to the associated document manager.
*/
- wxDocManager* GetDocumentManager() const;
+ virtual wxDocManager* GetDocumentManager() const;
/**
Gets the document type name for this document. See the comment for
*/
wxString GetDocumentName() const;
+ /**
+ Return true if this document had been already saved.
+
+ @see IsModified()
+ */
+ bool GetDocumentSaved() const;
+
/**
Gets a pointer to the template that created the document.
*/
- wxDocTemplate* GetDocumentTemplate() const;
+ virtual wxDocTemplate* GetDocumentTemplate() const;
/**
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.
*/
- wxWindow* GetDocumentWindow() const;
+ virtual wxWindow* GetDocumentWindow() const;
/**
Gets the filename associated with this document, or "" if none is
*/
virtual wxString GetUserReadableName() const;
+ //@{
/**
Returns the list whose elements are the views on the document.
@see GetFirstView()
*/
- wxList GetViews() const;
+ wxList& GetViews();
+ const wxList& GetViews() const;
+ //@}
/**
Returns @true if the document has been modified since the last save,
virtual void OnChangedViewList();
/**
+ This virtual function is called when the document is being closed.
+
The default implementation calls DeleteContents() (an empty
- implementation) and sets the modified flag to @false. Override this to
- supply additional behaviour when the document is closed with Close().
+ implementation) 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 OnCloseDocument();
/**
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. If this
- function returns @false, the document is deleted.
+ 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.
+
+ @param path
+ The associated file path.
+ @param flags
+ Flags passed to CreateDocument().
+ @return
+ @true if the initialization was successful or @false if it failed.
*/
virtual bool OnCreate(const wxString& path, long flags);
Sets the pointer to the template that created the document. Should only
be called by the framework.
*/
- void SetDocumentTemplate(wxDocTemplate* templ);
+ virtual void SetDocumentTemplate(wxDocTemplate* templ);
/**
Sets the filename for this document. Usually called by the framework.
+ Calls OnChangeFilename() which in turn calls wxView::OnChangeFilename() for
+ all views if @a notifyViews is @true,
+ */
+ void SetFilename(const wxString& filename, bool notifyViews = false);
+
+ /**
If @a notifyViews is @true, wxView::OnChangeFilename() is called for
all views.
+
+ @since 2.9.0
*/
- void SetFilename(const wxString& filename, bool notifyViews = false);
+ virtual void OnChangeFilename(bool notifyViews);
/**
Sets the title for this document. The document title is used for an
view. @a hint represents optional information to allow a view to
optimize its update.
*/
- void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL);
+ virtual void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL);
protected:
/**
/**
@class wxFileHistory
- @wxheader{docview.h}
The wxFileHistory encapsulates a user interface convenience, the list of
most recently visited files as shown on a menu (usually the File menu).
/**
Destructor.
*/
- ~wxFileHistory();
+ virtual ~wxFileHistory();
/**
Adds a file to the file history list, if the object has a pointer to an
appropriate file menu.
*/
- void AddFileToHistory(const wxString& filename);
+ virtual void AddFileToHistory(const wxString& filename);
/**
Appends the files in the history list, to all menus managed by the file
history object.
*/
- void AddFilesToMenu();
+ virtual void AddFilesToMenu();
/**
Appends the files in the history list, to the given menu only.
*/
- void AddFilesToMenu(wxMenu* menu);
+ virtual void AddFilesToMenu(wxMenu* menu);
/**
Returns the base identifier for the range used for appending items.
/**
Returns the number of files currently stored in the file history.
*/
- size_t GetCount() const;
+ virtual size_t GetCount() const;
/**
Returns the file at this index (zero-based).
*/
- wxString GetHistoryFile(size_t index) const;
+ virtual wxString GetHistoryFile(size_t index) const;
/**
Returns the maximum number of files that can be stored.
*/
- int GetMaxFiles() const;
+ virtual int GetMaxFiles() const;
/**
Returns the list of menus that are managed by this file history object.
@see wxConfigBase
*/
- void Load(const wxConfigBase& config);
+ virtual void Load(const wxConfigBase& config);
/**
Removes the specified file from the history.
*/
- void RemoveFileFromHistory(size_t i);
+ virtual void RemoveFileFromHistory(size_t i);
/**
Removes this menu from the list of those managed by this object.
*/
- void RemoveMenu(wxMenu* menu);
+ virtual void RemoveMenu(wxMenu* menu);
/**
Saves the file history into the given config object. This must be
@see wxConfigBase
*/
- void Save(wxConfigBase& config);
+ virtual void Save(wxConfigBase& config);
/**
Sets the base identifier for the range used for appending items.
with filenames that are already in the history when this function is
called, as this is not done automatically.
*/
- void UseMenu(wxMenu* menu);
-
- /**
- A character array of strings corresponding to the most recently opened
- files.
- */
- char** m_fileHistory;
-
- /**
- The number of files stored in the history array.
- */
- size_t m_fileHistoryN;
-
- /**
- The maximum number of files to be stored and displayed on the menu.
- */
- size_t m_fileMaxFiles;
-
- /**
- The file menu used to display the file history list (if enabled).
- */
- wxMenu* m_fileMenu;
+ virtual void UseMenu(wxMenu* menu);
};
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_file */
+/** @addtogroup group_funcmacro_file */
//@{
/**
projects / wxWidgets.git / blobdiff