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         // Adding a page sets target page to the one added, so
 161         // we don't have to call SetTargetPage if we are filling
 162         // it right after adding.
 163         pgMan->AddPage(wxT("First Page"));
 164         page = pgMan->GetLastPage();
 165
 166         page->Append( new wxPropertyCategory(wxT("Category A1")) );
 167
 168         page->Append( new wxIntProperty(wxT("Number"),wxPG_LABEL,1) );
 169
 170         page->Append( new wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );
 171
 172         pgMan->AddPage(wxT("Second Page"));
 173         page = pgMan->GetLastPage();
 174
 175         page->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );
 176
 177         page->Append( new wxFontProperty(wxT("Font"),wxPG_LABEL) );
 178
 179     @endcode
 180
 181
 182     @section propgridmanager_window_styles_ Window Styles
 183
 184     See @ref propgrid_window_styles.
 185
 186     @section propgridmanager_event_handling Event Handling
 187
 188     See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
 189     for more information.
 190
 191     @library{wxpropgrid}
 192     @category{propgrid}
 193 */
 194 class wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
 195 {
 196 public:
 197     /** Creates new property page. Note that the first page is not created
 198         automatically.
 199         @param label
 200         A label for the page. This may be shown as a toolbar tooltip etc.
 201         @param bmp
 202         Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 203         default image is used.
 204         @param pageObj
 205         wxPropertyGridPage instance. Manager will take ownership of this object.
 206         NULL indicates that a default page instance should be created.
 207         @retval
 208         Returns index to the page created.
 209         @remarks
 210         If toolbar is used, it is highly recommended that the pages are
 211         added when the toolbar is not turned off using window style flag
 212         switching.
 213     */
 214     int AddPage( const wxString& label = wxEmptyString,
 215                  const wxBitmap& bmp = wxPG_NULL_BITMAP,
 216                  wxPropertyGridPage* pageObj = (wxPropertyGridPage*) NULL )
 217     {
 218         return InsertPage(-1,label,bmp,pageObj);
 219     }
 220
 221     void ClearModifiedStatus ( wxPGPropArg id );
 222
 223     void ClearModifiedStatus ()
 224     {
 225         m_pPropGrid->ClearModifiedStatus();
 226     }
 227
 228     /** Deletes all all properties and all pages.
 229     */
 230     virtual void Clear();
 231
 232     /** Deletes all properties on given page.
 233     */
 234     void ClearPage( int page );
 235
 236     /** Forces updating the value of property from the editor control.
 237         Returns true if DoPropertyChanged was actually called.
 238     */
 239     bool CommitChangesFromEditor( wxUint32 flags = 0 )
 240     {
 241         return m_pPropGrid->CommitChangesFromEditor(flags);
 242     }
 243
 244     /** Two step creation. Whenever the control is created without any parameters,
 245         use Create to actually create it. Don't access the control's public methods
 246         before this is called.
 247         @sa @link wndflags Additional Window Styles@endlink
 248     */
 249     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 250                  const wxPoint& pos = wxDefaultPosition,
 251                  const wxSize& size = wxDefaultSize,
 252                  long style = wxPGMAN_DEFAULT_STYLE,
 253                  const wxChar* name = wxPropertyGridManagerNameStr );
 254
 255     /** Enables or disables (shows/hides) categories according to parameter enable.
 256         WARNING: Not tested properly, use at your own risk.
 257     */
 258     bool EnableCategories( bool enable )
 259     {
 260         long fl = m_windowStyle | wxPG_HIDE_CATEGORIES;
 261         if ( enable ) fl = m_windowStyle & ~(wxPG_HIDE_CATEGORIES);
 262         SetWindowStyleFlag(fl);
 263         return true;
 264     }
 265
 266     /** Selects page, scrolls and/or expands items to ensure that the
 267         given item is visible. Returns true if something was actually done.
 268     */
 269     bool EnsureVisible( wxPGPropArg id );
 270
 271     /** Returns number of children of the root property of the selected page. */
 272     size_t GetChildrenCount()
 273     {
 274         return GetChildrenCount( m_pPropGrid->m_pState->m_properties );
 275     }
 276
 277     /** Returns number of children of the root property of given page. */
 278     size_t GetChildrenCount( int pageIndex );
 279
 280     /** Returns number of children for the property.
 281
 282         NB: Cannot be in container methods class due to name hiding.
 283     */
 284     size_t GetChildrenCount( wxPGPropArg id ) const
 285     {
 286         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
 287         return p->GetChildCount();
 288     }
 289
 290     /** Returns number of columns on given page. By the default,
 291         returns number of columns on current page. */
 292     int GetColumnCount( int page = -1 ) const;
 293
 294     /** Returns height of the description text box. */
 295     int GetDescBoxHeight() const;
 296
 297     /** Returns pointer to the contained wxPropertyGrid. This does not change
 298         after wxPropertyGridManager has been created, so you can safely obtain
 299         pointer once and use it for the entire lifetime of the instance.
 300     */
 301     wxPropertyGrid* GetGrid()
 302     {
 303         wxASSERT(m_pPropGrid);
 304         return m_pPropGrid;
 305     };
 306
 307     const wxPropertyGrid* GetGrid() const
 308     {
 309         wxASSERT(m_pPropGrid);
 310         return (const wxPropertyGrid*)m_pPropGrid;
 311     };
 312
 313     /** Returns iterator class instance.
 314         @remarks
 315         Calling this method in wxPropertyGridManager causes run-time assertion failure.
 316         Please only iterate through individual pages or use CreateVIterator().
 317     */
 318     wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL )
 319     {
 320         wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
 321         return wxPropertyGridInterface::GetIterator( flags, firstProp );
 322     }
 323
 324     wxPropertyGridConstIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL ) const
 325     {
 326         wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
 327         return wxPropertyGridInterface::GetIterator( flags, firstProp );
 328     }
 329
 330     /** Returns iterator class instance.
 331         @remarks
 332         Calling this method in wxPropertyGridManager causes run-time assertion failure.
 333         Please only iterate through individual pages or use CreateVIterator().
 334     */
 335     wxPropertyGridIterator GetIterator( int flags, int startPos )
 336     {
 337         wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
 338         return wxPropertyGridInterface::GetIterator( flags, startPos );
 339     }
 340
 341     wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
 342     {
 343         wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
 344         return wxPropertyGridInterface::GetIterator( flags, startPos );
 345     }
 346
 347     /** Similar to GetIterator, but instead returns wxPGVIterator instance,
 348         which can be useful for forward-iterating through arbitrary property
 349         containers.
 350     */
 351     virtual wxPGVIterator GetVIterator( int flags ) const;
 352
 353     /** Returns currently selected page.
 354     */
 355     wxPropertyGridPage* GetCurrentPage() const
 356     {
 357         return GetPage(m_selPage);
 358     }
 359
 360     /** Returns last page.
 361     */
 362     wxPropertyGridPage* GetLastPage() const
 363     {
 364         return GetPage(m_arrPages.size()-1);
 365     }
 366
 367     /** Returns page object for given page index.
 368     */
 369     wxPropertyGridPage* GetPage( unsigned int ind ) const
 370     {
 371         return (wxPropertyGridPage*)m_arrPages.Item(ind);
 372     }
 373
 374     /** Returns page object for given page name.
 375     */
 376     wxPropertyGridPage* GetPage( const wxString& name ) const
 377     {
 378         return GetPage(GetPageByName(name));
 379     }
 380
 381     /** Returns index for a page name. If no match is found, wxNOT_FOUND is returned. */
 382     int GetPageByName( const wxString& name ) const;
 383
 384     /** Returns number of managed pages. */
 385     size_t GetPageCount() const;
 386
 387     /** Returns name of given page. */
 388     const wxString& GetPageName( int index ) const;
 389
 390     /** Returns "root property" of the given page. It does not have name, etc.
 391         and it is not visible. It is only useful for accessing its children.
 392     */
 393     wxPGProperty* GetPageRoot( int index ) const;
 394
 395     /** Returns index to currently selected page. */
 396     int GetSelectedPage() const { return m_selPage; }
 397
 398     /** Shortcut for GetGrid()->GetSelection(). */
 399     wxPGProperty* GetSelectedProperty() const
 400     {
 401         return m_pPropGrid->GetSelection();
 402     }
 403
 404     /** Synonyme for GetSelectedPage. */
 405     int GetSelection() const { return m_selPage; }
 406
 407     /** Returns a pointer to the toolbar currently associated with the
 408         wxPropertyGridManager (if any). */
 409     wxToolBar* GetToolBar() const { return m_pToolbar; }
 410
 411     /** Creates new property page. Note that the first page is not created
 412         automatically.
 413         @param index
 414         Add to this position. -1 will add as the last item.
 415         @param label
 416         A label for the page. This may be shown as a toolbar tooltip etc.
 417         @param bmp
 418         Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 419         default image is used.
 420         @param pageObj
 421         wxPropertyGridPage instance. Manager will take ownership of this object.
 422         If NULL, default page object is constructed.
 423         @retval
 424         Returns index to the page created.
 425     */
 426     virtual int InsertPage( int index, const wxString& label, const wxBitmap& bmp = wxNullBitmap,
 427                             wxPropertyGridPage* pageObj = (wxPropertyGridPage*) NULL );
 428
 429     /** Returns true if any property on any page has been modified by the user. */
 430     bool IsAnyModified() const;
 431
 432     /** Returns true if updating is frozen (ie. Freeze() called but not yet Thaw() ). */
 433     bool IsFrozen() const { return (m_pPropGrid->m_frozen>0)?true:false; }
 434
 435     /** Returns true if any property on given page has been modified by the user. */
 436     bool IsPageModified( size_t index ) const;
 437
 438     virtual void Refresh( bool eraseBackground = true,
 439                           const wxRect* rect = (const wxRect*) NULL );
 440
 441     /** Removes a page.
 442         @retval
 443         Returns false if it was not possible to remove page in question.
 444     */
 445     virtual bool RemovePage( int page );
 446
 447     /** Select and displays a given page. Also makes it target page for
 448         insert operations etc.
 449         @param index
 450         Index of page being seleced. Can be -1 to select nothing.
 451     */
 452     void SelectPage( int index );
 453
 454     /** Select and displays a given page (by label). */
 455     void SelectPage( const wxString& label )
 456     {
 457         int index = GetPageByName(label);
 458         wxCHECK_RET( index >= 0, wxT("No page with such name") );
 459         SelectPage( index );
 460     }
 461
 462     /** Select and displays a given page. */
 463     void SelectPage( wxPropertyGridPage* ptr )
 464     {
 465         SelectPage( GetPageByState(ptr) );
 466     }
 467
 468     /** Select a property. */
 469     bool SelectProperty( wxPGPropArg id, bool focus = false )
 470     {
 471         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 472         return p->GetParentState()->DoSelectProperty(p, focus);
 473     }
 474
 475     /** Sets number of columns on given page (default is current page).
 476     */
 477     void SetColumnCount( int colCount, int page = -1 );
 478
 479     /** Sets label and text in description box.
 480     */
 481     void SetDescription( const wxString& label, const wxString& content );
 482
 483     /** Sets y coordinate of the description box splitter. */
 484     void SetDescBoxHeight( int ht, bool refresh = true );
 485
 486     /** Moves splitter as left as possible, while still allowing all
 487         labels to be shown in full.
 488         @param subProps
 489         If false, will still allow sub-properties (ie. properties which
 490         parent is not root or category) to be cropped.
 491         @param allPages
 492         If true, takes labels on all pages into account.
 493     */
 494     void SetSplitterLeft( bool subProps = false, bool allPages = true );
 495
 496     /** Sets splitter position on individual page. */
 497     void SetPageSplitterPosition( int page, int pos, int column = 0 )
 498     {
 499         GetPage(page)->DoSetSplitterPosition( pos, column );
 500     }
 501
 502     /** Sets splitter position for all pages.
 503         @remarks
 504         Splitter position cannot exceed grid size, and therefore setting it during
 505         form creation may fail as initial grid size is often smaller than desired
 506         splitter position, especially when sizers are being used.
 507     */
 508     void SetSplitterPosition( int pos, int column = 0 );
 509
 510     /** Synonyme for SelectPage(name). */
 511     void SetStringSelection( const wxChar* name )
 512     {
 513         SelectPage( GetPageByName(name) );
 514     }
 515
 516 protected:
 517
 518     //
 519     // Subclassing helpers
 520     //
 521
 522     /** Creates property grid for the manager. Override to use subclassed
 523         wxPropertyGrid.
 524     */
 525     virtual wxPropertyGrid* CreatePropertyGrid() const;
 526
 527     virtual void RefreshProperty( wxPGProperty* p );
 528 };
 529
 530 // -----------------------------------------------------------------------