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     wxDocTemplate* SelectDocumentType(wxDocTemplate** templates,
 558                                       int noTemplates, bool sort = false);
 559
 560     /**
 561         Returns a document template by asking the user (if there is more than
 562         one template), displaying a list of valid views. This function is used
 563         in CreateView(). The dialog normally will not appear because the array
 564         of templates only contains those relevant to the document in question,
 565         and often there will only be one such.
 566
 567         @param templates
 568             Pointer to an array of templates from which to choose a desired
 569             template.
 570         @param noTemplates
 571             Number of templates being pointed to by the templates pointer.
 572         @param sort
 573             If more than one template is passed in in templates, then this
 574             parameter indicates whether the list of templates that the user
 575             will have to choose from is sorted or not when shown the choice box
 576             dialog. Default is @false.
 577     */
 578     wxDocTemplate* SelectViewType(wxDocTemplate** templates,
 579                                   int noTemplates, bool sort = false);
 580
 581     /**
 582         Sets the directory to be displayed to the user when opening a file.
 583         Initially this is empty.
 584     */
 585     void SetLastDirectory(const wxString& dir);
 586
 587     /**
 588         Sets the maximum number of documents that can be open at a time. By
 589         default, this is @c INT_MAX, i.e. the number of documents is unlimited.
 590         If you set it to 1, existing documents will be saved and deleted when
 591         the user tries to open or create a new one (similar to the behaviour of
 592         Windows Write, for example). Allowing multiple documents gives
 593         behaviour more akin to MS Word and other Multiple Document Interface
 594         applications.
 595     */
 596     void SetMaxDocsOpen(int n);
 597
 598     /**
 599         The currently active view.
 600     */
 601     wxView* m_currentView;
 602
 603     /**
 604         Stores the integer to be used for the next default document name.
 605     */
 606     int m_defaultDocumentNameCounter;
 607
 608     /**
 609         A list of all documents.
 610     */
 611     wxList m_docs;
 612
 613     /**
 614         A pointer to an instance of wxFileHistory, which manages the history of
 615         recently-visited files on the File menu.
 616     */
 617     wxFileHistory* m_fileHistory;
 618
 619     /**
 620         Stores the flags passed to the constructor.
 621     */
 622     long m_flags;
 623
 624     /**
 625         The directory last selected by the user when opening a file.
 626     */
 627     wxFileHistory* m_fileHistory;
 628
 629     /**
 630         Stores the maximum number of documents that can be opened before
 631         existing documents are closed. By default, this is 10,000.
 632     */
 633     int m_maxDocsOpen;
 634 };
 635
 636
 637
 638 /**
 639     @class wxView
 640
 641     The view class can be used to model the viewing and editing component of
 642     an application's file-based data. It is part of the document/view framework
 643     supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
 644     and wxDocManager classes.
 645
 646     @library{wxcore}
 647     @category{docview}
 648
 649     @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager
 650 */
 651 class wxView : public wxEvtHandler
 652 {
 653 public:
 654     /**
 655         Constructor. Define your own default constructor to initialize
 656         application-specific data.
 657     */
 658     wxView();
 659
 660     /**
 661         Destructor. Removes itself from the document's list of views.
 662     */
 663     virtual ~wxView();
 664
 665     /**
 666         Call this from your view frame's wxDocChildFrame::OnActivate() member
 667         to tell the framework which view is currently active. If your windowing
 668         system doesn't call wxDocChildFrame::OnActivate(), you may need to call
 669         this function from any place where you know the view must be active,
 670         and the framework will need to get the current view.
 671
 672         The prepackaged view frame wxDocChildFrame calls Activate() from its
 673         wxDocChildFrame::OnActivate() member.
 674
 675         This function calls OnActivateView().
 676     */
 677     virtual void Activate(bool activate);
 678
 679     /**
 680         Closes the view by calling OnClose(). If @a deleteWindow is @true, this
 681         function should delete the window associated with the view.
 682     */
 683     virtual bool Close(bool deleteWindow = true);
 684
 685     /**
 686         Gets a pointer to the document associated with the view.
 687     */
 688     wxDocument* GetDocument() const;
 689
 690     /**
 691         Returns a pointer to the document manager instance associated with this
 692         view.
 693     */
 694     wxDocManager* GetDocumentManager() const;
 695
 696     /**
 697         Gets the frame associated with the view (if any). Note that this
 698         "frame" is not a wxFrame at all in the generic MDI implementation which
 699         uses notebook pages instead of frames and this is why this method
 700         returns a wxWindow and not a wxFrame.
 701     */
 702     wxWindow* GetFrame() const;
 703
 704     /**
 705         Gets the name associated with the view (passed to the wxDocTemplate
 706         constructor). Not currently used by the framework.
 707     */
 708     wxString GetViewName() const;
 709
 710     /**
 711         Called when a view is activated by means of Activate(). The default
 712         implementation does nothing.
 713     */
 714     virtual void OnActivateView(bool activate, wxView* activeView,
 715                                 wxView* deactiveView);
 716
 717     /**
 718         Called when the filename has changed. The default implementation
 719         constructs a suitable title and sets the title of the view frame (if
 720         any).
 721     */
 722     virtual void OnChangeFilename();
 723
 724     /**
 725         Implements closing behaviour. The default implementation calls
 726         wxDocument::Close() to close the associated document. Does not delete
 727         the view. The application may wish to do some cleaning up operations in
 728         this function, @e if a call to wxDocument::Close() succeeded. For
 729         example, if your views all share the same window, you need to
 730         disassociate the window from the view and perhaps clear the window. If
 731         @a deleteWindow is @true, delete the frame associated with the view.
 732     */
 733     virtual bool OnClose(bool deleteWindow);
 734
 735     /**
 736         Override this to clean up the view when the document is being closed.
 737     */
 738     virtual void OnClosingDocument();
 739
 740     /**
 741         wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just
 742         after the wxDocTemplate creates the wxView, it calls OnCreate(). The
 743         wxView can create a wxDocChildFrame (or derived class) in its
 744         wxView::OnCreate() member function. This wxDocChildFrame provides user
 745         interface elements to view and/or edit the contents of the wxDocument.
 746
 747         By default, simply returns @true. If the function returns @false, the
 748         view will be deleted.
 749     */
 750     virtual bool OnCreate(wxDocument* doc, long flags);
 751
 752     /**
 753         If the printing framework is enabled in the library, this function
 754         returns a wxPrintout object for the purposes of printing. It should
 755         create a new object every time it is called; the framework will delete
 756         objects it creates.
 757
 758         By default, this function returns an instance of wxDocPrintout, which
 759         prints and previews one page by calling OnDraw().
 760
 761         Override to return an instance of a class other than wxDocPrintout.
 762     */
 763     virtual wxPrintout* OnCreatePrintout();
 764
 765     /**
 766         Override this function to render the view on the given device context.
 767     */
 768     virtual void OnDraw(wxDC* dc) = 0;
 769
 770     /**
 771         Called when the view should be updated.
 772
 773         @param sender
 774             A pointer to the wxView that sent the update request, or @NULL if
 775             no single view requested the update (for instance, when the
 776             document is opened).
 777         @param hint
 778             This is unused currently, but may in future contain
 779             application-specific information for making updating more
 780             efficient.
 781     */
 782     virtual void OnUpdate(wxView* sender, wxObject* hint = 0);
 783
 784     /**
 785         Associates the given document with the view. Normally called by the
 786         framework.
 787     */
 788     virtual void SetDocument(wxDocument* doc);
 789
 790     /**
 791         Sets the frame associated with this view. The application should call
 792         this if possible, to tell the view about the frame.
 793
 794         See GetFrame() for the explanation about the mismatch between the
 795         "Frame" in the method name and the type of its parameter.
 796     */
 797     void SetFrame(wxWindow* frame);
 798
 799     /**
 800         Sets the view type name. Should only be called by the framework.
 801     */
 802     void SetViewName(const wxString& name);
 803
 804     /**
 805         The document associated with this view. There may be more than one view
 806         per document, but there can never be more than one document for one
 807         view.
 808     */
 809     wxDocument* m_viewDocument;
 810
 811     /**
 812         Frame associated with the view, if any.
 813     */
 814     wxFrame* m_viewFrame;
 815
 816     /**
 817         The view type name given to the wxDocTemplate constructor, copied to
 818         this variable when the view is created. Not currently used by the
 819         framework.
 820     */
 821     wxString m_viewTypeName;
 822 };
 823
 824
 825
 826 /**
 827     @class wxDocChildFrame
 828
 829     The wxDocChildFrame class provides a default frame for displaying documents
 830     on separate windows. This class can only be used for SDI (not MDI) child
 831     frames.
 832
 833     The class is part of the document/view framework supported by wxWidgets,
 834     and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
 835     classes.
 836
 837     @library{wxcore}
 838     @category{docview}
 839
 840     @see @ref overview_docview, @ref page_samples_docview, wxFrame
 841 */
 842 class wxDocChildFrame : public wxFrame
 843 {
 844 public:
 845     /**
 846         Constructor.
 847     */
 848     wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent,
 849                     wxWindowID id, const wxString& title,
 850                     const wxPoint& pos = wxDefaultPosition,
 851                     const wxSize& size = wxDefaultSize,
 852                     long style = wxDEFAULT_FRAME_STYLE,
 853                     const wxString& name = "frame");
 854
 855     /**
 856         Destructor.
 857     */
 858     virtual ~wxDocChildFrame();
 859
 860     /**
 861         Returns the document associated with this frame.
 862     */
 863     wxDocument* GetDocument() const;
 864
 865     /**
 866         Returns the view associated with this frame.
 867     */
 868     wxView* GetView() const;
 869
 870     /**
 871         Sets the currently active view to be the frame's view. You may need to
 872         override (but still call) this function in order to set the keyboard
 873         focus for your subwindow.
 874     */
 875     void OnActivate(wxActivateEvent& event);
 876
 877     /**
 878         Closes and deletes the current view and document.
 879     */
 880     void OnCloseWindow(wxCloseEvent& event);
 881
 882     /**
 883         Sets the document for this frame.
 884     */
 885     void SetDocument(wxDocument* doc);
 886
 887     /**
 888         Sets the view for this frame.
 889     */
 890     void SetView(wxView* view);
 891
 892     /**
 893         The document associated with the frame.
 894     */
 895     wxDocument* m_childDocument;
 896
 897     /**
 898         The view associated with the frame.
 899     */
 900     wxView* m_childView;
 901 };
 902
 903
 904
 905 /**
 906     @class wxDocParentFrame
 907
 908     The wxDocParentFrame class provides a default top-level frame for
 909     applications using the document/view framework. This class can only be used
 910     for SDI (not MDI) parent frames.
 911
 912     It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
 913     classes.
 914
 915     @library{wxcore}
 916     @category{docview}
 917
 918     @see @ref overview_docview, @ref page_samples_docview, wxFrame
 919 */
 920 class wxDocParentFrame : public wxFrame
 921 {
 922 public:
 923     /**
 924         Default constructor.
 925     */
 926     wxDocParentFrame();
 927     /**
 928         Constructor.
 929     */
 930     wxDocParentFrame(wxDocManager* manager, wxFrame* parent,
 931                      wxWindowID id, const wxString& title,
 932                      const wxPoint& pos = wxDefaultPosition,
 933                      const wxSize& size = wxDefaultSize,
 934                      long style = wxDEFAULT_FRAME_STYLE,
 935                      const wxString& name = "frame");
 936
 937     /**
 938         Destructor.
 939     */
 940     virtual ~wxDocParentFrame();
 941
 942     /**
 943         Used in two-step construction.
 944     */
 945     bool Create(wxDocManager* manager, wxFrame* parent, wxWindowID id,
 946                 const wxString& title, const wxPoint& pos = wxDefaultPosition,
 947                 const wxSize& size = wxDefaultSize, long style = 541072960,
 948                 const wxString& name = wxFrameNameStr);
 949
 950     /**
 951         Returns the associated document manager object.
 952     */
 953     wxDocManager* GetDocumentManager() const;
 954
 955     /**
 956         Deletes all views and documents. If no user input cancelled the
 957         operation, the frame will be destroyed and the application will exit.
 958         Since understanding how document/view clean-up takes place can be
 959         difficult, the implementation of this function is shown below:
 960
 961         @code
 962         void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event)
 963         {
 964             if (m_docManager->Clear(!event.CanVeto()))
 965             {
 966                 this->Destroy();
 967             }
 968             else
 969                 event.Veto();
 970         }
 971         @endcode
 972     */
 973     void OnCloseWindow(wxCloseEvent& event);
 974 };
 975
 976
 977
 978 /**
 979     @class wxDocument
 980
 981     The document class can be used to model an application's file-based data.
 982     It is part of the document/view framework supported by wxWidgets, and
 983     cooperates with the wxView, wxDocTemplate and wxDocManager classes.
 984
 985     @library{wxcore}
 986     @category{docview}
 987
 988     @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager
 989 */
 990 class wxDocument : public wxEvtHandler
 991 {
 992 public:
 993     /**
 994         Constructor. Define your own default constructor to initialize
 995         application-specific data.
 996     */
 997     wxDocument(wxDocument* parent = 0);
 998
 999     /**
1000         Destructor. Removes itself from the document manager.
1001     */
1002     virtual ~wxDocument();
1003
1004     /**
1005         If the view is not already in the list of views, adds the view and
1006         calls OnChangedViewList().
1007     */
1008     virtual bool AddView(wxView* view);
1009
1010     /**
1011         Closes the document, by calling OnSaveModified() and then (if this
1012         returned @true) OnCloseDocument(). This does not normally delete the
1013         document object, use DeleteAllViews() to do this implicitly.
1014     */
1015     virtual bool Close();
1016
1017     /**
1018         Calls wxView::Close() and deletes each view. Deleting the final view
1019         will implicitly delete the document itself, because the wxView
1020         destructor calls RemoveView(). This in turns calls OnChangedViewList(),
1021         whose default implemention is to save and delete the document if no
1022         views exist.
1023     */
1024     virtual bool DeleteAllViews();
1025
1026     /**
1027         Returns a pointer to the command processor associated with this
1028         document.
1029
1030         @see wxCommandProcessor
1031     */
1032     virtual wxCommandProcessor* GetCommandProcessor() const;
1033
1034     /**
1035         Gets a pointer to the associated document manager.
1036     */
1037     virtual wxDocManager* GetDocumentManager() const;
1038
1039     /**
1040         Gets the document type name for this document. See the comment for
1041         @ref m_documentTypeName.
1042     */
1043     wxString GetDocumentName() const;
1044
1045     /**
1046         Gets a pointer to the template that created the document.
1047     */
1048     virtual wxDocTemplate* GetDocumentTemplate() const;
1049
1050     /**
1051         Intended to return a suitable window for using as a parent for
1052         document-related dialog boxes. By default, uses the frame associated
1053         with the first view.
1054     */
1055     virtual wxWindow* GetDocumentWindow() const;
1056
1057     /**
1058         Gets the filename associated with this document, or "" if none is
1059         associated.
1060     */
1061     wxString GetFilename() const;
1062
1063     /**
1064         A convenience function to get the first view for a document, because in
1065         many cases a document will only have a single view.
1066
1067         @see GetViews()
1068     */
1069     wxView* GetFirstView() const;
1070
1071     /**
1072         Gets the title for this document. The document title is used for an
1073         associated frame (if any), and is usually constructed by the framework
1074         from the filename.
1075     */
1076     wxString GetTitle() const;
1077
1078     /**
1079         Return the document name suitable to be shown to the user. The default
1080         implementation uses the document title, if any, of the name part of the
1081         document filename if it was set or, otherwise, the string @b unnamed.
1082     */
1083     virtual wxString GetUserReadableName() const;
1084
1085     /**
1086         Returns the list whose elements are the views on the document.
1087
1088         @see GetFirstView()
1089     */
1090     wxList GetViews() const;
1091
1092     /**
1093         Returns @true if the document has been modified since the last save,
1094         @false otherwise. You may need to override this if your document view
1095         maintains its own record of being modified.
1096
1097         @see Modify()
1098     */
1099     virtual bool IsModified() const;
1100
1101     //@{
1102     /**
1103         Override this function and call it from your own LoadObject() before
1104         streaming your own data. LoadObject() is called by the framework
1105         automatically when the document contents need to be loaded.
1106
1107         @note This version of LoadObject() may not exist depending on how
1108               wxWidgets was configured.
1109     */
1110     virtual istream& LoadObject(istream& stream);
1111     virtual wxInputStream& LoadObject(wxInputStream& stream);
1112     //@}
1113
1114     /**
1115         Call with @true to mark the document as modified since the last save,
1116         @false otherwise. You may need to override this if your document view
1117         maintains its own record of being modified.
1118
1119         @see IsModified()
1120     */
1121     virtual void Modify(bool modify);
1122
1123     /**
1124         Called when a view is added to or deleted from this document. The
1125         default implementation saves and deletes the document if no views exist
1126         (the last one has just been removed).
1127     */
1128     virtual void OnChangedViewList();
1129
1130     /**
1131         This virtual function is called when the document is being closed.
1132
1133         The default implementation calls DeleteContents() (an empty
1134         implementation) and sets the modified flag to @false. You can override
1135         it to supply additional behaviour when the document is closed with
1136         Close().
1137
1138         Notice that previous wxWidgets versions used to call this function also
1139         from OnNewDocument(), rather counter-intuitively. This is no longer the
1140         case since wxWidgets 2.9.0.
1141     */
1142     virtual bool OnCloseDocument();
1143
1144     /**
1145         Called just after the document object is created to give it a chance to
1146         initialize itself. The default implementation uses the template
1147         associated with the document to create an initial view. If this
1148         function returns @false, the document is deleted.
1149     */
1150     virtual bool OnCreate(const wxString& path, long flags);
1151
1152     /**
1153         Override this function if you want a different (or no) command
1154         processor to be created when the document is created. By default, it
1155         returns an instance of wxCommandProcessor.
1156
1157         @see wxCommandProcessor
1158     */
1159     virtual wxCommandProcessor* OnCreateCommandProcessor();
1160
1161     /**
1162         The default implementation calls OnSaveModified() and DeleteContents(),
1163         makes a default title for the document, and notifies the views that the
1164         filename (in fact, the title) has changed.
1165     */
1166     virtual bool OnNewDocument();
1167
1168     /**
1169         Constructs an input file stream for the given filename (which must not
1170         be empty), and calls LoadObject(). If LoadObject() returns @true, the
1171         document is set to unmodified; otherwise, an error message box is
1172         displayed. The document's views are notified that the filename has
1173         changed, to give windows an opportunity to update their titles. All of
1174         the document's views are then updated.
1175     */
1176     virtual bool OnOpenDocument(const wxString& filename);
1177
1178     /**
1179         Constructs an output file stream for the given filename (which must not
1180         be empty), and calls SaveObject(). If SaveObject() returns @true, the
1181         document is set to unmodified; otherwise, an error message box is
1182         displayed.
1183     */
1184     virtual bool OnSaveDocument(const wxString& filename);
1185
1186     /**
1187         If the document has been modified, prompts the user to ask if the
1188         changes should be changed. If the user replies Yes, the Save() function
1189         is called. If No, the document is marked as unmodified and the function
1190         succeeds. If Cancel, the function fails.
1191     */
1192     virtual bool OnSaveModified();
1193
1194     /**
1195         Removes the view from the document's list of views, and calls
1196         OnChangedViewList().
1197     */
1198     virtual bool RemoveView(wxView* view);
1199
1200     /**
1201         Saves the document by calling OnSaveDocument() if there is an
1202         associated filename, or SaveAs() if there is no filename.
1203     */
1204     virtual bool Save();
1205
1206     /**
1207         Prompts the user for a file to save to, and then calls
1208         OnSaveDocument().
1209     */
1210     virtual bool SaveAs();
1211
1212     //@{
1213     /**
1214         Override this function and call it from your own SaveObject() before
1215         streaming your own data. SaveObject() is called by the framework
1216         automatically when the document contents need to be saved.
1217
1218         @note This version of SaveObject() may not exist depending on how
1219               wxWidgets was configured.
1220     */
1221     virtual ostream& SaveObject(ostream& stream);
1222     virtual wxOutputStream& SaveObject(wxOutputStream& stream);
1223     //@}
1224
1225     /**
1226         Sets the command processor to be used for this document. The document
1227         will then be responsible for its deletion. Normally you should not call
1228         this; override OnCreateCommandProcessor() instead.
1229
1230         @see wxCommandProcessor
1231     */
1232     virtual void SetCommandProcessor(wxCommandProcessor* processor);
1233
1234     /**
1235         Sets the document type name for this document. See the comment for
1236         @ref m_documentTypeName.
1237     */
1238     void SetDocumentName(const wxString& name);
1239
1240     /**
1241         Sets the pointer to the template that created the document. Should only
1242         be called by the framework.
1243     */
1244     virtual void SetDocumentTemplate(wxDocTemplate* templ);
1245
1246     /**
1247         Sets the filename for this document. Usually called by the framework.
1248
1249         If @a notifyViews is @true, wxView::OnChangeFilename() is called for
1250         all views.
1251     */
1252     void SetFilename(const wxString& filename, bool notifyViews = false);
1253
1254     /**
1255         Sets the title for this document. The document title is used for an
1256         associated frame (if any), and is usually constructed by the framework
1257         from the filename.
1258     */
1259     void SetTitle(const wxString& title);
1260
1261     /**
1262         Updates all views. If @a sender is non-@NULL, does not update this
1263         view. @a hint represents optional information to allow a view to
1264         optimize its update.
1265     */
1266     virtual void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL);
1267
1268 protected:
1269     /**
1270         This method is called by OnSaveDocument() to really save the document
1271         contents to the specified file.
1272
1273         Base class version creates a file-based stream and calls SaveObject().
1274         Override this if you need to do something else or prefer not to use
1275         SaveObject() at all.
1276      */
1277     virtual bool DoSaveDocument(const wxString& file);
1278
1279     /**
1280         This method is called by OnOpenDocument() to really load the document
1281         contents from the specified file.
1282
1283         Base class version creates a file-based stream and calls LoadObject().
1284         Override this if you need to do something else or prefer not to use
1285         LoadObject() at all.
1286      */
1287     virtual bool DoOpenDocument(const wxString& file);
1288
1289     /**
1290         A pointer to the command processor associated with this document.
1291     */
1292     wxCommandProcessor* m_commandProcessor;
1293
1294     /**
1295         Filename associated with this document ("" if none).
1296     */
1297     wxString m_documentFile;
1298
1299     /**
1300         @true if the document has been modified, @false otherwise.
1301     */
1302     bool m_documentModified;
1303
1304     /**
1305         A pointer to the template from which this document was created.
1306     */
1307     wxDocTemplate* m_documentTemplate;
1308
1309     /**
1310         Document title. The document title is used for an associated frame (if
1311         any), and is usually constructed by the framework from the filename.
1312     */
1313     wxString m_documentTitle;
1314
1315     /**
1316         The document type name given to the wxDocTemplate constructor, copied
1317         to this variable when the document is created. If several document
1318         templates are created that use the same document type, this variable is
1319         used in wxDocManager::CreateView() to collate a list of alternative
1320         view types that can be used on this kind of document. Do not change the
1321         value of this variable.
1322     */
1323     wxString m_documentTypeName;
1324
1325     /**
1326         List of wxView instances associated with this document.
1327     */
1328     wxList m_documentViews;
1329 };
1330
1331
1332
1333 /**
1334     @class wxFileHistory
1335
1336     The wxFileHistory encapsulates a user interface convenience, the list of
1337     most recently visited files as shown on a menu (usually the File menu).
1338
1339     wxFileHistory can manage one or more file menus. More than one menu may be
1340     required in an MDI application, where the file history should appear on
1341     each MDI child menu as well as the MDI parent frame.
1342
1343     @library{wxcore}
1344     @category{docview}
1345
1346     @see @ref overview_docview, wxDocManager
1347 */
1348 class wxFileHistory : public wxObject
1349 {
1350 public:
1351     /**
1352         Constructor. Pass the maximum number of files that should be stored and
1353         displayed.
1354
1355         @a idBase defaults to wxID_FILE1 and represents the id given to the
1356         first history menu item. Since menu items can't share the same ID you
1357         should change @a idBase (to one of your own defined IDs) when using
1358         more than one wxFileHistory in your application.
1359     */
1360     wxFileHistory(size_t maxFiles = 9, wxWindowID idBase = wxID_FILE1);
1361
1362     /**
1363         Destructor.
1364     */
1365     virtual ~wxFileHistory();
1366
1367     /**
1368         Adds a file to the file history list, if the object has a pointer to an
1369         appropriate file menu.
1370     */
1371     virtual void AddFileToHistory(const wxString& filename);
1372
1373     /**
1374         Appends the files in the history list, to all menus managed by the file
1375         history object.
1376     */
1377     virtual void AddFilesToMenu();
1378     /**
1379         Appends the files in the history list, to the given menu only.
1380     */
1381     virtual void AddFilesToMenu(wxMenu* menu);
1382
1383     /**
1384         Returns the base identifier for the range used for appending items.
1385     */
1386     wxWindowID GetBaseId() const;
1387
1388     /**
1389         Returns the number of files currently stored in the file history.
1390     */
1391     virtual size_t GetCount() const;
1392
1393     /**
1394         Returns the file at this index (zero-based).
1395     */
1396     virtual wxString GetHistoryFile(size_t index) const;
1397
1398     /**
1399         Returns the maximum number of files that can be stored.
1400     */
1401     virtual int GetMaxFiles() const;
1402
1403     /**
1404         Returns the list of menus that are managed by this file history object.
1405
1406         @see UseMenu()
1407     */
1408     const wxList& GetMenus() const;
1409
1410     /**
1411         Loads the file history from the given config object. This function
1412         should be called explicitly by the application.
1413
1414         @see wxConfigBase
1415     */
1416     virtual void Load(const wxConfigBase& config);
1417
1418     /**
1419         Removes the specified file from the history.
1420     */
1421     virtual void RemoveFileFromHistory(size_t i);
1422
1423     /**
1424         Removes this menu from the list of those managed by this object.
1425     */
1426     virtual void RemoveMenu(wxMenu* menu);
1427
1428     /**
1429         Saves the file history into the given config object. This must be
1430         called explicitly by the application.
1431
1432         @see wxConfigBase
1433     */
1434     virtual void Save(wxConfigBase& config);
1435
1436     /**
1437         Sets the base identifier for the range used for appending items.
1438     */
1439     void SetBaseId(wxWindowID baseId);
1440
1441     /**
1442         Adds this menu to the list of those menus that are managed by this file
1443         history object. Also see AddFilesToMenu() for initializing the menu
1444         with filenames that are already in the history when this function is
1445         called, as this is not done automatically.
1446     */
1447     virtual void UseMenu(wxMenu* menu);
1448
1449     /**
1450         A character array of strings corresponding to the most recently opened
1451         files.
1452     */
1453     char** m_fileHistory;
1454
1455     /**
1456         The number of files stored in the history array.
1457     */
1458     size_t m_fileHistoryN;
1459
1460     /**
1461         The maximum number of files to be stored and displayed on the menu.
1462     */
1463     size_t m_fileMaxFiles;
1464
1465     /**
1466         The file menu used to display the file history list (if enabled).
1467     */
1468     wxMenu* m_fileMenu;
1469 };
1470
1471
1472
1473 // ============================================================================
1474 // Global functions/macros
1475 // ============================================================================
1476
1477 /** @ingroup group_funcmacro_file */
1478 //@{
1479
1480 /**
1481     Copies the given file to @a stream. Useful when converting an old
1482     application to use streams (within the document/view framework, for
1483     example).
1484
1485     @header{wx/docview.h}
1486 */
1487 bool wxTransferFileToStream(const wxString& filename,
1488                             ostream& stream);
1489
1490 /**
1491     Copies the given stream to the file @a filename. Useful when converting an
1492     old application to use streams (within the document/view framework, for
1493     example).
1494
1495     @header{wx/docview.h}
1496 */
1497 bool wxTransferStreamToFile(istream& stream,
1498                              const wxString& filename);
1499
1500 //@}
1501