interface/docview.h

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