X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ac0ac8241f5ea7249ea01c04452efc0b72f49b1f..134198f1b773199b5506c302bf9510831d0319f5:/docs/latex/wx/docmanag.tex diff --git a/docs/latex/wx/docmanag.tex b/docs/latex/wx/docmanag.tex index b2eecb5e39..534c611c22 100644 --- a/docs/latex/wx/docmanag.tex +++ b/docs/latex/wx/docmanag.tex @@ -1,6 +1,17 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: docmanag.tex +%% Purpose: wxDocManager documentation +%% Author: wxWidgets Team +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) wxWidgets Team +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \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. @@ -13,6 +24,10 @@ and \helpref{wxDocTemplate}{wxdoctemplate} classes. +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{See also} \helpref{wxDocManager overview}{wxdocmanageroverview}, \helpref{wxDocument}{wxdocument},\rtfsp @@ -20,101 +35,123 @@ and \helpref{wxDocTemplate}{wxdoctemplate} classes. \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\_lastDirectory} + +\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} -\member{wxList}{mnTemplates} +\membersection{wxDocManager::m\_templates}\label{wxdocmanagermtemplates} + +\member{wxList}{m\_templates} A list of all document templates. -\membersection{wxDocManager::wxDocManager} -\func{void}{wxDocManager}{\param{long}{ flags = wxDEFAULT\_DOCMAN\_FLAGS}, \param{bool}{ initialize = TRUE}} +\membersection{wxDocManager::wxDocManager}\label{wxdocmanagerctor} + +\func{}{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} -\func{void}{ActivateView}{\param{wxView* }{doc}, \param{bool}{ activate}, \param{bool}{ deleting}} +\membersection{wxDocManager::ActivateView}\label{wxdocmanageractivateview} + +\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}} @@ -135,7 +172,8 @@ 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}} @@ -143,12 +181,14 @@ 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::FileHistoryAddFilesToMenu}\label{wxdocmanagerfilehistoryaddfilestomenu} \func{void}{FileHistoryAddFilesToMenu}{\void} @@ -159,6 +199,7 @@ Appends the files in the history list, to all menus managed by the file history Appends the files in the history list, to the given menu only. + \membersection{wxDocManager::FileHistoryLoad}\label{wxdocmanagerfilehistoryload} \func{void}{FileHistoryLoad}{\param{wxConfigBase\& }{config}} @@ -169,12 +210,14 @@ Loads the file history from a config object. \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}} @@ -186,6 +229,7 @@ explicitly by the application. \helpref{wxConfig}{wxconfigbase} + \membersection{wxDocManager::FileHistoryUseMenu}\label{wxdocmanagerfilehistoryusemenu} \func{void}{FileHistoryUseMenu}{\param{wxMenu*}{ menu}} @@ -197,55 +241,71 @@ list functionality. Note that you can add multiple menus using this function, to be managed by the file history object. -\membersection{wxDocManager::FindTemplateForPath} + +\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::GetLastDirectory}\label{wxdocmanagergetlastdirectory} \constfunc{wxString}{GetLastDirectory}{\void} Returns the directory last selected by the user when opening a file. Initially empty. -\membersection{wxDocManager::GetMaxDocsOpen} + +\membersection{wxDocManager::GetMaxDocsOpen}\label{wxdocmanagergetmaxdocsopen} \func{int}{GetMaxDocsOpen}{\void} Returns the number of documents that can be open simultaneously. -\membersection{wxDocManager::GetNoHistoryFiles} -\func{int}{GetNoHistoryFiles}{\void} +\membersection{wxDocManager::GetHistoryFilesCount}\label{wxdocmanagergethistoryfilescount} + +\func{size\_t}{GetHistoryFilesCount}{\void} Returns the number of files currently stored in the file history. + +\membersection{wxDocManager::GetTemplates}\label{wxdocmanagergettemplates} + +\func{wxList\&}{GetTemplates}{\void} + +Returns a reference to the list of associated templates. + + \membersection{wxDocManager::Initialize}\label{wxdocmanagerinitialize} \func{bool}{Initialize}{\void} @@ -256,85 +316,92 @@ 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} -\func{bool}{MakeDefaultName}{\param{const wxString\& }{buf}} +\membersection{wxDocManager::MakeNewDocumentName}\label{wxdocmanagermakenewdocumentname} -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. +\func{wxString}{MakeNewDocumentName}{\void} -\membersection{wxDocManager::OnCreateFileHistory} +Return a string containing a suitable default name for a new document. By +default this is implemented by appending an integer counter to the string +{\bf unnamed} but can be overridden in the derived classes to do something more +appropriate. + + +\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} -\func{void}{OnFileClose}{\void} +\membersection{wxDocManager::OnFileClose}\label{wxdocmanageronfileclose} + +\func{void}{OnFileClose}{\param{wxCommandEvent\& }{event}} Closes and deletes the currently active document. -\membersection{wxDocManager::OnFileNew} -\func{void}{OnFileNew}{\void} +\membersection{wxDocManager::OnFileCloseAll}\label{wxdocmanageronfilecloseall} + +\func{void}{OnFileCloseAll}{\param{wxCommandEvent\& }{event}} + +Closes and deletes all the currently opened documents. + + +\membersection{wxDocManager::OnFileNew}\label{wxdocmanageronfilenew} + +\func{void}{OnFileNew}{\param{wxCommandEvent\& }{event}} Creates a document from a list of templates (if more than one template). -\membersection{wxDocManager::OnFileOpen} -\func{void}{OnFileOpen}{\void} +\membersection{wxDocManager::OnFileOpen}\label{wxdocmanageronfileopen} + +\func{void}{OnFileOpen}{\param{wxCommandEvent\& }{event}} Creates a new document and reads in the selected file. -\membersection{wxDocManager::OnFileSave} -\func{void}{OnFileSave}{\void} +\membersection{wxDocManager::OnFileRevert}\label{wxdocmanageronfilerevert} -Saves the current document by calling wxDocument::Save for the current document. +\func{void}{OnFileRevert}{\param{wxCommandEvent\& }{event}} -\membersection{wxDocManager::OnFileSaveAs} +Reverts the current document by calling wxDocument::Revert for the current document. -\func{void}{OnFileSaveAs}{\void} -Calls wxDocument::SaveAs for the current document. +\membersection{wxDocManager::OnFileSave}\label{wxdocmanageronfilesave} -\membersection{wxDocManager::OnMenuCommand} +\func{void}{OnFileSave}{\param{wxCommandEvent\& }{event}} -\func{void}{OnMenuCommand}{\param{int}{ cmd}} +Saves the current document by calling wxDocument::Save for the current document. -Processes menu commands routed from child or parent frames. This deals -with the following predefined menu item identifiers: -\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} + +\func{void}{OnFileSaveAs}{\param{wxCommandEvent\& }{event}} -Unrecognized commands are routed to the currently active wxView's OnMenuCommand. +Calls wxDocument::SaveAs for the current document. -\membersection{wxDocManager::RemoveDocument} + +\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. @@ -345,31 +412,63 @@ 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. +\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} + +\membersection{wxDocManager::SetMaxDocsOpen}\label{wxdocmanagersetmaxdocsopen} \func{void}{SetMaxDocsOpen}{\param{int}{ n}} @@ -379,5 +478,3 @@ 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. - -