]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/latex/wx/docmanag.tex
change wxTextValidator to use wxArrayString instead of wxStringList
[wxWidgets.git] / docs / latex / wx / docmanag.tex
index 1cfbfbe0b7b565b6b201955f7cd705c0dc2a3cd7..a7669884ce6426e39e81bf21a9d3a6c61cb26922 100644 (file)
@@ -1,6 +1,6 @@
 \section{\class{wxDocManager}}\label{wxdocmanager}
 
-The wxDocManager class is part of the document/view framework supported by wxWindows,
+The wxDocManager class is part of the document/view framework supported by wxWidgets,
 and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}\rtfsp
 and \helpref{wxDocTemplate}{wxdoctemplate} classes.
 
@@ -9,102 +9,118 @@ and \helpref{wxDocTemplate}{wxdoctemplate} classes.
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
+\wxheading{Include files}
+
+<wx/docview.h>
+
 \wxheading{See also}
 
 \helpref{wxDocManager overview}{wxdocmanageroverview}, \helpref{wxDocument}{wxdocument},\rtfsp
-\helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}
+\helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}, \helpref{wxFileHistory}{wxfilehistory}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxDocManager::m\_currentView}
+\membersection{wxDocManager::m\_currentView}\label{wxdocmanagermcreateview}
 
 \member{wxView*}{m\_currentView}
 
 The currently active view.
 
-\membersection{wxDocManager::m\_defaultDocumentNameCounter}
+\membersection{wxDocManager::m\_defaultDocumentNameCounter}\label{wxdocmanagermdefaultdocumentnamecounter}
 
 \member{int}{m\_defaultDocumentNameCounter}
 
 Stores the integer to be used for the next default document name.
 
-\membersection{wxDocManager::m\_fileHistory}
+\membersection{wxDocManager::m\_fileHistory}\label{wxdocmanagermfilehistory}
 
 \member{wxFileHistory*}{m\_fileHistory}
 
 A pointer to an instance of \helpref{wxFileHistory}{wxfilehistory},
 which manages the history of recently-visited files on the File menu.
 
-\membersection{wxDocManager::m\_maxDocsOpen}
+\membersection{wxDocManager::m\_maxDocsOpen}\label{wxdocmanagermmaxdocsopen}
 
 \member{int}{m\_maxDocsOpen}
 
 Stores the maximum number of documents that can be opened before
 existing documents are closed. By default, this is 10,000.
 
-\membersection{wxDocManager::m\_docs}
+\membersection{wxDocManager::m\_docs}\label{wxdocmanagermdocs}
 
 \member{wxList}{m\_docs}
 
 A list of all documents.
 
-\membersection{wxDocManager::m\_flags}
+\membersection{wxDocManager::m\_flags}\label{wxdocmanagermflags}
 
 \member{long}{m\_flags}
 
 Stores the flags passed to the constructor.
 
-\membersection{wxDocManager::m\_templates}
+\membersection{wxDocManager::m\_lastDirectory}\label{wxdocmanagermlastdirectory}
+
+The directory last selected by the user when opening a file.
+
+\member{wxFileHistory*}{m\_fileHistory}
+
+\membersection{wxDocManager::m\_templates}\label{wxdocmanagermtemplates}
 
 \member{wxList}{mnTemplates}
 
 A list of all document templates.
 
-\membersection{wxDocManager::wxDocManager}
+\membersection{wxDocManager::wxDocManager}\label{wxdocmanagerctor}
 
-\func{void}{wxDocManager}{\param{long}{ flags = wxDEFAULT\_DOCMAN\_FLAGS}, \param{bool}{ initialize = TRUE}}
+\func{void}{wxDocManager}{\param{long}{ flags = wxDEFAULT\_DOCMAN\_FLAGS}, \param{bool}{ initialize = true}}
 
 Constructor. Create a document manager instance dynamically near the start of your application
 before doing any document or view operations.
 
 {\it flags} is currently unused.
 
-If {\it initialize} is TRUE, the \helpref{Initialize}{wxdocmanagerinitialize} function will be called
+If {\it initialize} is true, the \helpref{Initialize}{wxdocmanagerinitialize} 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
+base constructor with false, and then call Initialize in your own constructor, to allow
 your own Initialize or OnCreateFileHistory functions to be called.
 
