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