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