-\membersection{wxDocManager::\destruct{wxDocManager}}
+\membersection{wxDocManager::\destruct{wxDocManager}}\label{wxdocmanagerdtor}
 
 \func{void}{\destruct{wxDocManager}}{\void}
 
 Destructor.
 
-\membersection{wxDocManager::ActivateView}
+\membersection{wxDocManager::ActivateView}\label{wxdocmanageractivateview}
 
-\func{void}{ActivateView}{\param{wxView* }{doc}, \param{bool}{ activate}, \param{bool}{ deleting}}
+\func{void}{ActivateView}{\param{wxView* }{doc}, \param{bool}{ activate = true}}
 
 Sets the current view.
 
-\membersection{wxDocManager::AddDocument}
+\membersection{wxDocManager::AddDocument}\label{wxdocmanageradddocument}
 
 \func{void}{AddDocument}{\param{wxDocument *}{doc}}
 
 Adds the document to the list of documents.
 
-\membersection{wxDocManager::AddFileToHistory}
+\membersection{wxDocManager::AddFileToHistory}\label{wxdocmanageraddfiletohistory}
 
 \func{void}{AddFileToHistory}{\param{const wxString\& }{filename}}
 
 Adds a file to the file history list, if we have a pointer to an appropriate file menu.
 
-\membersection{wxDocManager::AssociateTemplate}
+\membersection{wxDocManager::AssociateTemplate}\label{wxdocmanagerassociatetemplate}
 
 \func{void}{AssociateTemplate}{\param{wxDocTemplate *}{temp}}
 
 Adds the template to the document manager's template list.
 
-\membersection{wxDocManager::CreateDocument}
+\membersection{wxDocManager::CloseDocuments}\label{wxdocmanagerclosedocuments}
+
+\func{bool}{CloseDocuments}{\param{bool }{force = true}}
+
+Closes all currently opened documents.
+
+\membersection{wxDocManager::CreateDocument}\label{wxdocmanagercreatedocument}
 
 \func{wxDocument*}{CreateDocument}{\param{const wxString\& }{path}, \param{long}{ flags}}
 
@@ -125,7 +141,7 @@ extension (Windows) or by popping up a template choice list (other platforms).
 If the maximum number of documents has been reached, this function
 will delete the oldest currently loaded document before creating a new one.
 
-\membersection{wxDocManager::CreateView}
+\membersection{wxDocManager::CreateView}\label{wxdocmanagercreateview}
 
 \func{wxView*}{CreateView}{\param{wxDocument*}{doc}, \param{long}{ flags}}
 
@@ -133,74 +149,106 @@ Creates a new view for the given document. If more than one view is allowed for
 document (by virtue of multiple templates mentioning the same document type), a choice
 of view is presented to the user.
 
-\membersection{wxDocManager::DisassociateTemplate}
+\membersection{wxDocManager::DisassociateTemplate}\label{wxdocmanagerdisassociatetemplate}
 
 \func{void}{DisassociateTemplate}{\param{wxDocTemplate *}{temp}}
 
 Removes the template from the list of templates.
 
-\membersection{wxDocManager::FileHistoryLoad}
+\membersection{wxDocManager::FileHistoryAddFilesToMenu}\label{wxdocmanagerfilehistoryaddfilestomenu}
 
-\func{void}{FileHistoryLoad}{\param{const wxString\& }{resourceFile}, \param{const wxString\& }{sectionName}}
+\func{void}{FileHistoryAddFilesToMenu}{\void}
 
-Loads the file history from a resource file, using the given section. This must be called
-explicitly by the application.
+Appends the files in the history list, to all menus managed by the file history object.
+
+\func{void}{FileHistoryAddFilesToMenu}{\param{wxMenu*}{ menu}}
+
+Appends the files in the history list, to the given menu only.
+
+\membersection{wxDocManager::FileHistoryLoad}\label{wxdocmanagerfilehistoryload}
 
-\membersection{wxDocManager::FileHistorySave}
+\func{void}{FileHistoryLoad}{\param{wxConfigBase\& }{config}}
 
