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         Return true if this document had been already saved.
1048
1049         @see IsModified()
1050      */
1051     bool GetDocumentSaved() const;
1052
1053     /**
1054         Gets a pointer to the template that created the document.
1055     */
1056     virtual wxDocTemplate* GetDocumentTemplate() const;
1057
1058     /**
1059         Intended to return a suitable window for using as a parent for
1060         document-related dialog boxes. By default, uses the frame associated
1061         with the first view.
1062     */
1063     virtual wxWindow* GetDocumentWindow() const;
1064
1065     /**
1066         Gets the filename associated with this document, or "" if none is
1067         associated.
1068     */
1069     wxString GetFilename() const;
1070
1071     /**
1072         A convenience function to get the first view for a document, because in
1073         many cases a document will only have a single view.
1074
1075         @see GetViews()
1076     */
1077     wxView* GetFirstView() const;
1078
1079     /**
1080         Gets the title for this document. The document title is used for an
1081         associated frame (if any), and is usually constructed by the framework
1082         from the filename.
1083     */
1084     wxString GetTitle() const;
1085
1086     /**
1087         Return the document name suitable to be shown to the user. The default
1088         implementation uses the document title, if any, of the name part of the
1089         document filename if it was set or, otherwise, the string @b unnamed.
1090     */
1091     virtual wxString GetUserReadableName() const;
1092
1093     /**
1094         Returns the list whose elements are the views on the document.
1095
1096         @see GetFirstView()
1097     */
1098     wxList GetViews() const;
1099
1100     /**
1101         Returns @true if the document has been modified since the last save,
1102         @false otherwise. You may need to override this if your document view
1103         maintains its own record of being modified.
1104
1105         @see Modify()
1106     */
1107     virtual bool IsModified() const;
1108
1109     //@{
1110     /**
1111         Override this function and call it from your own LoadObject() before
1112         streaming your own data. LoadObject() is called by the framework
1113         automatically when the document contents need to be loaded.
1114
1115         @note This version of LoadObject() may not exist depending on how
1116               wxWidgets was configured.
1117     */
1118     virtual istream& LoadObject(istream& stream);
1119     virtual wxInputStream& LoadObject(wxInputStream& stream);
1120     //@}
1121
1122     /**
1123         Call with @true to mark the document as modified since the last save,
1124         @false otherwise. You may need to override this if your document view
1125         maintains its own record of being modified.
1126
1127         @see IsModified()
1128     */
1129     virtual void Modify(bool modify);
1130
1131     /**
1132         Called when a view is added to or deleted from this document. The
1133         default implementation saves and deletes the document if no views exist
1134         (the last one has just been removed).
1135     */
1136     virtual void OnChangedViewList();
1137
1138     /**
1139         This virtual function is called when the document is being closed.
1140
1141         The default implementation calls DeleteContents() (an empty
1142         implementation) and sets the modified flag to @false. You can override
1143         it to supply additional behaviour when the document is closed with
1144         Close().
1145
1146         Notice that previous wxWidgets versions used to call this function also
1147         from OnNewDocument(), rather counter-intuitively. This is no longer the
1148         case since wxWidgets 2.9.0.
1149     */
1150     virtual bool OnCloseDocument();
1151
1152     /**
1153         Called just after the document object is created to give it a chance to
1154         initialize itself. The default implementation uses the template
1155         associated with the document to create an initial view. If this
1156         function returns @false, the document is deleted.
1157     */
1158     virtual bool OnCreate(const wxString& path, long flags);
1159
1160     /**
1161         Override this function if you want a different (or no) command
1162         processor to be created when the document is created. By default, it
1163         returns an instance of wxCommandProcessor.
1164
1165         @see wxCommandProcessor
1166     */
1167     virtual wxCommandProcessor* OnCreateCommandProcessor();
1168
1169     /**
1170         The default implementation calls OnSaveModified() and DeleteContents(),
1171         makes a default title for the document, and notifies the views that the
1172         filename (in fact, the title) has changed.
1173     */
1174     virtual bool OnNewDocument();
1175
1176     /**
1177         Constructs an input file stream for the given filename (which must not
1178         be empty), and calls LoadObject(). If LoadObject() returns @true, the
1179         document is set to unmodified; otherwise, an error message box is
1180         displayed. The document's views are notified that the filename has
1181         changed, to give windows an opportunity to update their titles. All of
1182         the document's views are then updated.
1183     */
1184     virtual bool OnOpenDocument(const wxString& filename);
1185
1186     /**
1187         Constructs an output file stream for the given filename (which must not
1188         be empty), and calls SaveObject(). If SaveObject() returns @true, the
1189         document is set to unmodified; otherwise, an error message box is
1190         displayed.
1191     */
1192     virtual bool OnSaveDocument(const wxString& filename);
1193
1194     /**
1195         If the document has been modified, prompts the user to ask if the
1196         changes should be changed. If the user replies Yes, the Save() function
1197         is called. If No, the document is marked as unmodified and the function
1198         succeeds. If Cancel, the function fails.
1199     */
1200     virtual bool OnSaveModified();
1201
1202     /**
1203         Removes the view from the document's list of views, and calls
1204         OnChangedViewList().
1205     */
1206     virtual bool RemoveView(wxView* view);
1207
1208     /**
1209         Saves the document by calling OnSaveDocument() if there is an
1210         associated filename, or SaveAs() if there is no filename.
1211     */
1212     virtual bool Save();
1213
1214     /**
1215         Prompts the user for a file to save to, and then calls
1216         OnSaveDocument().
1217     */
1218     virtual bool SaveAs();
1219
1220     //@{
1221     /**
1222         Override this function and call it from your own SaveObject() before
1223         streaming your own data. SaveObject() is called by the framework
1224         automatically when the document contents need to be saved.
1225
1226         @note This version of SaveObject() may not exist depending on how
1227               wxWidgets was configured.
1228     */
1229     virtual ostream& SaveObject(ostream& stream);
1230     virtual wxOutputStream& SaveObject(wxOutputStream& stream);
1231     //@}
1232
1233     /**
1234         Sets the command processor to be used for this document. The document
1235         will then be responsible for its deletion. Normally you should not call
1236         this; override OnCreateCommandProcessor() instead.
1237
1238         @see wxCommandProcessor
1239     */
1240     virtual void SetCommandProcessor(wxCommandProcessor* processor);
1241
1242     /**
1243         Sets the document type name for this document. See the comment for
1244         @ref m_documentTypeName.
1245     */
1246     void SetDocumentName(const wxString& name);
1247
1248     /**
1249         Sets the pointer to the template that created the document. Should only
1250         be called by the framework.
1251     */
1252     virtual void SetDocumentTemplate(wxDocTemplate* templ);
1253
1254     /**
1255         Sets the filename for this document. Usually called by the framework.
1256
1257         If @a notifyViews is @true, wxView::OnChangeFilename() is called for
1258         all views.
1259     */
1260     void SetFilename(const wxString& filename, bool notifyViews = false);
1261
1262     /**
1263         Sets the title for this document. The document title is used for an
1264         associated frame (if any), and is usually constructed by the framework
1265         from the filename.
1266     */
1267     void SetTitle(const wxString& title);
1268
1269     /**
1270         Updates all views. If @a sender is non-@NULL, does not update this
1271         view. @a hint represents optional information to allow a view to
1272         optimize its update.
1273     */
1274     virtual void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL);
1275
1276 protected:
1277     /**
1278         This method is called by OnSaveDocument() to really save the document
1279         contents to the specified file.
1280
1281         Base class version creates a file-based stream and calls SaveObject().
1282         Override this if you need to do something else or prefer not to use
1283         SaveObject() at all.
1284      */
1285     virtual bool DoSaveDocument(const wxString& file);
1286
1287     /**
1288         This method is called by OnOpenDocument() to really load the document
1289         contents from the specified file.
1290
1291         Base class version creates a file-based stream and calls LoadObject().
1292         Override this if you need to do something else or prefer not to use
1293         LoadObject() at all.
1294      */
1295     virtual bool DoOpenDocument(const wxString& file);
1296
1297     /**
1298         A pointer to the command processor associated with this document.
1299     */
1300     wxCommandProcessor* m_commandProcessor;
1301
1302     /**
1303         Filename associated with this document ("" if none).
1304     */
1305     wxString m_documentFile;
1306
1307     /**
1308         @true if the document has been modified, @false otherwise.
1309     */
1310     bool m_documentModified;
1311
1312     /**
1313         A pointer to the template from which this document was created.
1314     */
1315     wxDocTemplate* m_documentTemplate;
1316
1317     /**
1318         Document title. The document title is used for an associated frame (if
1319         any), and is usually constructed by the framework from the filename.
1320     */
1321     wxString m_documentTitle;
1322
1323     /**
1324         The document type name given to the wxDocTemplate constructor, copied
1325         to this variable when the document is created. If several document
1326         templates are created that use the same document type, this variable is
1327         used in wxDocManager::CreateView() to collate a list of alternative
1328         view types that can be used on this kind of document. Do not change the
1329         value of this variable.
1330     */
1331     wxString m_documentTypeName;
1332
1333     /**
1334         List of wxView instances associated with this document.
1335     */
1336     wxList m_documentViews;
1337 };
1338
1339
1340
1341 /**
1342     @class wxFileHistory
1343
1344     The wxFileHistory encapsulates a user interface convenience, the list of
1345     most recently visited files as shown on a menu (usually the File menu).
1346
1347     wxFileHistory can manage one or more file menus. More than one menu may be
1348     required in an MDI application, where the file history should appear on
1349     each MDI child menu as well as the MDI parent frame.
1350
1351     @library{wxcore}
1352     @category{docview}
1353
1354     @see @ref overview_docview, wxDocManager
1355 */
1356 class wxFileHistory : public wxObject
1357 {
1358 public:
1359     /**
1360         Constructor. Pass the maximum number of files that should be stored and
1361         displayed.
1362
1363         @a idBase defaults to wxID_FILE1 and represents the id given to the
1364         first history menu item. Since menu items can't share the same ID you
1365         should change @a idBase (to one of your own defined IDs) when using
1366         more than one wxFileHistory in your application.
1367     */
1368     wxFileHistory(size_t maxFiles = 9, wxWindowID idBase = wxID_FILE1);
1369
1370     /**
1371         Destructor.
1372     */
1373     virtual ~wxFileHistory();
1374
1375     /**
1376         Adds a file to the file history list, if the object has a pointer to an
1377         appropriate file menu.
1378     */
1379     virtual void AddFileToHistory(const wxString& filename);
1380
1381     /**
1382         Appends the files in the history list, to all menus managed by the file
1383         history object.
1384     */
1385     virtual void AddFilesToMenu();
1386     /**
1387         Appends the files in the history list, to the given menu only.
1388     */
1389     virtual void AddFilesToMenu(wxMenu* menu);
1390
1391     /**
1392         Returns the base identifier for the range used for appending items.
1393     */
1394     wxWindowID GetBaseId() const;
1395
1396     /**
1397         Returns the number of files currently stored in the file history.
1398     */
1399     virtual size_t GetCount() const;
1400
1401     /**
1402         Returns the file at this index (zero-based).
1403     */
1404     virtual wxString GetHistoryFile(size_t index) const;
1405
1406     /**
1407         Returns the maximum number of files that can be stored.
1408     */
1409     virtual int GetMaxFiles() const;
1410
1411     /**
1412         Returns the list of menus that are managed by this file history object.
1413
1414         @see UseMenu()
1415     */
1416     const wxList& GetMenus() const;
1417
1418     /**
1419         Loads the file history from the given config object. This function
1420         should be called explicitly by the application.
1421
1422         @see wxConfigBase
1423     */
1424     virtual void Load(const wxConfigBase& config);
1425
1426     /**
1427         Removes the specified file from the history.
1428     */
1429     virtual void RemoveFileFromHistory(size_t i);
1430
1431     /**
1432         Removes this menu from the list of those managed by this object.
1433     */
1434     virtual void RemoveMenu(wxMenu* menu);
1435
1436     /**
1437         Saves the file history into the given config object. This must be
1438         called explicitly by the application.
1439
1440         @see wxConfigBase
1441     */
1442     virtual void Save(wxConfigBase& config);
1443
1444     /**
1445         Sets the base identifier for the range used for appending items.
1446     */
1447     void SetBaseId(wxWindowID baseId);
1448
1449     /**
1450         Adds this menu to the list of those menus that are managed by this file
1451         history object. Also see AddFilesToMenu() for initializing the menu
1452         with filenames that are already in the history when this function is
1453         called, as this is not done automatically.
1454     */
1455     virtual void UseMenu(wxMenu* menu);
1456
1457     /**
1458         A character array of strings corresponding to the most recently opened
1459         files.
1460     */
1461     char** m_fileHistory;
1462
1463     /**
1464         The number of files stored in the history array.
1465     */
1466     size_t m_fileHistoryN;
1467
1468     /**
1469         The maximum number of files to be stored and displayed on the menu.
1470     */
1471     size_t m_fileMaxFiles;
1472
1473     /**
1474         The file menu used to display the file history list (if enabled).
1475     */
1476     wxMenu* m_fileMenu;
1477 };
1478
1479
1480
1481 // ============================================================================
1482 // Global functions/macros
1483 // ============================================================================
1484
1485 /** @ingroup group_funcmacro_file */
1486 //@{
1487
1488 /**
1489     Copies the given file to @a stream. Useful when converting an old
1490     application to use streams (within the document/view framework, for
1491     example).
1492
1493     @header{wx/docview.h}
1494 */
1495 bool wxTransferFileToStream(const wxString& filename,
1496                             ostream& stream);
1497
1498 /**
1499     Copies the given stream to the file @a filename. Useful when converting an
1500     old application to use streams (within the document/view framework, for
1501     example).
1502
1503     @header{wx/docview.h}
1504 */
1505 bool wxTransferStreamToFile(istream& stream,
1506                              const wxString& filename);
1507
1508 //@}
1509