interface/wx/docview.h

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