interface/wx/docview.h

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