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