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