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