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