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         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     ~wxDocManager();
 278
 279     /**
 280         Sets the current view.
 281     */
 282     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     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     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     wxView* CreateView(wxDocument* doc, long flags);
 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     void FileHistoryAddFilesToMenu();
 360     /**
 361         Appends the files in the history list to the given @a menu only.
 362     */
 363     void FileHistoryAddFilesToMenu(wxMenu* menu);
 364
 365     /**
 366         Loads the file history from a config object.
 367
 368         @see wxConfigBase
 369     */
 370     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     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     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     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     wxDocTemplate* FindTemplateForPath(const wxString& path);
 402
 403     /**
 404         Returns the document associated with the currently active view (if
 405         any).
 406     */
 407     wxDocument* GetCurrentDocument();
 408
 409     /**
 410         Returns the currently active view
 411     */
 412     wxView* GetCurrentView();
 413
 414     /**
 415         Returns a reference to the list of documents.
 416     */
 417     wxList GetDocuments();
 418
 419     /**
 420         Returns a pointer to file history.
 421     */
 422     wxFileHistory* GetFileHistory();
 423
 424     /**
 425         Returns the number of files currently stored in the file history.
 426     */
 427     size_t GetHistoryFilesCount();
 428
 429     /**
 430         Returns the directory last selected by the user when opening a file.
 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();
 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     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     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     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     wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates,
 531                                       int noTemplates, wxString& path,
 532                                       long flags, bool save);
 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     ~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();
 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);
 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);
 775
 776     /**
 777         Associates the given document with the view. Normally called by the
 778         framework.
 779     */
 780     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     ~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     ~wxDocParentFrame();
 933
 934     /**
 935         Used in two-step construction.
 936     */
 937     bool Create(wxDocManager* manager, wxFrame* parent,
 938                 wxWindowID id, const wxString& title,
 939                 const wxPoint& pos = wxDefaultPosition,
 940                 const wxSize& size = wxDefaultSize,
 941                 long style = wxDEFAULT_FRAME_STYLE,
 942                 const wxString& name = "frame");
 943
 944     /**
 945         Returns the associated document manager object.
 946     */
 947     wxDocManager* GetDocumentManager() const;
 948
 949     /**
 950         Deletes all views and documents. If no user input cancelled the
 951         operation, the frame will be destroyed and the application will exit.
 952         Since understanding how document/view clean-up takes place can be
 953         difficult, the implementation of this function is shown below:
 954
 955         @code
 956         void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event)
 957         {
 958             if (m_docManager->Clear(!event.CanVeto()))
 959             {
 960                 this->Destroy();
 961             }
 962             else
 963                 event.Veto();
 964         }
 965         @endcode
 966     */
 967     void OnCloseWindow(wxCloseEvent& event);
 968 };
 969
 970
 971
 972 /**
 973     @class wxDocument
 974
 975     The document class can be used to model an application's file-based data.
 976     It is part of the document/view framework supported by wxWidgets, and
 977     cooperates with the wxView, wxDocTemplate and wxDocManager classes.
 978
 979     @library{wxcore}
 980     @category{docview}
 981
 982     @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager
 983 */
 984 class wxDocument : public wxEvtHandler
 985 {
 986 public:
 987     /**
 988         Constructor. Define your own default constructor to initialize
 989         application-specific data.
 990     */
 991     wxDocument();
 992
 993     /**
 994         Destructor. Removes itself from the document manager.
 995     */
 996     ~wxDocument();
 997
 998     /**
 999         If the view is not already in the list of views, adds the view and
1000         calls OnChangedViewList().
1001     */
1002     virtual bool AddView(wxView* view);
1003
1004     /**
1005         Closes the document, by calling OnSaveModified() and then (if this
1006         returned @true) OnCloseDocument(). This does not normally delete the
1007         document object, use DeleteAllViews() to do this implicitly.
1008     */
1009     virtual bool Close();
1010
1011     /**
1012         Calls wxView::Close() and deletes each view. Deleting the final view
1013         will implicitly delete the document itself, because the wxView
1014         destructor calls RemoveView(). This in turns calls OnChangedViewList(),
1015         whose default implemention is to save and delete the document if no
1016         views exist.
1017     */
1018     virtual bool DeleteAllViews();
1019
1020     /**
1021         Returns a pointer to the command processor associated with this
1022         document.
1023
1024         @see wxCommandProcessor
1025     */
1026     wxCommandProcessor* GetCommandProcessor() const;
1027
1028     /**
1029         Gets a pointer to the associated document manager.
1030     */
1031     wxDocManager* GetDocumentManager() const;
1032
1033     /**
1034         Gets the document type name for this document. See the comment for
1035         @ref m_documentTypeName.
1036     */
1037     wxString GetDocumentName() const;
1038
1039     /**
1040         Gets a pointer to the template that created the document.
1041     */
1042     wxDocTemplate* GetDocumentTemplate() const;
1043
1044     /**
1045         Intended to return a suitable window for using as a parent for
1046         document-related dialog boxes. By default, uses the frame associated
1047         with the first view.
1048     */
1049     wxWindow* GetDocumentWindow() const;
1050
1051     /**
1052         Gets the filename associated with this document, or "" if none is
1053         associated.
1054     */
1055     wxString GetFilename() const;
1056
1057     /**
1058         A convenience function to get the first view for a document, because in
1059         many cases a document will only have a single view.
1060
1061         @see GetViews()
1062     */
1063     wxView* GetFirstView() const;
1064
1065     /**
1066         Gets the title for this document. The document title is used for an
1067         associated frame (if any), and is usually constructed by the framework
1068         from the filename.
1069     */
1070     wxString GetTitle() const;
1071
1072     /**
1073         Return the document name suitable to be shown to the user. The default
1074         implementation uses the document title, if any, of the name part of the
1075         document filename if it was set or, otherwise, the string @b unnamed.
1076     */
1077     virtual wxString GetUserReadableName() const;
1078
1079     /**
1080         Returns the list whose elements are the views on the document.
1081
1082         @see GetFirstView()
1083     */
1084     wxList GetViews() const;
1085
1086     /**
1087         Returns @true if the document has been modified since the last save,
1088         @false otherwise. You may need to override this if your document view
1089         maintains its own record of being modified.
1090
1091         @see Modify()
1092     */
1093     virtual bool IsModified() const;
1094
1095     //@{
1096     /**
1097         Override this function and call it from your own LoadObject() before
1098         streaming your own data. LoadObject() is called by the framework
1099         automatically when the document contents need to be loaded.
1100
1101         @note This version of LoadObject() may not exist depending on how
1102               wxWidgets was configured.
1103     */
1104     virtual istream& LoadObject(istream& stream);
1105     virtual wxInputStream& LoadObject(wxInputStream& stream);
1106     //@}
1107
1108     /**
1109         Call with @true to mark the document as modified since the last save,
1110         @false otherwise. You may need to override this if your document view
1111         maintains its own record of being modified.
1112
1113         @see IsModified()
1114     */
1115     virtual void Modify(bool modify);
1116
1117     /**
1118         Called when a view is added to or deleted from this document. The
1119         default implementation saves and deletes the document if no views exist
1120         (the last one has just been removed).
1121     */
1122     virtual void OnChangedViewList();
1123
1124     /**
1125         This virtual function is called when the document is being closed.
1126
1127         The default implementation calls DeleteContents() (an empty
1128         implementation) and sets the modified flag to @false. You can override
1129         it to supply additional behaviour when the document is closed with
1130         Close().
1131
1132         Notice that previous wxWidgets versions used to call this function also
1133         from OnNewDocument(), rather counter-intuitively. This is no longer the
1134         case since wxWidgets 2.9.0.
1135     */
1136     virtual bool OnCloseDocument();
1137
1138     /**
1139         Called just after the document object is created to give it a chance to
1140         initialize itself. The default implementation uses the template
1141         associated with the document to create an initial view. If this
1142         function returns @false, the document is deleted.
1143     */
1144     virtual bool OnCreate(const wxString& path, long flags);
1145
1146     /**
1147         Override this function if you want a different (or no) command
1148         processor to be created when the document is created. By default, it
1149         returns an instance of wxCommandProcessor.
1150
1151         @see wxCommandProcessor
1152     */
1153     virtual wxCommandProcessor* OnCreateCommandProcessor();
1154
1155     /**
1156         The default implementation calls OnSaveModified() and DeleteContents(),
1157         makes a default title for the document, and notifies the views that the
1158         filename (in fact, the title) has changed.
1159     */
1160     virtual bool OnNewDocument();
1161
1162     /**
1163         Constructs an input file stream for the given filename (which must not
1164         be empty), and calls LoadObject(). If LoadObject() returns @true, the
1165         document is set to unmodified; otherwise, an error message box is
1166         displayed. The document's views are notified that the filename has
1167         changed, to give windows an opportunity to update their titles. All of
1168         the document's views are then updated.
1169     */
1170     virtual bool OnOpenDocument(const wxString& filename);
1171
1172     /**
1173         Constructs an output file stream for the given filename (which must not
1174         be empty), and calls SaveObject(). If SaveObject() returns @true, the
1175         document is set to unmodified; otherwise, an error message box is
1176         displayed.
1177     */
1178     virtual bool OnSaveDocument(const wxString& filename);
1179
1180     /**
1181         If the document has been modified, prompts the user to ask if the
1182         changes should be changed. If the user replies Yes, the Save() function
1183         is called. If No, the document is marked as unmodified and the function
1184         succeeds. If Cancel, the function fails.
1185     */
1186     virtual bool OnSaveModified();
1187
1188     /**
1189         Removes the view from the document's list of views, and calls
1190         OnChangedViewList().
1191     */
1192     virtual bool RemoveView(wxView* view);
1193
1194     /**
1195         Saves the document by calling OnSaveDocument() if there is an
1196         associated filename, or SaveAs() if there is no filename.
1197     */
1198     virtual bool Save();
1199
1200     /**
1201         Prompts the user for a file to save to, and then calls
1202         OnSaveDocument().
1203     */
1204     virtual bool SaveAs();
1205
1206     //@{
1207     /**
1208         Override this function and call it from your own SaveObject() before
1209         streaming your own data. SaveObject() is called by the framework
1210         automatically when the document contents need to be saved.
1211
1212         @note This version of SaveObject() may not exist depending on how
1213               wxWidgets was configured.
1214     */
1215     virtual ostream& SaveObject(ostream& stream);
1216     virtual wxOutputStream& SaveObject(wxOutputStream& stream);
1217     //@}
1218
1219     /**
1220         Sets the command processor to be used for this document. The document
1221         will then be responsible for its deletion. Normally you should not call
1222         this; override OnCreateCommandProcessor() instead.
1223
1224         @see wxCommandProcessor
1225     */
1226     virtual void SetCommandProcessor(wxCommandProcessor* processor);
1227
1228     /**
1229         Sets the document type name for this document. See the comment for
1230         @ref m_documentTypeName.
1231     */
1232     void SetDocumentName(const wxString& name);
1233
1234     /**
1235         Sets the pointer to the template that created the document. Should only
1236         be called by the framework.
1237     */
1238     void SetDocumentTemplate(wxDocTemplate* templ);
1239
1240     /**
1241         Sets the filename for this document. Usually called by the framework.
1242
1243         If @a notifyViews is @true, wxView::OnChangeFilename() is called for
1244         all views.
1245     */
1246     void SetFilename(const wxString& filename, bool notifyViews = false);
1247
1248     /**
1249         Sets the title for this document. The document title is used for an
1250         associated frame (if any), and is usually constructed by the framework
1251         from the filename.
1252     */
1253     void SetTitle(const wxString& title);
1254
1255     /**
1256         Updates all views. If @a sender is non-@NULL, does not update this
1257         view. @a hint represents optional information to allow a view to
1258         optimize its update.
1259     */
1260     void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL);
1261
1262 protected:
1263     /**
1264         This method is called by OnSaveDocument() to really save the document
1265         contents to the specified file.
1266
1267         Base class version creates a file-based stream and calls SaveObject().
1268         Override this if you need to do something else or prefer not to use
1269         SaveObject() at all.
1270      */
1271     virtual bool DoSaveDocument(const wxString& file);
1272
1273     /**
1274         This method is called by OnOpenDocument() to really load the document
1275         contents from the specified file.
1276
1277         Base class version creates a file-based stream and calls LoadObject().
1278         Override this if you need to do something else or prefer not to use
1279         LoadObject() at all.
1280      */
1281     virtual bool DoOpenDocument(const wxString& file);
1282
1283     /**
1284         A pointer to the command processor associated with this document.
1285     */
1286     wxCommandProcessor* m_commandProcessor;
1287
1288     /**
1289         Filename associated with this document ("" if none).
1290     */
1291     wxString m_documentFile;
1292
1293     /**
1294         @true if the document has been modified, @false otherwise.
1295     */
1296     bool m_documentModified;
1297
1298     /**
1299         A pointer to the template from which this document was created.
1300     */
1301     wxDocTemplate* m_documentTemplate;
1302
1303     /**
1304         Document title. The document title is used for an associated frame (if
1305         any), and is usually constructed by the framework from the filename.
1306     */
1307     wxString m_documentTitle;
1308
1309     /**
1310         The document type name given to the wxDocTemplate constructor, copied
1311         to this variable when the document is created. If several document
1312         templates are created that use the same document type, this variable is
1313         used in wxDocManager::CreateView() to collate a list of alternative
1314         view types that can be used on this kind of document. Do not change the
1315         value of this variable.
1316     */
1317     wxString m_documentTypeName;
1318
1319     /**
1320         List of wxView instances associated with this document.
1321     */
1322     wxList m_documentViews;
1323 };
1324
1325
1326
1327 /**
1328     @class wxFileHistory
1329
1330     The wxFileHistory encapsulates a user interface convenience, the list of
1331     most recently visited files as shown on a menu (usually the File menu).
1332
1333     wxFileHistory can manage one or more file menus. More than one menu may be
1334     required in an MDI application, where the file history should appear on
1335     each MDI child menu as well as the MDI parent frame.
1336
1337     @library{wxcore}
1338     @category{docview}
1339
1340     @see @ref overview_docview, wxDocManager
1341 */
1342 class wxFileHistory : public wxObject
1343 {
1344 public:
1345     /**
1346         Constructor. Pass the maximum number of files that should be stored and
1347         displayed.
1348
1349         @a idBase defaults to wxID_FILE1 and represents the id given to the
1350         first history menu item. Since menu items can't share the same ID you
1351         should change @a idBase (to one of your own defined IDs) when using
1352         more than one wxFileHistory in your application.
1353     */
1354     wxFileHistory(size_t maxFiles = 9, wxWindowID idBase = wxID_FILE1);
1355
1356     /**
1357         Destructor.
1358     */
1359     ~wxFileHistory();
1360
1361     /**
1362         Adds a file to the file history list, if the object has a pointer to an
1363         appropriate file menu.
1364     */
1365     void AddFileToHistory(const wxString& filename);
1366
1367     /**
1368         Appends the files in the history list, to all menus managed by the file
1369         history object.
1370     */
1371     void AddFilesToMenu();
1372     /**
1373         Appends the files in the history list, to the given menu only.
1374     */
1375     void AddFilesToMenu(wxMenu* menu);
1376
1377     /**
1378         Returns the base identifier for the range used for appending items.
1379     */
1380     wxWindowID GetBaseId() const;
1381
1382     /**
1383         Returns the number of files currently stored in the file history.
1384     */
1385     size_t GetCount() const;
1386
1387     /**
1388         Returns the file at this index (zero-based).
1389     */
1390     wxString GetHistoryFile(size_t index) const;
1391
1392     /**
1393         Returns the maximum number of files that can be stored.
1394     */
1395     int GetMaxFiles() const;
1396
1397     /**
1398         Returns the list of menus that are managed by this file history object.
1399
1400         @see UseMenu()
1401     */
1402     const wxList& GetMenus() const;
1403
1404     /**
1405         Loads the file history from the given config object. This function
1406         should be called explicitly by the application.
1407
1408         @see wxConfigBase
1409     */
1410     void Load(const wxConfigBase& config);
1411
1412     /**
1413         Removes the specified file from the history.
1414     */
1415     void RemoveFileFromHistory(size_t i);
1416
1417     /**
1418         Removes this menu from the list of those managed by this object.
1419     */
1420     void RemoveMenu(wxMenu* menu);
1421
1422     /**
1423         Saves the file history into the given config object. This must be
1424         called explicitly by the application.
1425
1426         @see wxConfigBase
1427     */
1428     void Save(wxConfigBase& config);
1429
1430     /**
1431         Sets the base identifier for the range used for appending items.
1432     */
1433     void SetBaseId(wxWindowID baseId);
1434
1435     /**
1436         Adds this menu to the list of those menus that are managed by this file
1437         history object. Also see AddFilesToMenu() for initializing the menu
1438         with filenames that are already in the history when this function is
1439         called, as this is not done automatically.
1440     */
1441     void UseMenu(wxMenu* menu);
1442
1443     /**
1444         A character array of strings corresponding to the most recently opened
1445         files.
1446     */
1447     char** m_fileHistory;
1448
1449     /**
1450         The number of files stored in the history array.
1451     */
1452     size_t m_fileHistoryN;
1453
1454     /**
1455         The maximum number of files to be stored and displayed on the menu.
1456     */
1457     size_t m_fileMaxFiles;
1458
1459     /**
1460         The file menu used to display the file history list (if enabled).
1461     */
1462     wxMenu* m_fileMenu;
1463 };
1464
1465
1466
1467 // ============================================================================
1468 // Global functions/macros
1469 // ============================================================================
1470
1471 /** @ingroup group_funcmacro_file */
1472 //@{
1473
1474 /**
1475     Copies the given file to @a stream. Useful when converting an old
1476     application to use streams (within the document/view framework, for
1477     example).
1478
1479     @header{wx/docview.h}
1480 */
1481 bool wxTransferFileToStream(const wxString& filename,
1482                             ostream& stream);
1483
1484 /**
1485     Copies the given stream to the file @a filename. Useful when converting an
1486     old application to use streams (within the document/view framework, for
1487     example).
1488
1489     @header{wx/docview.h}
1490 */
1491 bool wxTransferStreamToFile(istream& stream,
1492                              const wxString& filename);
1493
1494 //@}
1495