-\func{void}{FileHistorySave}{\param{const wxString\& }{resourceFile}, \param{const wxString\& }{sectionName}}
+Loads the file history from a config object.
 
-Saves the file history into a resource file, using the given section. This must be called
+\wxheading{See also}
+
+\helpref{wxConfig}{wxconfigbase}
+
+\membersection{wxDocManager::FileHistoryRemoveMenu}\label{wxdocmanagerfilehistoryremovemenu}
+
+\func{void}{FileHistoryRemoveMenu}{\param{wxMenu*}{ menu}}
+
+Removes the given menu from the list of menus managed by the file history object.
+
+\membersection{wxDocManager::FileHistorySave}\label{wxdocmanagerfilehistorysave}
+
+\func{void}{FileHistorySave}{\param{wxConfigBase\& }{resourceFile}}
+
+Saves the file history into a config object. This must be called
 explicitly by the application.
 
-\membersection{wxDocManager::FileHistoryUseMenu}
+\wxheading{See also}
+
+\helpref{wxConfig}{wxconfigbase}
+
+\membersection{wxDocManager::FileHistoryUseMenu}\label{wxdocmanagerfilehistoryusemenu}
 
-\func{void}{FileHistoryUseMenu}{\param{wxMenu *}{menu}}
+\func{void}{FileHistoryUseMenu}{\param{wxMenu*}{ menu}}
 
 Use this menu for appending recently-visited document filenames, for convenient
 access. Calling this function with a valid menu pointer enables the history
 list functionality.
 
-\membersection{wxDocManager::FindTemplateForPath}
+Note that you can add multiple menus using this function, to be managed by the
+file history object.
+
+\membersection{wxDocManager::FindTemplateForPath}\label{wxdocmanagerfindtemplateforpath}
 
 \func{wxDocTemplate *}{FindTemplateForPath}{\param{const wxString\& }{path}}
 
 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.
 
-\membersection{wxDocManager::GetCurrentDocument}
+\membersection{wxDocManager::GetCurrentDocument}\label{wxdocmanagergetcurrentdocument}
 
 \func{wxDocument *}{GetCurrentDocument}{\void}
 
 Returns the document associated with the currently active view (if any).
 
-\membersection{wxDocManager::GetCurrentView}
+\membersection{wxDocManager::GetCurrentView}\label{wxdocmanagergetcurrentview}
 
 \func{wxView *}{GetCurrentView}{\void}
 
 Returns the currently active view 
 
-\membersection{wxDocManager::GetDocuments}
+\membersection{wxDocManager::GetDocuments}\label{wxdocmanagergetdocuments}
 
 \func{wxList\&}{GetDocuments}{\void}
 
 Returns a reference to the list of documents.
 
-\membersection{wxDocManager::GetFileHistory}
+\membersection{wxDocManager::GetFileHistory}\label{wxdocmanagergetfilehistory}
 
 \func{wxFileHistory *}{GetFileHistory}{\void}
 
 Returns a pointer to file history.
 
-\membersection{wxDocManager::GetMaxDocsOpen}
+\membersection{wxDocManager::GetLastDirectory}\label{wxdocmanagergetlastdirectory}
+
+\constfunc{wxString}{GetLastDirectory}{\void}
+
+Returns the directory last selected by the user when opening a file. Initially empty.
+
+\membersection{wxDocManager::GetMaxDocsOpen}\label{wxdocmanagergetmaxdocsopen}
 
 \func{int}{GetMaxDocsOpen}{\void}
 
 Returns the number of documents that can be open simultaneously.
 
-\membersection{wxDocManager::GetNoHistoryFiles}
+\membersection{wxDocManager::GetHistoryFilesCount}\label{wxdocmanagergethistoryfilescount}
 
-\func{int}{GetNoHistoryFiles}{\void}
+\func{size\_t}{GetHistoryFilesCount}{\void}
 
 Returns the number of files currently stored in the file history.
 
@@ -214,14 +262,14 @@ the opportunity to override functionality. If OnCreateFileHistory was called
 from the constructor, an overridden virtual OnCreateFileHistory would not be
 called due to C++'s `interesting' constructor semantics. In fact Initialize
 \rtfsp{\it is} called from the wxDocManager constructor, but this can be
