1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: docmanag.tex 3%% Purpose: wxDocManager documentation 4%% Author: wxWidgets Team 5%% Modified by: 6%% Created: 7%% RCS-ID: $Id: docmanag.tex 53699 2008-05-22 06:34:00Z BP $ 8%% Copyright: (c) wxWidgets Team 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxDocManager}}\label{wxdocmanager} 13 14The wxDocManager class is part of the document/view framework supported by wxWidgets, 15and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}\rtfsp 16and \helpref{wxDocTemplate}{wxdoctemplate} classes. 17 18\wxheading{Derived from} 19 20\helpref{wxEvtHandler}{wxevthandler}\\ 21\helpref{wxObject}{wxobject} 22 23\wxheading{Include files} 24 25<wx/docview.h> 26 27\wxheading{See also} 28 29\helpref{wxDocManager overview}{wxdocmanageroverview}, \helpref{wxDocument}{wxdocument},\rtfsp 30\helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}, \helpref{wxFileHistory}{wxfilehistory} 31 32\latexignore{\rtfignore{\wxheading{Members}}} 33 34 35\membersection{wxDocManager::m\_currentView}\label{wxdocmanagermcreateview} 36 37\member{wxView*}{m\_currentView} 38 39The currently active view. 40 41 42\membersection{wxDocManager::m\_defaultDocumentNameCounter}\label{wxdocmanagermdefaultdocumentnamecounter} 43 44\member{int}{m\_defaultDocumentNameCounter} 45 46Stores the integer to be used for the next default document name. 47 48 49\membersection{wxDocManager::m\_fileHistory}\label{wxdocmanagermfilehistory} 50 51\member{wxFileHistory*}{m\_fileHistory} 52 53A pointer to an instance of \helpref{wxFileHistory}{wxfilehistory}, 54which manages the history of recently-visited files on the File menu. 55 56 57\membersection{wxDocManager::m\_maxDocsOpen}\label{wxdocmanagermmaxdocsopen} 58 59\member{int}{m\_maxDocsOpen} 60 61Stores the maximum number of documents that can be opened before 62existing documents are closed. By default, this is 10,000. 63 64 65\membersection{wxDocManager::m\_docs}\label{wxdocmanagermdocs} 66 67\member{wxList}{m\_docs} 68 69A list of all documents. 70 71 72\membersection{wxDocManager::m\_flags}\label{wxdocmanagermflags} 73 74\member{long}{m\_flags} 75 76Stores the flags passed to the constructor. 77 78 79\membersection{wxDocManager::m\_lastDirectory}\label{wxdocmanagermlastdirectory} 80 81The directory last selected by the user when opening a file. 82 83\member{wxFileHistory*}{m\_fileHistory} 84 85 86\membersection{wxDocManager::m\_templates}\label{wxdocmanagermtemplates} 87 88\member{wxList}{m\_templates} 89 90A list of all document templates. 91 92 93\membersection{wxDocManager::wxDocManager}\label{wxdocmanagerctor} 94 95\func{}{wxDocManager}{\param{long}{ flags = wxDEFAULT\_DOCMAN\_FLAGS}, \param{bool}{ initialize = true}} 96 97Constructor. Create a document manager instance dynamically near the start of your application 98before doing any document or view operations. 99 100{\it flags} is currently unused. 101 102If {\it initialize} is true, the \helpref{Initialize}{wxdocmanagerinitialize} function will be called 103to create a default history list object. If you derive from wxDocManager, you may wish to call the 104base constructor with false, and then call Initialize in your own constructor, to allow 105your own Initialize or OnCreateFileHistory functions to be called. 106 107 108\membersection{wxDocManager::\destruct{wxDocManager}}\label{wxdocmanagerdtor} 109 110\func{void}{\destruct{wxDocManager}}{\void} 111 112Destructor. 113 114 115\membersection{wxDocManager::ActivateView}\label{wxdocmanageractivateview} 116 117\func{void}{ActivateView}{\param{wxView* }{doc}, \param{bool}{ activate = true}} 118 119Sets the current view. 120 121 122\membersection{wxDocManager::AddDocument}\label{wxdocmanageradddocument} 123 124\func{void}{AddDocument}{\param{wxDocument *}{doc}} 125 126Adds the document to the list of documents. 127 128 129\membersection{wxDocManager::AddFileToHistory}\label{wxdocmanageraddfiletohistory} 130 131\func{void}{AddFileToHistory}{\param{const wxString\& }{filename}} 132 133Adds a file to the file history list, if we have a pointer to an appropriate file menu. 134 135 136\membersection{wxDocManager::AssociateTemplate}\label{wxdocmanagerassociatetemplate} 137 138\func{void}{AssociateTemplate}{\param{wxDocTemplate *}{temp}} 139 140Adds the template to the document manager's template list. 141 142 143\membersection{wxDocManager::CloseDocuments}\label{wxdocmanagerclosedocuments} 144 145\func{bool}{CloseDocuments}{\param{bool }{force = true}} 146 147Closes all currently opened documents. 148 149 150\membersection{wxDocManager::CreateDocument}\label{wxdocmanagercreatedocument} 151 152\func{wxDocument*}{CreateDocument}{\param{const wxString\& }{path}, \param{long}{ flags}} 153 154Creates a new document in a manner determined by the {\it flags} parameter, which can be: 155 156\begin{itemize}\itemsep=0pt 157\item wxDOC\_NEW Creates a fresh document. 158\item wxDOC\_SILENT Silently loads the given document file. 159\end{itemize} 160 161If wxDOC\_NEW is present, a new document will be created and returned, possibly after 162asking the user for a template to use if there is more than one document template. 163If wxDOC\_SILENT is present, a new document will be created and the given file loaded 164into it. If neither of these flags is present, the user will be presented with 165a file selector for the file to load, and the template to use will be determined by the 166extension (Windows) or by popping up a template choice list (other platforms). 167 168If the maximum number of documents has been reached, this function 169will delete the oldest currently loaded document before creating a new one. 170 171 172\membersection{wxDocManager::CreateView}\label{wxdocmanagercreateview} 173 174\func{wxView*}{CreateView}{\param{wxDocument*}{doc}, \param{long}{ flags}} 175 176Creates a new view for the given document. If more than one view is allowed for the 177document (by virtue of multiple templates mentioning the same document type), a choice 178of view is presented to the user. 179 180 181\membersection{wxDocManager::DisassociateTemplate}\label{wxdocmanagerdisassociatetemplate} 182 183\func{void}{DisassociateTemplate}{\param{wxDocTemplate *}{temp}} 184 185Removes the template from the list of templates. 186 187 188\membersection{wxDocManager::FileHistoryAddFilesToMenu}\label{wxdocmanagerfilehistoryaddfilestomenu} 189 190\func{void}{FileHistoryAddFilesToMenu}{\void} 191 192Appends the files in the history list, to all menus managed by the file history object. 193 194\func{void}{FileHistoryAddFilesToMenu}{\param{wxMenu*}{ menu}} 195 196Appends the files in the history list, to the given menu only. 197 198 199\membersection{wxDocManager::FileHistoryLoad}\label{wxdocmanagerfilehistoryload} 200 201\func{void}{FileHistoryLoad}{\param{wxConfigBase\& }{config}} 202 203Loads the file history from a config object. 204 205\wxheading{See also} 206 207\helpref{wxConfig}{wxconfigbase} 208 209 210\membersection{wxDocManager::FileHistoryRemoveMenu}\label{wxdocmanagerfilehistoryremovemenu} 211 212\func{void}{FileHistoryRemoveMenu}{\param{wxMenu*}{ menu}} 213 214Removes the given menu from the list of menus managed by the file history object. 215 216 217\membersection{wxDocManager::FileHistorySave}\label{wxdocmanagerfilehistorysave} 218 219\func{void}{FileHistorySave}{\param{wxConfigBase\& }{resourceFile}} 220 221Saves the file history into a config object. This must be called 222explicitly by the application. 223 224\wxheading{See also} 225 226\helpref{wxConfig}{wxconfigbase} 227 228 229\membersection{wxDocManager::FileHistoryUseMenu}\label{wxdocmanagerfilehistoryusemenu} 230 231\func{void}{FileHistoryUseMenu}{\param{wxMenu*}{ menu}} 232 233Use this menu for appending recently-visited document filenames, for convenient 234access. Calling this function with a valid menu pointer enables the history 235list functionality. 236 237Note that you can add multiple menus using this function, to be managed by the 238file history object. 239 240 241\membersection{wxDocManager::FindTemplateForPath}\label{wxdocmanagerfindtemplateforpath} 242 243\func{wxDocTemplate *}{FindTemplateForPath}{\param{const wxString\& }{path}} 244 245Given a path, try to find template that matches the extension. This is only 246an approximate method of finding a template for creating a document. 247 248 249\membersection{wxDocManager::GetCurrentDocument}\label{wxdocmanagergetcurrentdocument} 250 251\func{wxDocument *}{GetCurrentDocument}{\void} 252 253Returns the document associated with the currently active view (if any). 254 255 256\membersection{wxDocManager::GetCurrentView}\label{wxdocmanagergetcurrentview} 257 258\func{wxView *}{GetCurrentView}{\void} 259 260Returns the currently active view 261 262 263\membersection{wxDocManager::GetDocuments}\label{wxdocmanagergetdocuments} 264 265\func{wxList\&}{GetDocuments}{\void} 266 267Returns a reference to the list of documents. 268 269 270\membersection{wxDocManager::GetFileHistory}\label{wxdocmanagergetfilehistory} 271 272\func{wxFileHistory *}{GetFileHistory}{\void} 273 274Returns a pointer to file history. 275 276 277\membersection{wxDocManager::GetLastDirectory}\label{wxdocmanagergetlastdirectory} 278 279\constfunc{wxString}{GetLastDirectory}{\void} 280 281Returns the directory last selected by the user when opening a file. Initially empty. 282 283 284\membersection{wxDocManager::GetMaxDocsOpen}\label{wxdocmanagergetmaxdocsopen} 285 286\func{int}{GetMaxDocsOpen}{\void} 287 288Returns the number of documents that can be open simultaneously. 289 290 291\membersection{wxDocManager::GetHistoryFilesCount}\label{wxdocmanagergethistoryfilescount} 292 293\func{size\_t}{GetHistoryFilesCount}{\void} 294 295Returns the number of files currently stored in the file history. 296 297 298\membersection{wxDocManager::GetTemplates}\label{wxdocmanagergettemplates} 299 300\func{wxList\&}{GetTemplates}{\void} 301 302Returns a reference to the list of associated templates. 303 304 305\membersection{wxDocManager::Initialize}\label{wxdocmanagerinitialize} 306 307\func{bool}{Initialize}{\void} 308 309Initializes data; currently just calls OnCreateFileHistory. Some data cannot 310always be initialized in the constructor because the programmer must be given 311the opportunity to override functionality. If OnCreateFileHistory was called 312from the constructor, an overridden virtual OnCreateFileHistory would not be 313called due to C++'s `interesting' constructor semantics. In fact Initialize 314\rtfsp{\it is} called from the wxDocManager constructor, but this can be 315vetoed by passing false to the second argument, allowing the derived class's 316constructor to call Initialize, possibly calling a different OnCreateFileHistory 317from the default. 318 319The bottom line: if you're not deriving from Initialize, forget it and 320construct wxDocManager with no arguments. 321 322 323\membersection{wxDocManager::MakeDefaultName}\label{wxdocmanagermakedefaultname} 324 325\func{bool}{MakeDefaultName}{\param{const wxString\& }{buf}} 326 327This method is preserved for backwards compatibility in wxWidgets 2.8 but is 328renamed to \helpref{MakeNewDocumentName}{wxdocmanagermakenewdocumentname} in 329wxWidgets 3.0, please see its description for the details. 330 331This function simply copies the value returned by MakeNewDocumentName() into 332the provided \arg{buf} and returns \true. 333 334\perlnote{In wxPerl this function must return the modified name rather 335than just modifying the argument.} 336 337 338\membersection{wxDocManager::MakeNewDocumentName}\label{wxdocmanagermakenewdocumentname} 339 340\func{wxString}{MakeNewDocumentName}{\void} 341 342Returns the name to be used for a new document. The default implementation 343appends an integer counter to the string {\bf unnamed} and increments the 344counter. To customize this behaviour, you need to override the virtual 345\helpref{MakeNewDocumentName}{wxdocmanagermakedefaultname} method but if you 346only need to call this method, an not to override it, please use this method 347which is forward-compatible with wxWidgets 3.0. 348 349\newsince{2.8.8} 350 351 352\membersection{wxDocManager::OnCreateFileHistory}\label{wxdocmanageroncreatefilehistory} 353 354\func{wxFileHistory *}{OnCreateFileHistory}{\void} 355 356A hook to allow a derived class to create a different type of file history. Called 357from \helpref{Initialize}{wxdocmanagerinitialize}. 358 359 360\membersection{wxDocManager::OnFileClose}\label{wxdocmanageronfileclose} 361 362\func{void}{OnFileClose}{\param{wxCommandEvent\& }{event}} 363 364Closes and deletes the currently active document. 365 366 367\membersection{wxDocManager::OnFileCloseAll}\label{wxdocmanageronfilecloseall} 368 369\func{void}{OnFileCloseAll}{\param{wxCommandEvent\& }{event}} 370 371Closes and deletes all the currently opened documents. 372 373 374\membersection{wxDocManager::OnFileNew}\label{wxdocmanageronfilenew} 375 376\func{void}{OnFileNew}{\param{wxCommandEvent\& }{event}} 377 378Creates a document from a list of templates (if more than one template). 379 380 381\membersection{wxDocManager::OnFileOpen}\label{wxdocmanageronfileopen} 382 383\func{void}{OnFileOpen}{\param{wxCommandEvent\& }{event}} 384 385Creates a new document and reads in the selected file. 386 387 388\membersection{wxDocManager::OnFileRevert}\label{wxdocmanageronfilerevert} 389 390\func{void}{OnFileRevert}{\param{wxCommandEvent\& }{event}} 391 392Reverts the current document by calling wxDocument::Revert for the current document. 393 394 395\membersection{wxDocManager::OnFileSave}\label{wxdocmanageronfilesave} 396 397\func{void}{OnFileSave}{\param{wxCommandEvent\& }{event}} 398 399Saves the current document by calling wxDocument::Save for the current document. 400 401 402\membersection{wxDocManager::OnFileSaveAs}\label{wxdocmanageronfilesaveas} 403 404\func{void}{OnFileSaveAs}{\param{wxCommandEvent\& }{event}} 405 406Calls wxDocument::SaveAs for the current document. 407 408 409\membersection{wxDocManager::RemoveDocument}\label{wxdocmanagerremovedocument} 410 411\func{void}{RemoveDocument}{\param{wxDocument *}{doc}} 412 413Removes the document from the list of documents. 414 415 416\membersection{wxDocManager::SelectDocumentPath}\label{wxdocmanagerselectdocumentpath} 417 418\func{wxDocTemplate *}{SelectDocumentPath}{\param{wxDocTemplate **}{templates}, 419 \param{int}{ noTemplates}, \param{wxString\& }{path}, 420 \param{long}{ flags}, \param{bool}{ save}} 421 422Under Windows, pops up a file selector with a list of filters corresponding to document templates. 423The wxDocTemplate corresponding to the selected file's extension is returned. 424 425On other platforms, if there is more than one document template a choice list is popped up, 426followed by a file selector. 427 428This function is used in wxDocManager::CreateDocument. 429 430\perlnote{In wxPerl {\tt templates} is a reference to a list of templates. 431If you override this method in your document manager it must return 432two values, eg:\par 433 (doctemplate, path) = My::DocManager->SelectDocumentPath( ... ); 434} 435 436 437\membersection{wxDocManager::SelectDocumentType}\label{wxdocmanagerselectdocumenttype} 438 439\func{wxDocTemplate *}{SelectDocumentType}{\param{wxDocTemplate **}{templates}, 440 \param{int}{ noTemplates}, \param{bool}{ sort=false}} 441 442Returns a document template by asking the user (if there is more than one template). 443This function is used in wxDocManager::CreateDocument. 444 445\wxheading{Parameters} 446 447\docparam{templates}{Pointer to an array of templates from which to choose a desired template.} 448\docparam{noTemplates}{Number of templates being pointed to by the {\it templates} pointer.} 449\docparam{sort}{If more than one template is passed in in {\it templates}, 450then this parameter indicates whether the list of templates that the user 451will have to choose from is sorted or not when shown the choice box dialog. 452Default is false.} 453 454\perlnote{In wxPerl {\tt templates} is a reference to a list of templates.} 455 456 457\membersection{wxDocManager::SelectViewType}\label{wxdocmanagerselectviewtype} 458 459\func{wxDocTemplate *}{SelectViewType}{\param{wxDocTemplate **}{templates}, 460 \param{int}{ noTemplates}, \param{bool}{ sort=false}} 461 462Returns a document template by asking the user (if there is more than one template), 463displaying a list of valid views. This function is used in wxDocManager::CreateView. 464The dialog normally will not appear because the array of templates only contains 465those relevant to the document in question, and often there will only be one such. 466 467\wxheading{Parameters} 468 469\docparam{templates}{Pointer to an array of templates from which to choose a desired template.} 470\docparam{noTemplates}{Number of templates being pointed to by the {\it templates} pointer.} 471\docparam{sort}{If more than one template is passed in in {\it templates}, 472then this parameter indicates whether the list of templates that the user 473will have to choose from is sorted or not when shown the choice box dialog. 474Default is false.} 475 476\perlnote{In wxPerl {\tt templates} is a reference to a list of templates.} 477 478 479\membersection{wxDocManager::SetLastDirectory}\label{wxdocmanagersetlastdirectory} 480 481\func{void}{SetLastDirectory}{\param{const wxString\&}{ dir}} 482 483Sets the directory to be displayed to the user when opening a file. Initially this is empty. 484 485 486\membersection{wxDocManager::SetMaxDocsOpen}\label{wxdocmanagersetmaxdocsopen} 487 488\func{void}{SetMaxDocsOpen}{\param{int}{ n}} 489 490Sets the maximum number of documents that can be open at a time. By default, this 491is 10,000. If you set it to 1, existing documents will be saved and deleted 492when the user tries to open or create a new one (similar to the behaviour 493of Windows Write, for example). Allowing multiple documents gives behaviour 494more akin to MS Word and other Multiple Document Interface applications. 495 496