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