-vetoed by passing FALSE to the second argument, allowing the derived class's
+vetoed by passing false to the second argument, allowing the derived class's
 constructor to call Initialize, possibly calling a different OnCreateFileHistory
 from the default.
 
 The bottom line: if you're not deriving from Initialize, forget it and
 construct wxDocManager with no arguments.
 
-\membersection{wxDocManager::MakeDefaultName}
+\membersection{wxDocManager::MakeDefaultName}\label{wxdocmanagermakedefaultname}
 
 \func{bool}{MakeDefaultName}{\param{const wxString\& }{buf}}
 
@@ -229,70 +277,68 @@ Copies a suitable default name into {\it buf}. This is implemented by
 appending an integer counter to the string {\bf unnamed} and incrementing
 the counter.
 
-\membersection{wxDocManager::OnCreateFileHistory}
+\perlnote{In wxPerl this function must return the modified name rather
+than just modifying the argument.}
+
+\membersection{wxDocManager::OnCreateFileHistory}\label{wxdocmanageroncreatefilehistory}
 
 \func{wxFileHistory *}{OnCreateFileHistory}{\void}
 
 A hook to allow a derived class to create a different type of file history. Called
 from \helpref{Initialize}{wxdocmanagerinitialize}.
 
-\membersection{wxDocManager::OnFileClose}
+\membersection{wxDocManager::OnFileClose}\label{wxdocmanageronfileclose}
 
-\func{void}{OnFileClose}{\void}
+\func{void}{OnFileClose}{\param{wxCommandEvent\& }{event}}
 
 Closes and deletes the currently active document.
 
-\membersection{wxDocManager::OnFileNew}
+\membersection{wxDocManager::OnFileCloseAll}\label{wxdocmanageronfilecloseall}
 
-\func{void}{OnFileNew}{\void}
+\func{void}{OnFileCloseAll}{\param{wxCommandEvent\& }{event}}
 
-Creates a document from a list of templates (if more than one template).
+Closes and deletes all the currently opened documents.
 
-\membersection{wxDocManager::OnFileOpen}
+\membersection{wxDocManager::OnFileNew}\label{wxdocmanageronfilenew}
 
-\func{void}{OnFileOpen}{\void}
+\func{void}{OnFileNew}{\param{wxCommandEvent\& }{event}}
 
-Creates a new document and reads in the selected file.
+Creates a document from a list of templates (if more than one template).
 
-\membersection{wxDocManager::OnFileSave}
+\membersection{wxDocManager::OnFileOpen}\label{wxdocmanageronfileopen}
 
-\func{void}{OnFileSave}{\void}
+\func{void}{OnFileOpen}{\param{wxCommandEvent\& }{event}}
 
-Saves the current document by calling wxDocument::Save for the current document.
+Creates a new document and reads in the selected file.
 
-\membersection{wxDocManager::OnFileSaveAs}
+\membersection{wxDocManager::OnFileRevert}\label{wxdocmanageronfilerevert}
 
-\func{void}{OnFileSaveAs}{\void}
+\func{void}{OnFileRevert}{\param{wxCommandEvent\& }{event}}
 
-Calls wxDocument::SaveAs for the current document.
+Reverts the current document by calling wxDocument::Revert for the current document.
 
-\membersection{wxDocManager::OnMenuCommand}
+\membersection{wxDocManager::OnFileSave}\label{wxdocmanageronfilesave}
 
-\func{void}{OnMenuCommand}{\param{int}{ cmd}}
+\func{void}{OnFileSave}{\param{wxCommandEvent\& }{event}}
 
-Processes menu commands routed from child or parent frames. This deals
-with the following predefined menu item identifiers:
+Saves the current document by calling wxDocument::Save for the current document.
 
-\begin{itemize}\itemsep=0pt
-\item wxID\_OPEN Creates a new document and opens a file into it.
-\item wxID\_CLOSE Closes the current document.
-\item wxID\_NEW Creates a new document.
-\item wxID\_SAVE Saves the document.
-\item wxID\_SAVE\_AS Saves the document into a specified filename.
-\end{itemize}
+\membersection{wxDocManager::OnFileSaveAs}\label{wxdocmanageronfilesaveas}
 
