interface/wx/docview.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        docview.h
   3 // Purpose:     interface of various doc/view framework classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     A vector of wxDocument pointers.
  11
  12     @since 2.9.5
  13 */
  14 typedef wxVector<wxDocument*> wxDocVector;
  15
  16 /**
  17     A vector of wxView pointers.
  18
  19     @since 2.9.5
  20 */
  21 typedef wxVector<wxView*> wxViewVector;
  22
  23 /**
  24     A vector of wxDocTemplate pointers.
  25
  26     @since 2.9.5
  27 */
  28 typedef wxVector<wxDocTemplate*> wxDocTemplateVector;
  29
  30 /**
  31     @class wxDocTemplate
  32
  33     The wxDocTemplate class is used to model the relationship between a
  34     document class and a view class.
  35
  36     @library{wxcore}
  37     @category{docview}
  38
  39     @see @ref overview_docview_wxdoctemplate, wxDocument, wxView
  40 */
  41 class wxDocTemplate : public wxObject
  42 {
  43 public:
  44     /**
  45         Constructor. Create instances dynamically near the start of your
  46         application after creating a wxDocManager instance, and before doing
  47         any document or view operations.
  48
  49         @param manager
  50             The document manager object which manages this template.
  51         @param descr
  52             A short description of what the template is for. This string will
  53             be displayed in the file filter list of Windows file selectors.
  54         @param filter
  55             An appropriate file filter such as "*.txt".
  56         @param dir
  57             The default directory to use for file selectors.
  58         @param ext
  59             The default file extension (such as "txt").
  60         @param docTypeName
  61             A name that should be unique for a given type of document, used for
  62             gathering a list of views relevant to a particular document.
  63         @param viewTypeName
  64             A name that should be unique for a given view.
  65         @param docClassInfo
  66             A pointer to the run-time document class information as returned by
  67             the wxCLASSINFO() macro, e.g. wxCLASSINFO(MyDocumentClass). If this is
  68             not supplied, you will need to derive a new wxDocTemplate class and
  69             override the CreateDocument() member to return a new document
  70             instance on demand.
  71         @param viewClassInfo
  72             A pointer to the run-time view class information as returned by the
  73             wxCLASSINFO() macro, e.g. wxCLASSINFO(MyViewClass). If this is not
  74             supplied, you will need to derive a new wxDocTemplate class and
  75             override the CreateView() member to return a new view instance on
  76             demand.
  77         @param flags
  78             A bit list of the following:
  79             - wxTEMPLATE_VISIBLE       - The template may be displayed to the
  80                                          user in dialogs.
  81             - wxTEMPLATE_INVISIBLE     - The template may not be displayed to
  82                                          the user in dialogs.
  83             - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE.
  84
  85         @beginWxPerlOnly
  86
  87         In wxPerl @a docClassInfo and @a viewClassInfo can be either
  88         @c Wx::ClassInfo objects or strings containing the name of the
  89         perl packages which are to be used as @c Wx::Document and
  90         @c Wx::View classes (they must have a constructor named new);
  91         as an example:
  92
  93         - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
  94           docTypeName, viewTypeName, docClassInfo, viewClassInfo,
  95           flags): will construct document and view objects from the
  96           class information.
  97         - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
  98           docTypeName, viewTypeName, docClassName, viewClassName,
  99           flags): will construct document and view objects from perl
 100           packages.
 101         - Wx::DocTemplate->new(docmgr, descr, filter, dir, ext,
 102           docTypeName, viewTypeName):
 103           in this case @c Wx::DocTemplate::CreateDocument() and
 104           @c Wx::DocTemplate::CreateView() must be overridden
 105         @endWxPerlOnly
 106     */
 107     wxDocTemplate(wxDocManager* manager, const wxString& descr,
 108                   const wxString& filter, const wxString& dir,
 109                   const wxString& ext, const wxString& docTypeName,
 110                   const wxString& viewTypeName, wxClassInfo* docClassInfo = 0,
 111                   wxClassInfo* viewClassInfo = 0,
 112                   long flags = wxTEMPLATE_VISIBLE);
 113
 114     /**
 115         Destructor.
 116     */
 117     virtual ~wxDocTemplate();
 118
 119     /**
 120         Creates a new instance of the associated document class. If you have
 121         not supplied a wxClassInfo parameter to the template constructor, you
 122         will need to override this function to return an appropriate document
 123         instance.
 124
 125         This function calls InitDocument() which in turns calls
 126         wxDocument::OnCreate().
 127     */
 128     virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
 129
 130     /**
 131         Creates a new instance of the associated view class.
 132
 133         If you have not supplied a wxClassInfo parameter to the template
 134         constructor, you will need to override this function to return an
 135         appropriate view instance.
 136
 137         If the new view initialization fails, it must call
 138         wxDocument::RemoveView() for consistency with the default behaviour of
 139         this function.
 140     */
 141     virtual wxView* CreateView(wxDocument* doc, long flags = 0);
 142
 143     /**
 144         This function implements the default (very primitive) format detection
 145         which checks if the extension is that of the template.
 146
 147         @param path
 148             The path to be checked against the template.
 149     */
 150     virtual bool FileMatchesTemplate(const wxString& path);
 151
 152     /**
 153         Returns the default file extension for the document data, as passed to
 154         the document template constructor.
 155     */
 156     wxString GetDefaultExtension() const;
 157
 158     /**
 159         Returns the text description of this template, as passed to the
 160         document template constructor.
 161     */
 162     wxString GetDescription() const;
 163
 164     /**
 165         Returns the default directory, as passed to the document template
 166         constructor.
 167     */
 168     wxString GetDirectory() const;
 169
 170     /**
 171         Returns the run-time class information that allows document
 172         instances to be constructed dynamically, as passed to the document
 173         template constructor.
 174     */
 175     wxClassInfo* GetDocClassInfo() const;
 176
 177     /**
 178         Returns a pointer to the document manager instance for which this
 179         template was created.
 180     */
 181     wxDocManager* GetDocumentManager() const;
 182
 183     /**
 184         Returns the document type name, as passed to the document template
 185         constructor.
 186     */
 187     virtual wxString GetDocumentName() const;
 188
 189     /**
 190         Returns the file filter, as passed to the document template
 191         constructor.
 192     */
 193     wxString GetFileFilter() const;
 194
 195     /**
 196         Returns the flags, as passed to the document template constructor.
 197     */
 198     long GetFlags() const;
 199
 200     /**
 201         Returns a reference to the wxPageSetupDialogData associated with the
 202         printing operations of this document manager.
 203     */
 204     //@{
 205     wxPageSetupDialogData& GetPageSetupDialogData();
 206     const wxPageSetupDialogData& GetPageSetupDialogData() const;
 207     //@}
 208
 209     /**
 210         Returns the run-time class information that allows view instances
 211         to be constructed dynamically, as passed to the document template
 212         constructor.
 213     */
 214     wxClassInfo* GetViewClassInfo() const;
 215
 216     /**
 217         Returns the view type name, as passed to the document template
 218         constructor.
 219     */
 220     virtual wxString GetViewName() const;
 221
 222     /**
 223         Initialises the document, calling wxDocument::OnCreate().
 224
 225         This is called from CreateDocument().
 226
 227         If you override this method, notice that you must @em delete the @a doc
 228         if its initialization fails for consistency with the default behaviour.
 229
 230         @param doc
 231             The document to initialize.
 232         @param path
 233             The associated file path.
 234         @param flags
 235             Flags passed to CreateDocument().
 236         @return
 237             @true if the initialization was successful or @false if it failed
 238             in which case @a doc should be deleted by this function.
 239     */
 240     virtual bool InitDocument(wxDocument* doc,
 241                               const wxString& path,
 242                               long flags = 0);
 243
 244     /**
 245         Returns @true if the document template can be shown in user dialogs,
 246         @false otherwise.
 247     */
 248     bool IsVisible() const;
 249
 250     /**
 251         Sets the default file extension.
 252     */
 253     void SetDefaultExtension(const wxString& ext);
 254
 255     /**
 256         Sets the template description.
 257     */
 258     void SetDescription(const wxString& descr);
 259
 260     /**
 261         Sets the default directory.
 262     */
 263     void SetDirectory(const wxString& dir);
 264
 265     /**
 266         Sets the pointer to the document manager instance for which this
 267         template was created. Should not be called by the application.
 268     */
 269     void SetDocumentManager(wxDocManager* manager);
 270
 271     /**
 272         Sets the file filter.
 273     */
 274     void SetFileFilter(const wxString& filter);
 275
 276     /**
 277         Sets the internal document template flags (see the constructor
 278         description for more details).
 279     */
 280     void SetFlags(long flags);
 281
 282     /**
 283         The default extension for files of this type.
 284     */
 285     wxString m_defaultExt;
 286
 287     /**
 288         A short description of this template.
 289     */
 290     wxString m_description;
 291
 292     /**
 293         The default directory for files of this type.
 294     */
 295     wxString m_directory;
 296
 297     /**
 298         Run-time class information that allows document instances to be
 299         constructed dynamically.
 300     */
 301     wxClassInfo* m_docClassInfo;
 302
 303     /**
 304         The named type of the document associated with this template.
 305     */
 306     wxString m_docTypeName;
 307
 308     /**
 309         A pointer to the document manager for which this template was created.
 310     */
 311     wxDocTemplate* m_documentManager;
 312
 313     /**
 314         The file filter (such as "*.txt") to be used in file selector dialogs.
 315     */
 316     wxString m_fileFilter;
 317
 318     /**
 319         The flags passed to the constructor.
 320     */
 321     long m_flags;
 322
 323     /**
 324         Run-time class information that allows view instances to be constructed
 325         dynamically.
 326     */
 327     wxClassInfo* m_viewClassInfo;
 328
 329     /**
 330         The named type of the view associated with this template.
 331     */
 332     wxString m_viewTypeName;
 333 };
 334
 335
 336
 337 /**
 338     @class wxDocManager
 339
 340     The wxDocManager class is part of the document/view framework supported by
 341     wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate
 342     classes.
 343
 344     @library{wxcore}
 345     @category{docview}
 346
 347     @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate,
 348          wxFileHistory
 349 */
 350 class wxDocManager : public wxEvtHandler
 351 {
 352 public:
 353     /**
 354         Constructor. Create a document manager instance dynamically near the
 355         start of your application before doing any document or view operations.
 356
 357         If @a initialize is @true, the Initialize() function will be called to
 358         create a default history list object. If you derive from wxDocManager,
 359         you may wish to call the base constructor with @false, and then call
 360         Initialize() in your own constructor, to allow your own Initialize() or
 361         OnCreateFileHistory functions to be called.
 362
 363         @param flags
 364             Currently unused.
 365         @param initialize
 366             Indicates whether Initialize() should be called by this ctor.
 367     */
 368     wxDocManager(long flags = 0, bool initialize = true);
 369
 370     /**
 371         Destructor.
 372     */
 373     virtual ~wxDocManager();
 374
 375     /**
 376         Sets the current view.
 377     */
 378     virtual void ActivateView(wxView* doc, bool activate = true);
 379
 380     /**
 381         Adds the document to the list of documents.
 382     */
 383     void AddDocument(wxDocument* doc);
 384
 385     /**
 386         Adds a file to the file history list, if we have a pointer to an
 387         appropriate file menu.
 388     */
 389     virtual void AddFileToHistory(const wxString& filename);
 390
 391     /**
 392         Adds the template to the document manager's template list.
 393     */
 394     void AssociateTemplate(wxDocTemplate* temp);
 395
 396     /**
 397         Search for a particular document template.
 398
 399         Example:
 400         @code
 401            // creating a document instance of the specified document type:
 402            m_doc = (MyDoc*)docManager->FindTemplate(CLASSINFO(MyDoc))->
 403                         CreateDocument(wxEmptyString, wxDOC_SILENT);
 404         @endcode
 405
 406         @param classinfo
 407             Class info of a document class for which a wxDocTemplate had been
 408             previously created.
 409
 410         @return
 411             Pointer to a wxDocTemplate, or @NULL if none found.
 412
 413         @since 2.9.2
 414      */
 415     wxDocTemplate* FindTemplate(const wxClassInfo* classinfo);
 416
 417     /**
 418         Closes the specified document.
 419
 420         If @a force is @true, the document is closed even if it has unsaved
 421         changes.
 422
 423         @param doc
 424             The document to close, must be non-@NULL.
 425         @param force
 426             If @true, close the document even if wxDocument::Close() returns
 427             @false.
 428         @return
 429             @true if the document was closed or @false if closing it was
 430             cancelled by user (only in @a force = @false case).
 431      */
 432     bool CloseDocument(wxDocument *doc, bool force = false);
 433
 434     /**
 435         Closes all currently opened documents.
 436
 437         @see CloseDocument()
 438     */
 439     bool CloseDocuments(bool force = true);
 440
 441     /**
 442         Creates a new document.
 443
 444         This function can either create a document corresponding to a new
 445         file or to an already existing one depending on whether @c wxDOC_NEW is
 446         specified in the @a flags.
 447
 448         By default, this function asks the user for the type of document to
 449         open and the path to its file if it's not specified, i.e. if @a path is
 450         empty. Specifying @c wxDOC_SILENT flag suppresses any prompts and means
 451         that the @a path must be non-empty and there must be a registered
 452         document template handling the extension of this file, otherwise a
 453         warning message is logged and the function returns @NULL. Notice that
 454         @c wxDOC_SILENT can be combined with @c wxDOC_NEW, however in this case
 455         the @a path must still be specified, even if the file with this path
 456         typically won't exist.
 457
 458         Finally notice that if this document manager was configured to allow
 459         only a limited number of simultaneously opened documents using
 460         SetMaxDocsOpen(), this function will try to close the oldest existing
 461         document if this number was reached before creating a new document.
 462         And if closing the old document fails (e.g. because it was vetoed by
 463         user), this function fails as well.
 464
 465         @param path
 466             Path to a file or an empty string. If the path is empty, the user
 467             will be asked to select it (thus, this is incompatible with the use
 468             of @c wxDOC_SILENT). The file should exist unless @a flags includes
 469             @c wxDOC_NEW.
 470         @param flags
 471             By default, none. May include @c wxDOC_NEW to indicate that the new
 472             document corresponds to a new file and not an existing one and
 473             @c wxDOC_SILENT to suppress any dialogs asking the user about the
 474             file path and type.
 475         @return a new document object or @NULL on failure.
 476     */
 477     virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
 478
 479     /**
 480         Creates an empty new document.
 481
 482         This is equivalent to calling CreateDocument() with @c wxDOC_NEW flags
 483         and without the file name.
 484      */
 485     wxDocument *CreateNewDocument();
 486
 487     /**
 488         Creates a new view for the given document. If more than one view is
 489         allowed for the document (by virtue of multiple templates mentioning
 490         the same document type), a choice of view is presented to the user.
 491     */
 492     virtual wxView* CreateView(wxDocument* doc, long flags = 0);
 493
 494     /**
 495         Removes the template from the list of templates.
 496     */
 497     void DisassociateTemplate(wxDocTemplate* temp);
 498
 499     /**
 500         Appends the files in the history list to all menus managed by the file
 501         history object.
 502     */
 503     virtual void FileHistoryAddFilesToMenu();
 504     /**
 505         Appends the files in the history list to the given @a menu only.
 506     */
 507     virtual void FileHistoryAddFilesToMenu(wxMenu* menu);
 508
 509     /**
 510         Loads the file history from a config object.
 511
 512         @see wxConfigBase
 513     */
 514     virtual void FileHistoryLoad(const wxConfigBase& config);
 515
 516     /**
 517         Removes the given menu from the list of menus managed by the file
 518         history object.
 519     */
 520     virtual void FileHistoryRemoveMenu(wxMenu* menu);
 521
 522     /**
 523         Saves the file history into a config object. This must be called
 524         explicitly by the application.
 525
 526         @see wxConfigBase
 527     */
 528     virtual void FileHistorySave(wxConfigBase& resourceFile);
 529
 530     /**
 531         Use this menu for appending recently-visited document filenames, for
 532         convenient access. Calling this function with a valid menu pointer
 533         enables the history list functionality.
 534
 535         @note You can add multiple menus using this function, to be managed by
 536               the file history object.
 537     */
 538     virtual void FileHistoryUseMenu(wxMenu* menu);
 539
 540     /**
 541         Given a path, try to find template that matches the extension. This is
 542         only an approximate method of finding a template for creating a
 543         document.
 544     */
 545     virtual wxDocTemplate* FindTemplateForPath(const wxString& path);
 546
 547     /**
 548         Returns the document associated with the currently active view (if
 549         any).
 550     */
 551     wxDocument* GetCurrentDocument() const;
 552
 553     /**
 554         Returns the currently active view
 555     */
 556     virtual wxView* GetCurrentView() const;
 557
 558     /**
 559         Returns a vector of wxDocument pointers.
 560
 561         @since 2.9.5
 562     */
 563     wxDocVector GetDocumentsVector() const;
 564
 565     /**
 566         Returns a vector of wxDocTemplate pointers.
 567
 568         @since 2.9.5
 569     */
 570     wxDocTemplateVector GetTemplatesVector() const;
 571
 572     /**
 573         Returns a reference to the list of documents.
 574     */
 575     wxList& GetDocuments();
 576
 577     /**
 578         Returns a pointer to file history.
 579     */
 580     virtual wxFileHistory* GetFileHistory() const;
 581
 582     /**
 583         Returns the number of files currently stored in the file history.
 584     */
 585     virtual size_t GetHistoryFilesCount() const;
 586
 587     /**
 588         Returns the directory last selected by the user when opening a file.
 589         Initially empty.
 590     */
 591     wxString GetLastDirectory() const;
 592
 593     /**
 594         Returns the number of documents that can be open simultaneously.
 595     */
 596     int GetMaxDocsOpen() const;
 597
 598     /**
 599         Returns a reference to the list of associated templates.
 600     */
 601     wxList& GetTemplates();
 602
 603     /**
 604         Initializes data; currently just calls OnCreateFileHistory().
 605
 606         Some data cannot always be initialized in the constructor because the
 607         programmer must be given the opportunity to override functionality. If
 608         OnCreateFileHistory() was called from the constructor, an overridden
 609         virtual OnCreateFileHistory() would not be called due to C++'s
 610         'interesting' constructor semantics. In fact Initialize() @e is called
 611         from the wxDocManager constructor, but this can be vetoed by passing
 612         @false to the second argument, allowing the derived class's constructor
 613         to call Initialize(), possibly calling a different
 614         OnCreateFileHistory() from the default.
 615
 616         The bottom line: if you're not deriving from Initialize(), forget it
 617         and construct wxDocManager with no arguments.
 618     */
 619     virtual bool Initialize();
 620
 621     /**
 622         Return a string containing a suitable default name for a new document.
 623         By default this is implemented by appending an integer counter to the
 624         string @b unnamed but can be overridden in the derived classes to do
 625         something more appropriate.
 626     */
 627     virtual wxString MakeNewDocumentName();
 628
 629     /**
 630         A hook to allow a derived class to create a different type of file
 631         history. Called from Initialize().
 632     */
 633     virtual wxFileHistory* OnCreateFileHistory();
 634
 635     /**
 636         Closes and deletes the currently active document.
 637     */
 638     void OnFileClose(wxCommandEvent& event);
 639
 640     /**
 641         Closes and deletes all the currently opened documents.
 642     */
 643     void OnFileCloseAll(wxCommandEvent& event);
 644
 645     /**
 646         Creates a document from a list of templates (if more than one
 647         template).
 648     */
 649     void OnFileNew(wxCommandEvent& event);
 650
 651     /**
 652         Creates a new document and reads in the selected file.
 653     */
 654     void OnFileOpen(wxCommandEvent& event);
 655
 656     /**
 657         Reverts the current document by calling wxDocument::Revert() for the
 658         current document.
 659     */
 660     void OnFileRevert(wxCommandEvent& event);
 661
 662     /**
 663         Saves the current document by calling wxDocument::Save() for the
 664         current document.
 665     */
 666     void OnFileSave(wxCommandEvent& event);
 667
 668     /**
 669         Calls wxDocument::SaveAs() for the current document.
 670     */
 671     void OnFileSaveAs(wxCommandEvent& event);
 672
 673     /**
 674         Removes the document from the list of documents.
 675     */
 676     void RemoveDocument(wxDocument* doc);
 677
 678     /**
 679         Under Windows, pops up a file selector with a list of filters
 680         corresponding to document templates. The wxDocTemplate corresponding to
 681         the selected file's extension is returned.
 682
 683         On other platforms, if there is more than one document template a
 684         choice list is popped up, followed by a file selector.
 685
 686         This function is used in CreateDocument().
 687
 688         @beginWxPerlOnly
 689         In wxPerl @a templates is a reference to a list of templates.
 690         If you override this method in your document manager it must
 691         return two values, eg:
 692
 693         @code
 694         (doctemplate, path) = My::DocManager->SelectDocumentPath(...);
 695         @endcode
 696         @endWxPerlOnly
 697     */
 698     virtual wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates,
 699                                               int noTemplates, wxString& path,
 700                                               long flags, bool save = false);
 701
 702     /**
 703         Returns a document template by asking the user (if there is more than
 704         one template). This function is used in CreateDocument().
 705
 706         @param templates
 707             Pointer to an array of templates from which to choose a desired
 708             template.
 709         @param noTemplates
 710             Number of templates being pointed to by the templates pointer.
 711         @param sort
 712             If more than one template is passed into templates, then this
 713             parameter indicates whether the list of templates that the user
 714             will have to choose from is sorted or not when shown the choice box
 715             dialog. Default is @false.
 716
 717         @beginWxPerlOnly
 718         In wxPerl @a templates is a reference to a list of templates.
 719         @endWxPerlOnly
 720     */
 721     virtual wxDocTemplate* SelectDocumentType(wxDocTemplate** templates,
 722                                               int noTemplates,
 723                                               bool sort = false);
 724
 725     /**
 726         Returns a document template by asking the user (if there is more than
 727         one template), displaying a list of valid views. This function is used
 728         in CreateView(). The dialog normally will not appear because the array
 729         of templates only contains those relevant to the document in question,
 730         and often there will only be one such.
 731
 732         @param templates
 733             Pointer to an array of templates from which to choose a desired
 734             template.
 735         @param noTemplates
 736             Number of templates being pointed to by the templates pointer.
 737         @param sort
 738             If more than one template is passed into templates, then this
 739             parameter indicates whether the list of templates that the user
 740             will have to choose from is sorted or not when shown the choice box
 741             dialog. Default is @false.
 742
 743         @beginWxPerlOnly
 744         In wxPerl @a templates is a reference to a list of templates.
 745         @endWxPerlOnly
 746     */
 747     virtual wxDocTemplate* SelectViewType(wxDocTemplate** templates,
 748                                           int noTemplates, bool sort = false);
 749
 750     /**
 751         Sets the directory to be displayed to the user when opening a file.
 752         Initially this is empty.
 753     */
 754     void SetLastDirectory(const wxString& dir);
 755
 756     /**
 757         Sets the maximum number of documents that can be open at a time. By
 758         default, this is @c INT_MAX, i.e. the number of documents is unlimited.
 759         If you set it to 1, existing documents will be saved and deleted when
 760         the user tries to open or create a new one (similar to the behaviour of
 761         Windows Write, for example). Allowing multiple documents gives
 762         behaviour more akin to MS Word and other Multiple Document Interface
 763         applications.
 764     */
 765     void SetMaxDocsOpen(int n);
 766
 767
 768 protected:
 769     /**
 770         Called when a file selected from the MRU list doesn't exist any more.
 771
 772         The default behaviour is to remove the file from the MRU (most recently
 773         used) files list and the corresponding menu and notify the user about
 774         it but this method can be overridden to customize it.
 775
 776         For example, an application may want to just give an error about the
 777         missing file @a filename but not remove it from the file history. Or it
 778         could ask the user whether the file should be kept or removed.
 779
 780         Notice that this method is called only if the file selected by user
 781         from the MRU files in the menu doesn't exist, but not if opening it
 782         failed for any other reason because in the latter case the default
 783         behaviour of removing the file from the MRU list is inappropriate.
 784         If you still want to do it, you would need to do it by calling
 785         RemoveFileFromHistory() explicitly in the part of the file opening code
 786         that may fail.
 787
 788         @since 2.9.3
 789
 790         @param n
 791             The index of the file in the MRU list, it can be passed to
 792             RemoveFileFromHistory() to remove this file from the list.
 793         @param filename
 794             The full name of the file.
 795      */
 796     virtual void OnMRUFileNotExist(unsigned n, const wxString& filename);
 797
 798     /**
 799         Create the frame used for print preview.
 800
 801         This method can be overridden if you need to change the behaviour or
 802         appearance of the preview window. By default, a standard wxPreviewFrame
 803         is created.
 804
 805         @since 2.9.1
 806
 807         @param preview The associated preview object.
 808         @param parent The parent window for the frame.
 809         @param title The suggested title for the print preview frame.
 810         @return A new print preview frame, must not return @NULL.
 811     */
 812     virtual wxPreviewFrame* CreatePreviewFrame(wxPrintPreviewBase* preview,
 813                                                wxWindow* parent,
 814                                                const wxString& title);
 815
 816     /**
 817         The currently active view.
 818     */
 819     wxView* m_currentView;
 820
 821     /**
 822         Stores the integer to be used for the next default document name.
 823     */
 824     int m_defaultDocumentNameCounter;
 825
 826     /**
 827         A list of all documents.
 828     */
 829     wxList m_docs;
 830
 831     /**
 832         A pointer to an instance of wxFileHistory, which manages the history of
 833         recently-visited files on the File menu.
 834     */
 835     wxFileHistory* m_fileHistory;
 836
 837     /**
 838         The directory last selected by the user when opening a file.
 839     */
 840     wxString m_lastDirectory;
 841
 842     /**
 843         Stores the maximum number of documents that can be opened before
 844         existing documents are closed.
 845
 846         By default, this is @c INT_MAX i.e. practically unlimited.
 847     */
 848     int m_maxDocsOpen;
 849 };
 850
 851
 852
 853 /**
 854     @class wxView
 855
 856     The view class can be used to model the viewing and editing component of
 857     an application's file-based data. It is part of the document/view framework
 858     supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
 859     and wxDocManager classes.
 860
 861     @library{wxcore}
 862     @category{docview}
 863
 864     @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager
 865 */
 866 class wxView : public wxEvtHandler
 867 {
 868 public:
 869     /**
 870         Constructor. Define your own default constructor to initialize
 871         application-specific data.
 872     */
 873     wxView();
 874
 875     /**
 876         Destructor. Removes itself from the document's list of views.
 877     */
 878     virtual ~wxView();
 879
 880     /**
 881         Call this from your view frame's wxDocChildFrame::OnActivate() member
 882         to tell the framework which view is currently active. If your windowing
 883         system doesn't call wxDocChildFrame::OnActivate(), you may need to call
 884         this function from any place where you know the view must be active,
 885         and the framework will need to get the current view.
 886
 887         The prepackaged view frame wxDocChildFrame calls Activate() from its
 888         wxDocChildFrame::OnActivate() member.
 889
 890         This function calls OnActivateView().
 891     */
 892     virtual void Activate(bool activate);
 893
 894     /**
 895         Closes the view by calling OnClose(). If @a deleteWindow is @true, this
 896         function should delete the window associated with the view.
 897     */
 898     virtual bool Close(bool deleteWindow = true);
 899
 900     /**
 901         Gets a pointer to the document associated with the view.
 902     */
 903     wxDocument* GetDocument() const;
 904
 905     /**
 906         Returns a pointer to the document manager instance associated with this
 907         view.
 908     */
 909     wxDocManager* GetDocumentManager() const;
 910
 911     /**
 912         Gets the frame associated with the view (if any). Note that this
 913         "frame" is not a wxFrame at all in the generic MDI implementation which
 914         uses notebook pages instead of frames and this is why this method
 915         returns a wxWindow and not a wxFrame.
 916     */
 917     wxWindow* GetFrame() const;
 918
 919     /**
 920         Gets the name associated with the view (passed to the wxDocTemplate
 921         constructor). Not currently used by the framework.
 922     */
 923     wxString GetViewName() const;
 924
 925     /**
 926         Called when a view is activated by means of Activate(). The default
 927         implementation does nothing.
 928     */
 929     virtual void OnActivateView(bool activate, wxView* activeView,
 930                                 wxView* deactiveView);
 931
 932     /**
 933         Called when the filename has changed. The default implementation
 934         constructs a suitable title and sets the title of the view frame (if any).
 935     */
 936     virtual void OnChangeFilename();
 937
 938     /**
 939         Implements closing behaviour. The default implementation calls
 940         wxDocument::Close() to close the associated document. Does not delete
 941         the view. The application may wish to do some cleaning up operations in
 942         this function, @e if a call to wxDocument::Close() succeeded. For
 943         example, if your views all share the same window, you need to
 944         disassociate the window from the view and perhaps clear the window. If
 945         @a deleteWindow is @true, delete the frame associated with the view.
 946     */
 947     virtual bool OnClose(bool deleteWindow);
 948
 949     /**
 950         Override this to clean up the view when the document is being closed.
 951     */
 952     virtual void OnClosingDocument();
 953
 954     /**
 955         wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just
 956         after the wxDocTemplate creates the wxView, it calls OnCreate(). The
 957         wxView can create a wxDocChildFrame (or derived class) in its
 958         wxView::OnCreate() member function. This wxDocChildFrame provides user
 959         interface elements to view and/or edit the contents of the wxDocument.
 960
 961         By default, simply returns @true. If the function returns @false, the
 962         view will be deleted.
 963     */
 964     virtual bool OnCreate(wxDocument* doc, long flags);
 965
 966     /**
 967         If the printing framework is enabled in the library, this function
 968         returns a wxPrintout object for the purposes of printing. It should
 969         create a new object every time it is called; the framework will delete
 970         objects it creates.
 971
 972         By default, this function returns an instance of wxDocPrintout, which
 973         prints and previews one page by calling OnDraw().
 974
 975         Override to return an instance of a class other than wxDocPrintout.
 976     */
 977     virtual wxPrintout* OnCreatePrintout();
 978
 979     /**
 980         Override this function to render the view on the given device context.
 981     */
 982     virtual void OnDraw(wxDC* dc) = 0;
 983
 984     /**
 985         Called when the view should be updated.
 986
 987         @param sender
 988             A pointer to the wxView that sent the update request, or @NULL if
 989             no single view requested the update (for instance, when the
 990             document is opened).
 991         @param hint
 992             This is unused currently, but may in future contain
 993             application-specific information for making updating more
 994             efficient.
 995     */
 996     virtual void OnUpdate(wxView* sender, wxObject* hint = 0);
 997
 998     /**
 999         Associates the given document with the view. Normally called by the
1000         framework.
1001     */
1002     virtual void SetDocument(wxDocument* doc);
1003
1004     /**
1005         Sets the frame associated with this view. The application should call
1006         this if possible, to tell the view about the frame.
1007
1008         See GetFrame() for the explanation about the mismatch between the
1009         "Frame" in the method name and the type of its parameter.
1010     */
1011     void SetFrame(wxWindow* frame);
1012
1013     /**
1014         Sets the view type name. Should only be called by the framework.
1015     */
1016     void SetViewName(const wxString& name);
1017
1018     /**
1019         The document associated with this view. There may be more than one view
1020         per document, but there can never be more than one document for one
1021         view.
1022     */
1023     wxDocument* m_viewDocument;
1024
1025     /**
1026         Frame associated with the view, if any.
1027     */
1028     wxFrame* m_viewFrame;
1029
1030     /**
1031         The view type name given to the wxDocTemplate constructor, copied to
1032         this variable when the view is created. Not currently used by the
1033         framework.
1034     */
1035     wxString m_viewTypeName;
1036 };
1037
1038
1039
1040 /**
1041     @class wxDocChildFrame
1042
1043     The wxDocChildFrame class provides a default frame for displaying documents
1044     on separate windows. This class can only be used for SDI (not MDI) child
1045     frames.
1046
1047     The class is part of the document/view framework supported by wxWidgets,
1048     and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
1049     classes.
1050
1051     Notice that this class handles ::wxEVT_ACTIVATE event and activates the
1052     child view on receiving it. Don't intercept this event unless you want to
1053     prevent from this happening.
1054
1055     The same remark applies to ::wxEVT_CLOSE_WINDOW, as wxDocParentFrame the
1056     frame handles this event by trying to close the associated view.
1057
1058     @library{wxcore}
1059     @category{docview}
1060
1061     @see @ref overview_docview, @ref page_samples_docview, wxFrame
1062 */
1063 class wxDocChildFrame : public wxFrame
1064 {
1065 public:
1066     /**
1067         Constructor.
1068     */
1069     wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent,
1070                     wxWindowID id, const wxString& title,
1071                     const wxPoint& pos = wxDefaultPosition,
1072                     const wxSize& size = wxDefaultSize,
1073                     long style = wxDEFAULT_FRAME_STYLE,
1074                     const wxString& name = wxFrameNameStr);
1075
1076     /**
1077         Destructor.
1078     */
1079     virtual ~wxDocChildFrame();
1080
1081     /**
1082         Returns the document associated with this frame.
1083     */
1084     wxDocument* GetDocument() const;
1085
1086     /**
1087         Returns the view associated with this frame.
1088     */
1089     wxView* GetView() const;
1090
1091     /**
1092         Sets the document for this frame.
1093     */
1094     void SetDocument(wxDocument* doc);
1095
1096     /**
1097         Sets the view for this frame.
1098     */
1099     void SetView(wxView* view);
1100
1101     /**
1102         The document associated with the frame.
1103     */
1104     wxDocument* m_childDocument;
1105
1106     /**
1107         The view associated with the frame.
1108     */
1109     wxView* m_childView;
1110 };
1111
1112
1113
1114 /**
1115     @class wxDocParentFrame
1116
1117     The wxDocParentFrame class provides a default top-level frame for
1118     applications using the document/view framework. This class can only be used
1119     for SDI (not MDI) parent frames.
1120
1121     It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
1122     classes.
1123
1124     Notice that this class processes ::wxEVT_CLOSE_WINDOW event and tries to
1125     close all open views from its handler. If all the views can be closed, i.e.
1126     if none of them contains unsaved changes or the user decides to not save
1127     them, the window is destroyed. Don't intercept this event in your code
1128     unless you want to replace this logic.
1129
1130     @library{wxcore}
1131     @category{docview}
1132
1133     @see @ref overview_docview, @ref page_samples_docview, wxFrame
1134 */
1135 class wxDocParentFrame : public wxFrame
1136 {
1137 public:
1138     /**
1139         Default constructor.
1140     */
1141     wxDocParentFrame();
1142     /**
1143         Constructor.
1144     */
1145     wxDocParentFrame(wxDocManager* manager, wxFrame* parent,
1146                      wxWindowID id, const wxString& title,
1147                      const wxPoint& pos = wxDefaultPosition,
1148                      const wxSize& size = wxDefaultSize,
1149                      long style = wxDEFAULT_FRAME_STYLE,
1150                      const wxString& name = wxFrameNameStr);
1151
1152     /**
1153         Destructor.
1154     */
1155     virtual ~wxDocParentFrame();
1156
1157     /**
1158         Used in two-step construction.
1159     */
1160     bool Create(wxDocManager* manager, wxFrame* parent, wxWindowID id,
1161                 const wxString& title, const wxPoint& pos = wxDefaultPosition,
1162                 const wxSize& size = wxDefaultSize, long style = 541072960,
1163                 const wxString& name = wxFrameNameStr);
1164
1165     /**
1166         Returns the associated document manager object.
1167     */
1168     wxDocManager* GetDocumentManager() const;
1169 };
1170
1171
1172
1173 /**
1174     @class wxDocument
1175
1176     The document class can be used to model an application's file-based data.
1177
1178     It is part of the document/view framework supported by wxWidgets, and
1179     cooperates with the wxView, wxDocTemplate and wxDocManager classes.
1180
1181     A normal document is the one created without parent document and is
1182     associated with a disk file. Since version 2.9.2 wxWidgets also supports a
1183     special kind of documents called <em>child documents</em> which are virtual
1184     in the sense that they do not correspond to a file but rather to a part of
1185     their parent document. Because of this, the child documents can't be
1186     created directly by user but can only be created by the parent document
1187     (usually when it's being created itself). They also can't be independently
1188     saved. A child document has its own view with the corresponding window.
1189     This view can be closed by user but, importantly, is also automatically
1190     closed when its parent document is closed. Thus, child documents may be
1191     convenient for creating additional windows which need to be closed when the
1192     main document is. The docview sample demonstrates this use of child
1193     documents by creating a child document containing the information about the
1194     parameters of the image opened in the main document.
1195
1196     @library{wxcore}
1197     @category{docview}
1198
1199     @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager
1200 */
1201 class wxDocument : public wxEvtHandler
1202 {
1203 public:
1204     /**
1205         Constructor. Define your own default constructor to initialize
1206         application-specific data.
1207
1208         @param parent
1209             Specifying a non-@c NULL parent document here makes this document a
1210             special <em>child document</em>, see their description in the class
1211             documentation. Notice that this parameter exists but is ignored in
1212             wxWidgets versions prior to 2.9.1.
1213     */
1214     wxDocument(wxDocument* parent = NULL);
1215
1216     /**
1217         Destructor. Removes itself from the document manager.
1218     */
1219     virtual ~wxDocument();
1220
1221     /**
1222         If the view is not already in the list of views, adds the view and
1223         calls OnChangedViewList().
1224     */
1225     virtual bool AddView(wxView* view);
1226
1227     /**
1228         Returns true if the document hasn't been modified since the last time
1229         it had been saved.
1230
1231         Notice that this function returns @false if the document had been never
1232         saved at all, so it may be also used to test whether it makes sense to
1233         save the document: if it returns @true, there is nothing to save but if
1234         @false is returned, it can be saved, even if it might be not modified
1235         (this can be used to create an empty document file by the user).
1236
1237         @see IsModified(), GetDocumentSaved()
1238
1239         @since 2.9.0
1240      */
1241     bool AlreadySaved() const;
1242
1243     /**
1244         Closes the document, by calling OnSaveModified() and then (if this
1245         returned @true) OnCloseDocument(). This does not normally delete the
1246         document object, use DeleteAllViews() to do this implicitly.
1247     */
1248     virtual bool Close();
1249
1250     /**
1251         Calls wxView::Close() and deletes each view. Deleting the final view
1252         will implicitly delete the document itself, because the wxView
1253         destructor calls RemoveView(). This in turns calls OnChangedViewList(),
1254         whose default implemention is to save and delete the document if no
1255         views exist.
1256     */
1257     virtual bool DeleteAllViews();
1258
1259     /**
1260         Virtual method called from OnCloseDocument().
1261
1262         This method may be overridden to perform any additional cleanup which
1263         might be needed when the document is closed.
1264
1265         The return value of this method is currently ignored.
1266
1267         The default version does nothing and simply returns @true.
1268      */
1269     virtual bool DeleteContents();
1270
1271     /**
1272         Returns a pointer to the command processor associated with this
1273         document.
1274
1275         @see wxCommandProcessor
1276     */
1277     virtual wxCommandProcessor* GetCommandProcessor() const;
1278
1279     /**
1280         Gets a pointer to the associated document manager.
1281     */
1282     virtual wxDocManager* GetDocumentManager() const;
1283
1284     /**
1285         Gets the document type name for this document. See the comment for
1286         @ref m_documentTypeName.
1287     */
1288     wxString GetDocumentName() const;
1289
1290     /**
1291         Return true if this document had been already saved.
1292
1293         @see IsModified()
1294      */
1295     bool GetDocumentSaved() const;
1296
1297     /**
1298         Gets a pointer to the template that created the document.
1299     */
1300     virtual wxDocTemplate* GetDocumentTemplate() const;
1301
1302     /**
1303         Intended to return a suitable window for using as a parent for
1304         document-related dialog boxes. By default, uses the frame associated
1305         with the first view.
1306     */
1307     virtual wxWindow* GetDocumentWindow() const;
1308
1309     /**
1310         Gets the filename associated with this document, or "" if none is
1311         associated.
1312     */
1313     wxString GetFilename() const;
1314
1315     /**
1316         A convenience function to get the first view for a document, because in
1317         many cases a document will only have a single view.
1318
1319         @see GetViews()
1320     */
1321     wxView* GetFirstView() const;
1322
1323     /**
1324         Gets the title for this document. The document title is used for an
1325         associated frame (if any), and is usually constructed by the framework
1326         from the filename.
1327     */
1328     wxString GetTitle() const;
1329
1330     /**
1331         Return the document name suitable to be shown to the user. The default
1332         implementation uses the document title, if any, of the name part of the
1333         document filename if it was set or, otherwise, the string @b unnamed.
1334     */
1335     virtual wxString GetUserReadableName() const;
1336
1337     /**
1338         Returns a vector of wxView pointers.
1339
1340         @since 2.9.5
1341     */
1342     wxViewVector GetViewsVector() const;
1343
1344     //@{
1345     /**
1346         Returns the list whose elements are the views on the document.
1347
1348         @see GetFirstView()
1349     */
1350     wxList& GetViews();
1351     const wxList& GetViews() const;
1352     //@}
1353
1354     /**
1355         Returns true if this document is a child document corresponding to a
1356         part of the parent document and not a disk file as usual.
1357
1358         This method can be used to check whether file-related operations make
1359         sense for this document as they only apply to top-level documents and
1360         not child ones.
1361
1362         @since 2.9.2
1363      */
1364     bool IsChildDocument() const;
1365
1366     /**
1367         Returns @true if the document has been modified since the last save,
1368         @false otherwise. You may need to override this if your document view
1369         maintains its own record of being modified.
1370
1371         @see Modify()
1372     */
1373     virtual bool IsModified() const;
1374
1375     //@{
1376     /**
1377         Override this function and call it from your own LoadObject() before
1378         streaming your own data. LoadObject() is called by the framework
1379         automatically when the document contents need to be loaded.
1380
1381         @note This version of LoadObject() may not exist depending on how
1382               wxWidgets was configured.
1383     */
1384     virtual istream& LoadObject(istream& stream);
1385     virtual wxInputStream& LoadObject(wxInputStream& stream);
1386     //@}
1387
1388     /**
1389         Call with @true to mark the document as modified since the last save,
1390         @false otherwise. You may need to override this if your document view
1391         maintains its own record of being modified.
1392
1393         @see IsModified()
1394     */
1395     virtual void Modify(bool modify);
1396
1397     /**
1398         Called when a view is added to or deleted from this document. The
1399         default implementation saves and deletes the document if no views exist
1400         (the last one has just been removed).
1401     */
1402     virtual void OnChangedViewList();
1403
1404     /**
1405         This virtual function is called when the document is being closed.
1406
1407         The default implementation calls DeleteContents() (which may be
1408         overridden to perform additional cleanup) and sets the modified flag to
1409         @false. You can override it to supply additional behaviour when the
1410         document is closed with Close().
1411
1412         Notice that previous wxWidgets versions used to call this function also
1413         from OnNewDocument(), rather counter-intuitively. This is no longer the
1414         case since wxWidgets 2.9.0.
1415     */
1416     virtual bool OnCloseDocument();
1417
1418     /**
1419         Called just after the document object is created to give it a chance to
1420         initialize itself.
1421
1422         The default implementation uses the template associated with the
1423         document to create an initial view.
1424
1425         For compatibility reasons, this method may either delete the document
1426         itself if its initialization fails or not do it in which case it is
1427         deleted by caller. It is recommended to delete the document explicitly
1428         in this function if it can't be initialized.
1429
1430         @param path
1431             The associated file path.
1432         @param flags
1433             Flags passed to CreateDocument().
1434         @return
1435             @true if the initialization was successful or @false if it failed.
1436     */
1437     virtual bool OnCreate(const wxString& path, long flags);
1438
1439     /**
1440         Override this function if you want a different (or no) command
1441         processor to be created when the document is created. By default, it
1442         returns an instance of wxCommandProcessor.
1443
1444         @see wxCommandProcessor
1445     */
1446     virtual wxCommandProcessor* OnCreateCommandProcessor();
1447
1448     /**
1449         The default implementation calls OnSaveModified() and DeleteContents(),
1450         makes a default title for the document, and notifies the views that the
1451         filename (in fact, the title) has changed.
1452     */
1453     virtual bool OnNewDocument();
1454
1455     /**
1456         Constructs an input file stream for the given filename (which must not
1457         be empty), and calls LoadObject(). If LoadObject() returns @true, the
1458         document is set to unmodified; otherwise, an error message box is
1459         displayed. The document's views are notified that the filename has
1460         changed, to give windows an opportunity to update their titles. All of
1461         the document's views are then updated.
1462     */
1463     virtual bool OnOpenDocument(const wxString& filename);
1464
1465     /**
1466         Constructs an output file stream for the given filename (which must not
1467         be empty), and calls SaveObject(). If SaveObject() returns @true, the
1468         document is set to unmodified; otherwise, an error message box is
1469         displayed.
1470     */
1471     virtual bool OnSaveDocument(const wxString& filename);
1472
1473     /**
1474         If the document has been modified, prompts the user to ask if the
1475         changes should be saved. If the user replies Yes, the Save() function
1476         is called. If No, the document is marked as unmodified and the function
1477         succeeds. If Cancel, the function fails.
1478     */
1479     virtual bool OnSaveModified();
1480
1481     /**
1482         Removes the view from the document's list of views, and calls
1483         OnChangedViewList().
1484     */
1485     virtual bool RemoveView(wxView* view);
1486
1487     /**
1488         Saves the document by calling OnSaveDocument() if there is an
1489         associated filename, or SaveAs() if there is no filename.
1490     */
1491     virtual bool Save();
1492
1493     /**
1494         Prompts the user for a file to save to, and then calls
1495         OnSaveDocument().
1496     */
1497     virtual bool SaveAs();
1498
1499     /**
1500         Discard changes and load last saved version.
1501
1502         Prompts the user first, and then calls DoOpenDocument() to reload the
1503         current file.
1504     */
1505     virtual bool Revert();
1506
1507     //@{
1508     /**
1509         Override this function and call it from your own SaveObject() before
1510         streaming your own data. SaveObject() is called by the framework
1511         automatically when the document contents need to be saved.
1512
1513         @note This version of SaveObject() may not exist depending on how
1514               wxWidgets was configured.
1515     */
1516     virtual ostream& SaveObject(ostream& stream);
1517     virtual wxOutputStream& SaveObject(wxOutputStream& stream);
1518     //@}
1519
1520     /**
1521         Sets the command processor to be used for this document. The document
1522         will then be responsible for its deletion. Normally you should not call
1523         this; override OnCreateCommandProcessor() instead.
1524
1525         @see wxCommandProcessor
1526     */
1527     virtual void SetCommandProcessor(wxCommandProcessor* processor);
1528
1529     /**
1530         Sets the document type name for this document. See the comment for
1531         @ref m_documentTypeName.
1532     */
1533     void SetDocumentName(const wxString& name);
1534
1535     /**
1536         Sets the pointer to the template that created the document. Should only
1537         be called by the framework.
1538     */
1539     virtual void SetDocumentTemplate(wxDocTemplate* templ);
1540
1541     /**
1542         Sets if this document has been already saved or not.
1543
1544         Normally there is no need to call this function as the document-view
1545         framework does it itself as the documents are loaded from and saved to
1546         the files. However it may be useful in some particular cases, for
1547         example it may be called with @false argument to prevent the user
1548         from saving the just opened document into the same file if this
1549         shouldn't be done for some reason (e.g. file format version changes and
1550         a new extension should be used for saving).
1551
1552         @see GetDocumentSaved(), AlreadySaved()
1553      */
1554     void SetDocumentSaved(bool saved = true);
1555
1556     /**
1557         Sets the filename for this document. Usually called by the framework.
1558
1559         Calls OnChangeFilename() which in turn calls wxView::OnChangeFilename() for
1560         all views if @a notifyViews is @true.
1561     */
1562     void SetFilename(const wxString& filename, bool notifyViews = false);
1563
1564     /**
1565         If @a notifyViews is @true, wxView::OnChangeFilename() is called for
1566         all views.
1567
1568         @since 2.9.0
1569     */
1570     virtual void OnChangeFilename(bool notifyViews);
1571
1572     /**
1573         Sets the title for this document. The document title is used for an
1574         associated frame (if any), and is usually constructed by the framework
1575         from the filename.
1576     */
1577     void SetTitle(const wxString& title);
1578
1579     /**
1580         Updates all views. If @a sender is non-@NULL, does not update this
1581         view. @a hint represents optional information to allow a view to
1582         optimize its update.
1583     */
1584     virtual void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL);
1585
1586 protected:
1587     /**
1588         This method is called by OnSaveDocument() to really save the document
1589         contents to the specified file.
1590
1591         Base class version creates a file-based stream and calls SaveObject().
1592         Override this if you need to do something else or prefer not to use
1593         SaveObject() at all.
1594      */
1595     virtual bool DoSaveDocument(const wxString& file);
1596
1597     /**
1598         This method is called by OnOpenDocument() to really load the document
1599         contents from the specified file.
1600
1601         Base class version creates a file-based stream and calls LoadObject().
1602         Override this if you need to do something else or prefer not to use
1603         LoadObject() at all.
1604      */
1605     virtual bool DoOpenDocument(const wxString& file);
1606
1607     /**
1608         A pointer to the command processor associated with this document.
1609     */
1610     wxCommandProcessor* m_commandProcessor;
1611
1612     /**
1613         Filename associated with this document ("" if none).
1614     */
1615     wxString m_documentFile;
1616
1617     /**
1618         @true if the document has been modified, @false otherwise.
1619     */
1620     bool m_documentModified;
1621
1622     /**
1623         A pointer to the template from which this document was created.
1624     */
1625     wxDocTemplate* m_documentTemplate;
1626
1627     /**
1628         Document title. The document title is used for an associated frame (if
1629         any), and is usually constructed by the framework from the filename.
1630     */
1631     wxString m_documentTitle;
1632
1633     /**
1634         The document type name given to the wxDocTemplate constructor, copied
1635         to this variable when the document is created. If several document
1636         templates are created that use the same document type, this variable is
1637         used in wxDocManager::CreateView() to collate a list of alternative
1638         view types that can be used on this kind of document. Do not change the
1639         value of this variable.
1640     */
1641     wxString m_documentTypeName;
1642
1643     /**
1644         List of wxView instances associated with this document.
1645     */
1646     wxList m_documentViews;
1647 };
1648
1649
1650 // ============================================================================
1651 // Global functions/macros
1652 // ============================================================================
1653
1654 /** @addtogroup group_funcmacro_file */
1655 //@{
1656
1657 /**
1658     Copies the given file to @a stream. Useful when converting an old
1659     application to use streams (within the document/view framework, for
1660     example).
1661
1662     @header{wx/docview.h}
1663 */
1664 bool wxTransferFileToStream(const wxString& filename,
1665                             ostream& stream);
1666
1667 /**
1668     Copies the given stream to the file @a filename. Useful when converting an
1669     old application to use streams (within the document/view framework, for
1670     example).
1671
1672     @header{wx/docview.h}
1673 */
1674 bool wxTransferStreamToFile(istream& stream,
1675                              const wxString& filename);
1676
1677 //@}
1678