interface/wx/docview.h

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