include/wx/propgrid/manager.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/propgrid/manager.h
   3 // Purpose:     wxPropertyGridManager
   4 // Author:      Jaakko Salli
   5 // Modified by:
   6 // Created:     2005-01-14
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Jaakko Salli
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_PROPGRID_MANAGER_H_
  13 #define _WX_PROPGRID_MANAGER_H_
  14
  15 #if wxUSE_PROPGRID
  16
  17 #include "wx/propgrid/propgrid.h"
  18
  19 #include "wx/dcclient.h"
  20 #include "wx/scrolwin.h"
  21 #include "wx/toolbar.h"
  22 #include "wx/stattext.h"
  23 #include "wx/button.h"
  24 #include "wx/textctrl.h"
  25 #include "wx/dialog.h"
  26
  27 // -----------------------------------------------------------------------
  28
  29 #ifndef SWIG
  30 extern WXDLLIMPEXP_DATA_PROPGRID(const char) wxPropertyGridManagerNameStr[];
  31 #endif
  32
  33 /** @class wxPropertyGridPage
  34
  35     Holder of property grid page information. You can subclass this and
  36     give instance in wxPropertyGridManager::AddPage. It inherits from
  37     wxEvtHandler and can be used to process events specific to this
  38     page (id of events will still be same as manager's). If you don't
  39     want to use it to process all events of the page, you need to
  40     return false in the derived wxPropertyGridPage::IsHandlingAllEvents.
  41
  42     Please note that wxPropertyGridPage lacks many non-const property
  43     manipulation functions found in wxPropertyGridManager. Please use
  44     parent manager (m_manager member variable) when needed.
  45
  46     Please note that most member functions are inherited and as such not
  47     documented on this page. This means you will probably also want to read
  48     wxPropertyGridInterface class reference.
  49
  50     @section propgridpage_event_handling Event Handling
  51
  52     wxPropertyGridPage receives events emitted by its wxPropertyGridManager, but
  53     only those events that are specific to that page. If
  54     wxPropertyGridPage::IsHandlingAllEvents returns false, then unhandled
  55     events are sent to the manager's parent, as usual.
  56
  57     See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
  58     for more information.
  59
  60     @library{wxpropgrid}
  61     @category{propgrid}
  62 */
  63 class WXDLLIMPEXP_PROPGRID wxPropertyGridPage : public wxEvtHandler,
  64                                                 public wxPropertyGridInterface,
  65                                                 public wxPropertyGridPageState
  66 {
  67     friend class wxPropertyGridManager;
  68     DECLARE_CLASS(wxPropertyGridPage)
  69 public:
  70
  71     wxPropertyGridPage();
  72     virtual ~wxPropertyGridPage();
  73
  74     /** Deletes all properties on page.
  75     */
  76     virtual void Clear();
  77
  78     /**
  79         Reduces column sizes to minimum possible that contents are still
  80         visibly (naturally some margin space will be applied as well).
  81
  82         @return
  83         Minimum size for the page to still display everything.
  84
  85         @remarks
  86         This function only works properly if size of containing grid was
  87         already fairly large.
  88
  89         Note that you can also get calculated column widths by calling
  90         GetColumnWidth() immediately after this function returns.
  91     */
  92     wxSize FitColumns();
  93
  94     /** Returns page index in manager;
  95     */
  96     inline int GetIndex() const;
  97
  98     /** Returns x-coordinate position of splitter on a page.
  99     */
 100     int GetSplitterPosition( int col = 0 ) const
 101         { return GetStatePtr()->DoGetSplitterPosition(col); }
 102
 103     /** Returns "root property". It does not have name, etc. and it is not
 104         visible. It is only useful for accessing its children.
 105     */
 106     wxPGProperty* GetRoot() const { return GetStatePtr()->DoGetRoot(); }
 107
 108     /** Return pointer to contained property grid state.
 109     */
 110     wxPropertyGridPageState* GetStatePtr()
 111     {
 112         return this;
 113     }
 114
 115     /** Return pointer to contained property grid state.
 116     */
 117     const wxPropertyGridPageState* GetStatePtr() const
 118     {
 119         return this;
 120     }
 121
 122     /**
 123         Returns id of the tool bar item that represents this page on
 124         wxPropertyGridManager's wxToolBar.
 125     */
 126     int GetToolId() const
 127     {
 128         return m_id;
 129     }
 130
 131     /** Do any member initialization in this method.
 132         @remarks
 133         - Called every time the page is added into a manager.
 134         - You can add properties to the page here.
 135     */
 136     virtual void Init() {}
 137
 138     /** Return false here to indicate unhandled events should be
 139         propagated to manager's parent, as normal.
 140     */
 141     virtual bool IsHandlingAllEvents() const { return true; }
 142
 143     /** Called every time page is about to be shown.
 144         Useful, for instance, creating properties just-in-time.
 145     */
 146     virtual void OnShow();
 147
 148     virtual void RefreshProperty( wxPGProperty* p );
 149
 150     /** Sets splitter position on page.
 151         @remarks
 152         Splitter position cannot exceed grid size, and therefore setting it
 153         during form creation may fail as initial grid size is often smaller
 154         than desired splitter position, especially when sizers are being used.
 155     */
 156     void SetSplitterPosition( int splitterPos, int col = 0 );
 157
 158 protected:
 159
 160     /** Propagate to other pages.
 161     */
 162     virtual void DoSetSplitterPosition( int pos,
 163                                         int splitterColumn = 0,
 164                                         bool allPages = false,
 165                                         bool fromAutoCenter = false );
 166
 167     /** Page label (may be referred as name in some parts of documentation).
 168         Can be set in constructor, or passed in
 169         wxPropertyGridManager::AddPage(), but *not* in both.
 170     */
 171     wxString                m_label;
 172
 173 #ifndef SWIG
 174
 175     //virtual bool ProcessEvent( wxEvent& event );
 176
 177     wxPropertyGridManager*  m_manager;
 178
 179     int                     m_id;  // toolbar index
 180
 181 private:
 182     bool                    m_isDefault; // is this base page object?
 183
 184 private:
 185     DECLARE_EVENT_TABLE()
 186 #endif
 187 };
 188
 189 // -----------------------------------------------------------------------
 190
 191 /** @class wxPropertyGridManager
 192
 193     wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
 194     which can optionally have toolbar for mode and page selection, and help
 195     text box.
 196     Use window flags to select components to include.
 197
 198     @section propgridmanager_window_styles_ Window Styles
 199
 200     See @ref propgrid_window_styles.
 201
 202     @section propgridmanager_event_handling Event Handling
 203
 204     See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
 205     for more information.
 206
 207     @library{wxpropgrid}
 208     @category{propgrid}
 209 */
 210 class WXDLLIMPEXP_PROPGRID
 211     wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
 212 {
 213     DECLARE_CLASS(wxPropertyGridManager)
 214     friend class wxPropertyGridPage;
 215 public:
 216
 217 #ifndef SWIG
 218     /**
 219         Two step constructor.
 220         Call Create when this constructor is called to build up the
 221         wxPropertyGridManager.
 222       */
 223     wxPropertyGridManager();
 224 #endif
 225
 226     /** The default constructor. The styles to be used are styles valid for
 227         the wxWindow.
 228         @see @link wndflags Additional Window Styles@endlink
 229     */
 230     wxPropertyGridManager( wxWindow *parent, wxWindowID id = wxID_ANY,
 231                            const wxPoint& pos = wxDefaultPosition,
 232                            const wxSize& size = wxDefaultSize,
 233                            long style = wxPGMAN_DEFAULT_STYLE,
 234                            const wxString& name = wxPropertyGridManagerNameStr );
 235
 236     /** Destructor */
 237     virtual ~wxPropertyGridManager();
 238
 239     /** Creates new property page. Note that the first page is not created
 240         automatically.
 241         @param label
 242         A label for the page. This may be shown as a toolbar tooltip etc.
 243         @param bmp
 244         Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 245         default image is used.
 246         @param pageObj
 247         wxPropertyGridPage instance. Manager will take ownership of this object.
 248         NULL indicates that a default page instance should be created.
 249
 250         @return
 251         Returns pointer to created page.
 252
 253         @remarks
 254         If toolbar is used, it is highly recommended that the pages are
 255         added when the toolbar is not turned off using window style flag
 256         switching.
 257     */
 258     wxPropertyGridPage* AddPage( const wxString& label = wxEmptyString,
 259                                  const wxBitmap& bmp = wxPG_NULL_BITMAP,
 260                                  wxPropertyGridPage* pageObj = NULL )
 261     {
 262         return InsertPage(-1, label, bmp, pageObj);
 263     }
 264
 265     /** Deletes all all properties and all pages.
 266     */
 267     virtual void Clear();
 268
 269     /** Deletes all properties on given page.
 270     */
 271     void ClearPage( int page );
 272
 273     /** Forces updating the value of property from the editor control.
 274         Returns true if DoPropertyChanged was actually called.
 275     */
 276     bool CommitChangesFromEditor( wxUint32 flags = 0 )
 277     {
 278         return m_pPropGrid->CommitChangesFromEditor(flags);
 279     }
 280
 281     /**
 282         Two step creation.
 283         Whenever the control is created without any parameters, use Create to
 284         actually create it. Don't access the control's public methods before
 285         this is called.
 286         @see @link wndflags Additional Window Styles@endlink
 287     */
 288     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 289                  const wxPoint& pos = wxDefaultPosition,
 290                  const wxSize& size = wxDefaultSize,
 291                  long style = wxPGMAN_DEFAULT_STYLE,
 292                  const wxString& name = wxPropertyGridManagerNameStr );
 293
 294     /**
 295         Enables or disables (shows/hides) categories according to parameter
 296         enable.
 297
 298         WARNING: Not tested properly, use at your own risk.
 299     */
 300     bool EnableCategories( bool enable )
 301     {
 302         long fl = m_windowStyle | wxPG_HIDE_CATEGORIES;
 303         if ( enable ) fl = m_windowStyle & ~(wxPG_HIDE_CATEGORIES);
 304         SetWindowStyleFlag(fl);
 305         return true;
 306     }
 307
 308     /** Selects page, scrolls and/or expands items to ensure that the
 309         given item is visible. Returns true if something was actually done.
 310     */
 311     bool EnsureVisible( wxPGPropArg id );
 312
 313     /** Returns number of columns on given page. By the default,
 314         returns number of columns on current page. */
 315     int GetColumnCount( int page = -1 ) const;
 316
 317     /** Returns height of the description text box. */
 318     int GetDescBoxHeight() const;
 319
 320     /** Returns pointer to the contained wxPropertyGrid. This does not change
 321         after wxPropertyGridManager has been created, so you can safely obtain
 322         pointer once and use it for the entire lifetime of the instance.
 323     */
 324     wxPropertyGrid* GetGrid()
 325     {
 326         wxASSERT(m_pPropGrid);
 327         return m_pPropGrid;
 328     };
 329
 330     const wxPropertyGrid* GetGrid() const
 331     {
 332         wxASSERT(m_pPropGrid);
 333         return (const wxPropertyGrid*)m_pPropGrid;
 334     };
 335
 336     /** Returns iterator class instance.
 337         @remarks
 338         Calling this method in wxPropertyGridManager causes run-time assertion
 339         failure. Please only iterate through individual pages or use
 340         CreateVIterator().
 341     */
 342     wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
 343                                         wxPGProperty* firstProp = NULL )
 344     {
 345         wxFAIL_MSG( "Please only iterate through individual pages "
 346                     "or use CreateVIterator()" );
 347         return wxPropertyGridInterface::GetIterator( flags, firstProp );
 348     }
 349
 350     wxPropertyGridConstIterator
 351     GetIterator(int flags = wxPG_ITERATE_DEFAULT,
 352                 wxPGProperty* firstProp = NULL) const
 353     {
 354         wxFAIL_MSG( "Please only iterate through individual pages "
 355                     " or use CreateVIterator()" );
 356         return wxPropertyGridInterface::GetIterator( flags, firstProp );
 357     }
 358
 359     /** Returns iterator class instance.
 360         @remarks
 361         Calling this method in wxPropertyGridManager causes run-time assertion
 362         failure. Please only iterate through individual pages or use
 363         CreateVIterator().
 364     */
 365     wxPropertyGridIterator GetIterator( int flags, int startPos )
 366     {
 367         wxFAIL_MSG( "Please only iterate through individual pages "
 368                     "or use CreateVIterator()" );
 369
 370         return wxPropertyGridInterface::GetIterator( flags, startPos );
 371     }
 372
 373     wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
 374     {
 375         wxFAIL_MSG( "Please only iterate through individual pages "
 376                     "or use CreateVIterator()" );
 377         return wxPropertyGridInterface::GetIterator( flags, startPos );
 378     }
 379
 380     /** Similar to GetIterator, but instead returns wxPGVIterator instance,
 381         which can be useful for forward-iterating through arbitrary property
 382         containers.
 383     */
 384     virtual wxPGVIterator GetVIterator( int flags ) const;
 385
 386     /** Returns currently selected page.
 387     */
 388     wxPropertyGridPage* GetCurrentPage() const
 389     {
 390         return GetPage(m_selPage);
 391     }
 392
 393     /** Returns page object for given page index.
 394     */
 395     wxPropertyGridPage* GetPage( unsigned int ind ) const
 396     {
 397         return m_arrPages[ind];
 398     }
 399
 400     /** Returns page object for given page name.
 401     */
 402     wxPropertyGridPage* GetPage( const wxString& name ) const
 403     {
 404         return GetPage(GetPageByName(name));
 405     }
 406
 407     /**
 408         Returns index for a page name.
 409
 410         If no match is found, wxNOT_FOUND is returned.
 411      */
 412     int GetPageByName( const wxString& name ) const;
 413
 414     /** Returns index for a relevant propertygrid state.
 415
 416         If no match is found, wxNOT_FOUND is returned.
 417     */
 418     int GetPageByState( const wxPropertyGridPageState* pstate ) const;
 419
 420 protected:
 421     /** Returns wxPropertyGridPageState of given page, current page's for -1.
 422     */
 423     virtual wxPropertyGridPageState* GetPageState( int page ) const;
 424
 425 public:
 426     /** Returns number of managed pages. */
 427     size_t GetPageCount() const;
 428
 429     /** Returns name of given page. */
 430     const wxString& GetPageName( int index ) const;
 431
 432     /** Returns "root property" of the given page. It does not have name, etc.
 433         and it is not visible. It is only useful for accessing its children.
 434     */
 435     wxPGProperty* GetPageRoot( int index ) const;
 436
 437     /** Returns index to currently selected page. */
 438     int GetSelectedPage() const { return m_selPage; }
 439
 440     /** Alias for GetSelection(). */
 441     wxPGProperty* GetSelectedProperty() const
 442     {
 443         return GetSelection();
 444     }
 445
 446     /** Shortcut for GetGrid()->GetSelection(). */
 447     wxPGProperty* GetSelection() const
 448     {
 449         return m_pPropGrid->GetSelection();
 450     }
 451
 452     /** Returns a pointer to the toolbar currently associated with the
 453         wxPropertyGridManager (if any). */
 454     wxToolBar* GetToolBar() const { return m_pToolbar; }
 455
 456     /** Creates new property page. Note that the first page is not created
 457         automatically.
 458         @param index
 459         Add to this position. -1 will add as the last item.
 460         @param label
 461         A label for the page. This may be shown as a toolbar tooltip etc.
 462         @param bmp
 463         Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 464         default image is used.
 465         @param pageObj
 466         wxPropertyGridPage instance. Manager will take ownership of this object.
 467         If NULL, default page object is constructed.
 468
 469         @return
 470         Returns pointer to created page.
 471     */
 472     virtual wxPropertyGridPage* InsertPage( int index,
 473                                             const wxString& label,
 474                                             const wxBitmap& bmp = wxNullBitmap,
 475                                             wxPropertyGridPage* pageObj = NULL );
 476
 477     /**
 478         Returns true if any property on any page has been modified by the user.
 479     */
 480     bool IsAnyModified() const;
 481
 482     /**
 483         Returns true if updating is frozen (ie Freeze() called but not yet
 484         Thaw() ).
 485      */
 486     bool IsFrozen() const { return m_pPropGrid->m_frozen > 0; }
 487
 488     /**
 489         Returns true if any property on given page has been modified by the
 490         user.
 491      */
 492     bool IsPageModified( size_t index ) const;
 493
 494     /**
 495         Returns true if property is selected. Since selection is page
 496         based, this function checks every page in the manager.
 497     */
 498     virtual bool IsPropertySelected( wxPGPropArg id ) const;
 499
 500     virtual void Refresh( bool eraseBackground = true,
 501                           const wxRect* rect = (const wxRect*) NULL );
 502
 503     /** Removes a page.
 504         @return
 505         Returns false if it was not possible to remove page in question.
 506     */
 507     virtual bool RemovePage( int page );
 508
 509     /** Select and displays a given page.
 510
 511         @param index
 512             Index of page being seleced. Can be -1 to select nothing.
 513     */
 514     void SelectPage( int index );
 515
 516     /** Select and displays a given page (by label). */
 517     void SelectPage( const wxString& label )
 518     {
 519         int index = GetPageByName(label);
 520         wxCHECK_RET( index >= 0, wxT("No page with such name") );
 521         SelectPage( index );
 522     }
 523
 524     /** Select and displays a given page. */
 525     void SelectPage( wxPropertyGridPage* ptr )
 526     {
 527         SelectPage( GetPageByState(ptr) );
 528     }
 529
 530     /** Select a property. */
 531     bool SelectProperty( wxPGPropArg id, bool focus = false )
 532     {
 533         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 534         return p->GetParentState()->DoSelectProperty(p, focus);
 535     }
 536
 537     /** Sets number of columns on given page (default is current page).
 538     */
 539     void SetColumnCount( int colCount, int page = -1 );
 540
 541     /** Sets label and text in description box.
 542     */
 543     void SetDescription( const wxString& label, const wxString& content );
 544
 545     /** Sets y coordinate of the description box splitter. */
 546     void SetDescBoxHeight( int ht, bool refresh = true );
 547
 548     /** Moves splitter as left as possible, while still allowing all
 549         labels to be shown in full.
 550         @param subProps
 551         If false, will still allow sub-properties (ie. properties which
 552         parent is not root or category) to be cropped.
 553         @param allPages
 554         If true, takes labels on all pages into account.
 555     */
 556     void SetSplitterLeft( bool subProps = false, bool allPages = true );
 557
 558     /** Sets splitter position on individual page. */
 559     void SetPageSplitterPosition( int page, int pos, int column = 0 )
 560     {
 561         GetPage(page)->DoSetSplitterPosition( pos, column );
 562     }
 563
 564     /** Sets splitter position for all pages.
 565         @remarks
 566         Splitter position cannot exceed grid size, and therefore setting it
 567         during form creation may fail as initial grid size is often smaller
 568         than desired splitter position, especially when sizers are being used.
 569     */
 570     void SetSplitterPosition( int pos, int column = 0 );
 571
 572 protected:
 573
 574     //
 575     // Subclassing helpers
 576     //
 577
 578     /**
 579         Creates property grid for the manager. Reimplement in derived class to
 580         use subclassed wxPropertyGrid. However, if you you do this then you
 581         must also use the two-step construction (ie. default constructor and
 582         Create() instead of constructor with arguments) when creating the
 583         manager.
 584     */
 585     virtual wxPropertyGrid* CreatePropertyGrid() const;
 586
 587 public:
 588     virtual void RefreshProperty( wxPGProperty* p );
 589
 590     //
 591     // Overridden functions - no documentation required.
 592     //
 593
 594     void SetId( wxWindowID winid );
 595
 596     virtual void Freeze();
 597     virtual void Thaw();
 598     virtual void SetExtraStyle ( long exStyle );
 599     virtual bool SetFont ( const wxFont& font );
 600     virtual void SetWindowStyleFlag ( long style );
 601     virtual bool Reparent( wxWindowBase *newParent );
 602
 603 protected:
 604     virtual wxSize DoGetBestSize() const;
 605
 606 public:
 607
 608 #ifndef SWIG
 609
 610     //
 611     // Event handlers
 612     //
 613     void OnMouseMove( wxMouseEvent &event );
 614     void OnMouseClick( wxMouseEvent &event );
 615     void OnMouseUp( wxMouseEvent &event );
 616     void OnMouseEntry( wxMouseEvent &event );
 617
 618     void OnPaint( wxPaintEvent &event );
 619
 620     void OnToolbarClick( wxCommandEvent &event );
 621     void OnResize( wxSizeEvent& event );
 622     void OnPropertyGridSelect( wxPropertyGridEvent& event );
 623
 624 protected:
 625
 626     wxPropertyGrid* m_pPropGrid;
 627
 628     wxVector<wxPropertyGridPage*>   m_arrPages;
 629
 630 #if wxUSE_TOOLBAR
 631     wxToolBar*      m_pToolbar;
 632 #endif
 633     wxStaticText*   m_pTxtHelpCaption;
 634     wxStaticText*   m_pTxtHelpContent;
 635
 636     wxPropertyGridPage*     m_emptyPage;
 637
 638     long            m_iFlags;
 639
 640     // Selected page index.
 641     int             m_selPage;
 642
 643     int             m_width;
 644
 645     int             m_height;
 646
 647     int             m_extraHeight;
 648
 649     int             m_splitterY;
 650
 651     int             m_splitterHeight;
 652
 653     int             m_nextTbInd;
 654
 655     int             m_dragOffset;
 656
 657     wxCursor        m_cursorSizeNS;
 658
 659     int             m_nextDescBoxSize;
 660
 661     wxWindowID      m_baseId;
 662
 663     unsigned char   m_dragStatus;
 664
 665     unsigned char   m_onSplitter;
 666
 667     virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
 668
 669     /** Select and displays a given page. */
 670     virtual bool DoSelectPage( int index );
 671
 672     // Sets some members to defaults.
 673     void Init1();
 674
 675     // Initializes some members.
 676     void Init2( int style );
 677
 678 /*#ifdef __WXMSW__
 679     virtual WXDWORD MSWGetStyle(long flags, WXDWORD *exstyle) const;
 680 #endif*/
 681
 682     virtual bool ProcessEvent( wxEvent& event );
 683
 684     /** Recalculates new positions for components, according to the
 685         given size.
 686     */
 687     void RecalculatePositions( int width, int height );
 688
 689     /** (Re)creates/destroys controls, according to the window style bits. */
 690     void RecreateControls();
 691
 692     void UpdateDescriptionBox( int new_splittery, int new_width, int new_height );
 693
 694     void RepaintDescBoxDecorations( wxDC& dc,
 695                                     int newSplitterY,
 696                                     int newWidth,
 697                                     int newHeight );
 698
 699     void SetDescribedProperty( wxPGProperty* p );
 700
 701     // Reimplement these to handle "descboxheight" state item
 702     virtual bool SetEditableStateItem( const wxString& name, wxVariant value );
 703     virtual wxVariant GetEditableStateItem( const wxString& name ) const;
 704
 705 private:
 706     DECLARE_EVENT_TABLE()
 707 #endif // #ifndef SWIG
 708 };
 709
 710 // -----------------------------------------------------------------------
 711
 712 inline int wxPropertyGridPage::GetIndex() const
 713 {
 714     if ( !m_manager )
 715         return wxNOT_FOUND;
 716     return m_manager->GetPageByState(this);
 717 }
 718
 719 // -----------------------------------------------------------------------
 720
 721 #endif // wxUSE_PROPGRID
 722
 723 #endif // _WX_PROPGRID_MANAGER_H_