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