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