interface/wx/propgrid/manager.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        manager.h
   3 // Purpose:     interface of wxPropertyGridManager
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id:
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /** @class wxPropertyGridPage
  10
  11     Holder of property grid page information. You can subclass this and
  12     give instance in wxPropertyGridManager::AddPage. It inherits from
  13     wxEvtHandler and can be used to process events specific to this
  14     page (id of events will still be same as manager's). If you don't
  15     want to use it to process all events of the page, you need to
  16     return false in the derived wxPropertyGridPage::IsHandlingAllEvents.
  17
  18     Please note that wxPropertyGridPage lacks many non-const property
  19     manipulation functions found in wxPropertyGridManager. Please use
  20     parent manager (m_manager member variable) when needed.
  21
  22     Please note that most member functions are inherited and as such not documented on
  23     this page. This means you will probably also want to read wxPropertyGridInterface
  24     class reference.
  25
  26     @section propgridpage_event_handling Event Handling
  27
  28     wxPropertyGridPage receives events emitted by its wxPropertyGridManager, but
  29     only those events that are specific to that page. If wxPropertyGridPage::IsHandlingAllEvents
  30     returns false, then unhandled events are sent to the manager's parent, as usual.
  31
  32     See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
  33     for more information.
  34
  35     @library{wxpropgrid}
  36     @category{propgrid}
  37 */
  38 class WXDLLIMPEXP_PROPGRID wxPropertyGridPage : public wxEvtHandler,
  39                                                 public wxPropertyGridInterface
  40 {
  41     friend class wxPropertyGridManager;
  42 public:
  43
  44     wxPropertyGridPage();
  45     virtual ~wxPropertyGridPage();
  46
  47     /** Deletes all properties on page.
  48     */
  49     virtual void Clear();
  50
  51     /** Reduces column sizes to minimum possible that contents are still visibly (naturally
  52         some margin space will be applied as well).
  53
  54         @retval
  55         Minimum size for the page to still display everything.
  56
  57         @remarks
  58         This function only works properly if size of containing grid was already fairly large.
  59
  60         Note that you can also get calculated column widths by calling GetColumnWidth()
  61         immediately after this function returns.
  62     */
  63     wxSize FitColumns();
  64
  65     /** Returns page index in manager;
  66     */
  67     inline int GetIndex() const;
  68
  69     /** Returns x-coordinate position of splitter on a page.
  70     */
  71     int GetSplitterPosition( int col = 0 ) const { return GetStatePtr()->DoGetSplitterPosition(col); }
  72
  73     /** Returns "root property". It does not have name, etc. and it is not
  74         visible. It is only useful for accessing its children.
  75     */
  76     wxPGProperty* GetRoot() const { return GetStatePtr()->DoGetRoot(); }
  77
  78     /** Returns id of the tool bar item that represents this page on wxPropertyGridManager's wxToolBar.
  79     */
  80     int GetToolId() const
  81     {
  82         return m_id;
  83     }
  84
  85     /** Do any member initialization in this method.
  86         @remarks
  87         - Called every time the page is added into a manager.
  88         - You can add properties to the page here.
  89     */
  90     virtual void Init() {}
  91
  92     /** Return false here to indicate unhandled events should be
  93         propagated to manager's parent, as normal.
  94     */
  95     virtual bool IsHandlingAllEvents() const { return true; }
  96
  97     /** Called every time page is about to be shown.
  98         Useful, for instance, creating properties just-in-time.
  99     */
 100     virtual void OnShow();
 101
 102     virtual void RefreshProperty( wxPGProperty* p );
 103
 104     /** Sets splitter position on page.
 105         @remarks
 106         Splitter position cannot exceed grid size, and therefore setting it during
 107         form creation may fail as initial grid size is often smaller than desired
 108         splitter position, especially when sizers are being used.
 109     */
 110     void SetSplitterPosition( int splitterPos, int col = 0 );
 111 };
 112
 113 // -----------------------------------------------------------------------
 114
 115 /** @class wxPropertyGridManager
 116
 117     wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
 118     which can optionally have toolbar for mode and page selection, and a help text
 119     box.
 120
 121     wxPropertyGridManager inherits from wxPropertyGridInterface, and as such
 122     it has most property manipulation functions. However, only some of them affect
 123     properties on all pages (eg. GetPropertyByName() and ExpandAll()), while some
 124     (eg. Append()) only apply to the currently selected page.
 125
 126     To operate explicitly on properties on specific page, use wxPropertyGridManager::GetPage()
 127     to obtain pointer to page's wxPropertyGridPage object.
 128
 129     Visual methods, such as SetCellBackgroundColour() are only available in
 130     wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain pointer to it.
 131
 132     Non-virtual iterators will not work in wxPropertyGridManager. Instead, you must
 133     acquire the internal grid (GetGrid()) or wxPropertyGridPage object (GetPage()).
 134
 135     wxPropertyGridManager constructor has exact same format as wxPropertyGrid
 136     constructor, and basicly accepts same extra window style flags (albeit also
 137     has some extra ones).
 138
 139     Here's some example code for creating and populating a wxPropertyGridManager:
 140
 141     @code
 142
 143         wxPropertyGridManager* pgMan = new wxPropertyGridManager(this, PGID,
 144             wxDefaultPosition, wxDefaultSize,
 145             // These and other similar styles are automatically
 146             // passed to the embedded wxPropertyGrid.
 147             wxPG_BOLD_MODIFIED|wxPG_SPLITTER_AUTO_CENTER|
 148             // Include toolbar.
 149             wxPG_TOOLBAR |
 150             // Include description box.
 151             wxPG_DESCRIPTION |
 152             // Include compactor.
 153             wxPG_COMPACTOR |
 154             // Plus defaults.
 155             wxPGMAN_DEFAULT_STYLE
 156            );
 157
 158         wxPropertyGridPage* page;
 159
 160         pgMan->AddPage(wxT("First Page"));
 161         page = pgMan->GetLastPage();
 162
 163         page->Append( new wxPropertyCategory(wxT("Category A1")) );
 164
 165         page->Append( new wxIntProperty(wxT("Number"),wxPG_LABEL,1) );
 166
 167         page->Append( new wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );
 168
 169         pgMan->AddPage(wxT("Second Page"));
 170         page = pgMan->GetLastPage();
 171
 172         page->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );
 173
 174         page->Append( new wxFontProperty(wxT("Font"),wxPG_LABEL) );
 175
 176     @endcode
 177
 178
 179     @section propgridmanager_window_styles_ Window Styles
 180
 181     See @ref propgrid_window_styles.
 182
 183     @section propgridmanager_event_handling Event Handling
 184
 185     See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
 186     for more information.
 187
 188     @library{wxpropgrid}
 189     @category{propgrid}
 190 */
 191 class wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
 192 {
 193 public:
 194     /** Creates new property page. Note that the first page is not created
 195         automatically.
 196         @param label
 197         A label for the page. This may be shown as a toolbar tooltip etc.
 198         @param bmp
 199         Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 200         default image is used.
 201         @param pageObj
 202         wxPropertyGridPage instance. Manager will take ownership of this object.
 203         NULL indicates that a default page instance should be created.
 204         @retval
 205         Returns index to the page created.
 206         @remarks
 207         If toolbar is used, it is highly recommended that the pages are
 208         added when the toolbar is not turned off using window style flag
 209         switching.
 210     */
 211     int AddPage( const wxString& label = wxEmptyString,
 212                  const wxBitmap& bmp = wxPG_NULL_BITMAP,
 213                  wxPropertyGridPage* pageObj = (wxPropertyGridPage*) NULL )
 214     {
 215         return InsertPage(-1,label,bmp,pageObj);
 216     }
 217
 218     void ClearModifiedStatus ( wxPGPropArg id );
 219
 220     void ClearModifiedStatus ()
 221     {
 222         m_pPropGrid->ClearModifiedStatus();
 223     }
 224
 225     /** Deletes all all properties and all pages.
 226     */
 227     virtual void Clear();
 228
 229     /** Deletes all properties on given page.
 230     */
 231     void ClearPage( int page );
 232
 233     /** Forces updating the value of property from the editor control.
 234         Returns true if DoPropertyChanged was actually called.
 235     */
 236     bool CommitChangesFromEditor( wxUint32 flags = 0 )
 237     {
 238         return m_pPropGrid->CommitChangesFromEditor(flags);
 239     }
 240
 241     /** Two step creation. Whenever the control is created without any parameters,
 242         use Create to actually create it. Don't access the control's public methods
 243         before this is called.
 244         @sa @link wndflags Additional Window Styles@endlink
 245     */
 246     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 247                  const wxPoint& pos = wxDefaultPosition,
 248                  const wxSize& size = wxDefaultSize,
 249                  long style = wxPGMAN_DEFAULT_STYLE,
 250                  const wxChar* name = wxPropertyGridManagerNameStr );
 251
 252     /** Enables or disables (shows/hides) categories according to parameter enable.
 253         WARNING: Not tested properly, use at your own risk.
 254     */
 255     bool EnableCategories( bool enable )
 256     {
 257         long fl = m_windowStyle | wxPG_HIDE_CATEGORIES;
 258         if ( enable ) fl = m_windowStyle & ~(wxPG_HIDE_CATEGORIES);
 259         SetWindowStyleFlag(fl);
 260         return true;
 261     }
 262
 263     /** Selects page, scrolls and/or expands items to ensure that the
 264         given item is visible. Returns true if something was actually done.
 265     */
 266     bool EnsureVisible( wxPGPropArg id );
 267
 268     /** Returns number of children of the root property of the selected page. */
 269     size_t GetChildrenCount()
 270     {
 271         return GetChildrenCount( m_pPropGrid->m_pState->m_properties );
 272     }
 273
 274     /** Returns number of children of the root property of given page. */
 275     size_t GetChildrenCount( int pageIndex );
 276
 277     /** Returns number of children for the property.
 278
 279         NB: Cannot be in container methods class due to name hiding.
 280     */
 281     size_t GetChildrenCount( wxPGPropArg id ) const
 282     {
 283         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
 284         return p->GetChildCount();
 285     }
 286
 287     /** Returns number of columns on given page. By the default,
 288         returns number of columns on current page. */
 289     int GetColumnCount( int page = -1 ) const;
 290
 291     /** Returns height of the description text box. */
 292     int GetDescBoxHeight() const;
 293
 294     /** Returns pointer to the contained wxPropertyGrid. This does not change
 295         after wxPropertyGridManager has been created, so you can safely obtain
 296         pointer once and use it for the entire lifetime of the instance.
 297     */
 298     wxPropertyGrid* GetGrid()
 299     {
 300         wxASSERT(m_pPropGrid);
 301         return m_pPropGrid;
 302     };
 303
 304     const wxPropertyGrid* GetGrid() const
 305     {
 306         wxASSERT(m_pPropGrid);
 307         return (const wxPropertyGrid*)m_pPropGrid;
 308     };
 309
 310     /** Returns iterator class instance.
 311         @remarks
 312         Calling this method in wxPropertyGridManager causes run-time assertion failure.
 313         Please only iterate through individual pages or use CreateVIterator().
 314     */
 315     wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL )
 316     {
 317         wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
 318         return wxPropertyGridInterface::GetIterator( flags, firstProp );
 319     }
 320
 321     wxPropertyGridConstIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL ) const
 322     {
 323         wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
 324         return wxPropertyGridInterface::GetIterator( flags, firstProp );
 325     }
 326
 327     /** Returns iterator class instance.
 328         @remarks
 329         Calling this method in wxPropertyGridManager causes run-time assertion failure.
 330         Please only iterate through individual pages or use CreateVIterator().
 331     */
 332     wxPropertyGridIterator GetIterator( int flags, int startPos )
 333     {
 334         wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
 335         return wxPropertyGridInterface::GetIterator( flags, startPos );
 336     }
 337
 338     wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
 339     {
 340         wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
 341         return wxPropertyGridInterface::GetIterator( flags, startPos );
 342     }
 343
 344     /** Similar to GetIterator, but instead returns wxPGVIterator instance,
 345         which can be useful for forward-iterating through arbitrary property
 346         containers.
 347     */
 348     virtual wxPGVIterator GetVIterator( int flags ) const;
 349
 350     /** Returns currently selected page.
 351     */
 352     wxPropertyGridPage* GetCurrentPage() const
 353     {
 354         return GetPage(m_selPage);
 355     }
 356
 357     /** Returns last page.
 358     */
 359     wxPropertyGridPage* GetLastPage() const
 360     {
 361         return GetPage(m_arrPages.size()-1);
 362     }
 363
 364     /** Returns page object for given page index.
 365     */
 366     wxPropertyGridPage* GetPage( unsigned int ind ) const
 367     {
 368         return (wxPropertyGridPage*)m_arrPages.Item(ind);
 369     }
 370
 371     /** Returns page object for given page name.
 372     */
 373     wxPropertyGridPage* GetPage( const wxString& name ) const
 374     {
 375         return GetPage(GetPageByName(name));
 376     }
 377
 378     /** Returns index for a page name. If no match is found, wxNOT_FOUND is returned. */
 379     int GetPageByName( const wxString& name ) const;
 380
 381     /** Returns number of managed pages. */
 382     size_t GetPageCount() const;
 383
 384     /** Returns name of given page. */
 385     const wxString& GetPageName( int index ) const;
 386
 387     /** Returns "root property" of the given page. It does not have name, etc.
 388         and it is not visible. It is only useful for accessing its children.
 389     */
 390     wxPGProperty* GetPageRoot( int index ) const;
 391
 392     /** Returns index to currently selected page. */
 393     int GetSelectedPage() const { return m_selPage; }
 394
 395     /** Shortcut for GetGrid()->GetSelection(). */
 396     wxPGProperty* GetSelectedProperty() const
 397     {
 398         return m_pPropGrid->GetSelection();
 399     }
 400
 401     /** Synonyme for GetSelectedPage. */
 402     int GetSelection() const { return m_selPage; }
 403
 404     /** Returns a pointer to the toolbar currently associated with the
 405         wxPropertyGridManager (if any). */
 406     wxToolBar* GetToolBar() const { return m_pToolbar; }
 407
 408     /** Creates new property page. Note that the first page is not created
 409         automatically.
 410         @param index
 411         Add to this position. -1 will add as the last item.
 412         @param label
 413         A label for the page. This may be shown as a toolbar tooltip etc.
 414         @param bmp
 415         Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 416         default image is used.
 417         @param pageObj
 418         wxPropertyGridPage instance. Manager will take ownership of this object.
 419         If NULL, default page object is constructed.
 420         @retval
 421         Returns index to the page created.
 422     */
 423     virtual int InsertPage( int index, const wxString& label, const wxBitmap& bmp = wxNullBitmap,
 424                             wxPropertyGridPage* pageObj = (wxPropertyGridPage*) NULL );
 425
 426     /** Returns true if any property on any page has been modified by the user. */
 427     bool IsAnyModified() const;
 428
 429     /** Returns true if updating is frozen (ie. Freeze() called but not yet Thaw() ). */
 430     bool IsFrozen() const { return (m_pPropGrid->m_frozen>0)?true:false; }
 431
 432     /** Returns true if any property on given page has been modified by the user. */
 433     bool IsPageModified( size_t index ) const;
 434
 435     virtual void Refresh( bool eraseBackground = true,
 436                           const wxRect* rect = (const wxRect*) NULL );
 437
 438     /** Removes a page.
 439         @retval
 440         Returns false if it was not possible to remove page in question.
 441     */
 442     virtual bool RemovePage( int page );
 443
 444     /** Select and displays a given page.
 445
 446         @param index
 447             Index of page being seleced. Can be -1 to select nothing.
 448     */
 449     void SelectPage( int index );
 450
 451     /** Select and displays a given page (by label). */
 452     void SelectPage( const wxString& label )
 453     {
 454         int index = GetPageByName(label);
 455         wxCHECK_RET( index >= 0, wxT("No page with such name") );
 456         SelectPage( index );
 457     }
 458
 459     /** Select and displays a given page. */
 460     void SelectPage( wxPropertyGridPage* ptr )
 461     {
 462         SelectPage( GetPageByState(ptr) );
 463     }
 464
 465     /** Select a property. */
 466     bool SelectProperty( wxPGPropArg id, bool focus = false )
 467     {
 468         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 469         return p->GetParentState()->DoSelectProperty(p, focus);
 470     }
 471
 472     /** Sets number of columns on given page (default is current page).
 473     */
 474     void SetColumnCount( int colCount, int page = -1 );
 475
 476     /** Sets label and text in description box.
 477     */
 478     void SetDescription( const wxString& label, const wxString& content );
 479
 480     /** Sets y coordinate of the description box splitter. */
 481     void SetDescBoxHeight( int ht, bool refresh = true );
 482
 483     /** Moves splitter as left as possible, while still allowing all
 484         labels to be shown in full.
 485         @param subProps
 486         If false, will still allow sub-properties (ie. properties which
 487         parent is not root or category) to be cropped.
 488         @param allPages
 489         If true, takes labels on all pages into account.
 490     */
 491     void SetSplitterLeft( bool subProps = false, bool allPages = true );
 492
 493     /** Sets splitter position on individual page. */
 494     void SetPageSplitterPosition( int page, int pos, int column = 0 )
 495     {
 496         GetPage(page)->DoSetSplitterPosition( pos, column );
 497     }
 498
 499     /** Sets splitter position for all pages.
 500         @remarks
 501         Splitter position cannot exceed grid size, and therefore setting it during
 502         form creation may fail as initial grid size is often smaller than desired
 503         splitter position, especially when sizers are being used.
 504     */
 505     void SetSplitterPosition( int pos, int column = 0 );
 506
 507     /** Synonyme for SelectPage(name). */
 508     void SetStringSelection( const wxChar* name )
 509     {
 510         SelectPage( GetPageByName(name) );
 511     }
 512
 513 protected:
 514
 515     //
 516     // Subclassing helpers
 517     //
 518
 519     /** Creates property grid for the manager. Override to use subclassed
 520         wxPropertyGrid.
 521     */
 522     virtual wxPropertyGrid* CreatePropertyGrid() const;
 523
 524     virtual void RefreshProperty( wxPGProperty* p );
 525 };
 526
 527 // -----------------------------------------------------------------------