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