-Unrecognized commands are routed to the currently active wxView's OnMenuCommand.
+\func{void}{OnFileSaveAs}{\param{wxCommandEvent\& }{event}}
 
-\membersection{wxDocManager::RemoveDocument}
+Calls wxDocument::SaveAs for the current document.
+
+\membersection{wxDocManager::RemoveDocument}\label{wxdocmanagerremovedocument}
 
 \func{void}{RemoveDocument}{\param{wxDocument *}{doc}}
 
 Removes the document from the list of documents.
 
-\membersection{wxDocManager::SelectDocumentPath}
+\membersection{wxDocManager::SelectDocumentPath}\label{wxdocmanagerselectdocumentpath}
 
 \func{wxDocTemplate *}{SelectDocumentPath}{\param{wxDocTemplate **}{templates},
- \param{int}{ noTemplates}, \param{const wxString\& }{path}, \param{const wxString\& }{bufSize},
+ \param{int}{ noTemplates}, \param{wxString\& }{path}, 
  \param{long}{ flags}, \param{bool}{ save}}
 
 Under Windows, pops up a file selector with a list of filters corresponding to document templates.
@@ -303,25 +349,59 @@ followed by a file selector.
 
 This function is used in wxDocManager::CreateDocument.
 
-\membersection{wxDocManager::SelectDocumentType}
+\perlnote{In wxPerl {\tt templates} is a reference to a list of templates.
+If you override this method in your document manager it must return
+two values, eg:\par
+  (doctemplate, path) = My::DocManager->SelectDocumentPath( ... );
+}
+
+\membersection{wxDocManager::SelectDocumentType}\label{wxdocmanagerselectdocumenttype}
 
 \func{wxDocTemplate *}{SelectDocumentType}{\param{wxDocTemplate **}{templates},
- \param{int}{ noTemplates}}
+ \param{int}{ noTemplates}, \param{bool}{ sort=false}}
 
 Returns a document template by asking the user (if there is more than one template).
 This function is used in wxDocManager::CreateDocument.
 
-\membersection{wxDocManager::SelectViewType}
+\wxheading{Parameters}
+
+\docparam{templates}{Pointer to an array of templates from which to choose a desired template.}
+\docparam{noTemplates}{Number of templates being pointed to by the {\it templates} pointer.}
+\docparam{sort}{If more than one template is passed in in {\it templates}, 
+then this parameter indicates whether the list of templates that the user 
+will have to choose from is sorted or not when shown the choice box dialog.  
+Default is false.}
+
+\perlnote{In wxPerl {\tt templates} is a reference to a list of templates.}
+
+\membersection{wxDocManager::SelectViewType}\label{wxdocmanagerselectviewtype}
 
 \func{wxDocTemplate *}{SelectViewType}{\param{wxDocTemplate **}{templates},
- \param{int}{ noTemplates}}
+ \param{int}{ noTemplates}, \param{bool}{ sort=false}}
 
 Returns a document template by asking the user (if there is more than one template),
 displaying a list of valid views. This function is used in wxDocManager::CreateView.
-The dialog normally won't appear because the array of templates only contains
+The dialog normally will not appear because the array of templates only contains
 those relevant to the document in question, and often there will only be one such.
 
-\membersection{wxDocManager::SetMaxDocsOpen}
+\wxheading{Parameters}
+
+\docparam{templates}{Pointer to an array of templates from which to choose a desired template.}
+\docparam{noTemplates}{Number of templates being pointed to by the {\it templates} pointer.}
+\docparam{sort}{If more than one template is passed in in {\it templates}, 
+then this parameter indicates whether the list of templates that the user 
+will have to choose from is sorted or not when shown the choice box dialog.  
+Default is false.}
+
+\perlnote{In wxPerl {\tt templates} is a reference to a list of templates.}
+
+\membersection{wxDocManager::SetLastDirectory}\label{wxdocmanagersetlastdirectory}
+
+\func{void}{SetLastDirectory}{\param{const wxString\&}{ dir}}
+
+Sets the directory to be displayed to the user when opening a file. Initially this is empty.
+
+\membersection{wxDocManager::SetMaxDocsOpen}\label{wxdocmanagersetmaxdocsopen}
 
 \func{void}{SetMaxDocsOpen}{\param{int}{ n}}