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