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