interface/docview.h

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