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