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