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 licence
   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, a help text
 132     box, and a header.
 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
 187         // Display a header above the grid
 188         pgMan->ShowHeader();
 189     @endcode
 190
 191     @section propgridmanager_window_styles_ Window Styles
 192
 193     See @ref propgrid_window_styles.
 194
 195     @section propgridmanager_event_handling Event Handling
 196
 197     See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
 198     for more information.
 199
 200     @library{wxpropgrid}
 201     @category{propgrid}
 202 */
 203 class wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
 204 {
 205 public:
 206     /**
 207         Creates new property page. Note that the first page is not created
 208         automatically.
 209
 210         @param label
 211             A label for the page. This may be shown as a toolbar tooltip etc.
 212
 213         @param bmp
 214             Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 215             default image is used.
 216
 217         @param pageObj
 218             wxPropertyGridPage instance. Manager will take ownership of this
 219             object. NULL indicates that a default page instance should be created.
 220
 221         @return Returns pointer to created property grid page.
 222
 223         @remarks If toolbar is used, it is highly recommended that the pages are
 224                 added when the toolbar is not turned off using window style flag
 225                 switching. Otherwise toolbar buttons might not be added properly.
 226     */
 227     wxPropertyGridPage* AddPage( const wxString& label = wxEmptyString,
 228                                  const wxBitmap& bmp = wxPG_NULL_BITMAP,
 229                                  wxPropertyGridPage* pageObj = NULL );
 230
 231     /**
 232         Deletes all properties and all pages.
 233     */
 234     virtual void Clear();
 235
 236     /**
 237         Deletes all properties on given page.
 238     */
 239     void ClearPage( int page );
 240
 241     /**
 242         Forces updating the value of property from the editor control.
 243
 244         @return Returns @true if value was actually updated.
 245     */
 246     bool CommitChangesFromEditor( wxUint32 flags = 0 );
 247
 248     /**
 249         Two step creation. Whenever the control is created without any parameters,
 250         use Create to actually create it. Don't access the control's public methods
 251         before this is called.
 252
 253         @see @ref propgrid_window_styles
 254     */
 255     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 256                  const wxPoint& pos = wxDefaultPosition,
 257                  const wxSize& size = wxDefaultSize,
 258                  long style = wxPGMAN_DEFAULT_STYLE,
 259                  const wxChar* name = wxPropertyGridManagerNameStr );
 260
 261     /**
 262         Enables or disables (shows/hides) categories according to parameter enable.
 263
 264         @remarks
 265             Calling his may not properly update toolbar buttons.
 266     */
 267     bool EnableCategories( bool enable );
 268
 269     /**
 270         Selects page, scrolls and/or expands items to ensure that the
 271         given item is visible.
 272
 273         @return Returns @true if something was actually done.
 274     */
 275     bool EnsureVisible( wxPGPropArg id );
 276
 277     /**
 278         Returns number of columns on given page. By the default,
 279         returns number of columns on current page.
 280     */
 281     int GetColumnCount( int page = -1 ) const;
 282
 283     /**
 284         Returns height of the description text box.
 285     */
 286     int GetDescBoxHeight() const;
 287
 288     /**
 289         Returns pointer to the contained wxPropertyGrid. This does not change
 290         after wxPropertyGridManager has been created, so you can safely obtain
 291         pointer once and use it for the entire lifetime of the manager
 292         instance.
 293     */
 294     wxPropertyGrid* GetGrid();
 295
 296     /**
 297         Similar to GetIterator, but instead returns wxPGVIterator instance,
 298         which can be useful for forward-iterating through arbitrary property
 299         containers.
 300     */
 301     virtual wxPGVIterator GetVIterator( int flags ) const;
 302
 303     /**
 304         Returns currently selected page.
 305     */
 306     wxPropertyGridPage* GetCurrentPage() const;
 307
 308     /**
 309         Returns page object for given page index.
 310     */
 311     wxPropertyGridPage* GetPage( unsigned int ind ) const;
 312
 313     /**
 314         Returns page object for given page name.
 315     */
 316     wxPropertyGridPage* GetPage( const wxString& name ) const;
 317
 318     /**
 319         Returns index for a page name. If no match is found, wxNOT_FOUND is
 320         returned.
 321     */
 322     int GetPageByName( const wxString& name ) const;
 323
 324     /**
 325         Returns number of managed pages.
 326     */
 327     size_t GetPageCount() const;
 328
 329     /**
 330         Returns name of given page.
 331     */
 332     const wxString& GetPageName( int index ) const;
 333
 334     /**
 335         Returns "root property" of the given page. It does not have name, etc.
 336         and it is not visible. It is only useful for accessing its children.
 337     */
 338     wxPGProperty* GetPageRoot( int index ) const;
 339
 340     /** Returns index to currently selected page. */
 341     int GetSelectedPage() const;
 342
 343     /** Shortcut for GetGrid()->GetSelection(). */
 344     wxPGProperty* GetSelectedProperty() const;
 345
 346     /** Synonyme for GetSelectedPage. */
 347     int GetSelection() const;
 348
 349     /**
 350         Returns a pointer to the toolbar currently associated with the
 351         wxPropertyGridManager (if any).
 352     */
 353     wxToolBar* GetToolBar() const;
 354
 355     /**
 356         Creates new property page. Note that the first page is not created
 357         automatically.
 358
 359         @param index
 360             Add to this position. -1 will add as the last item.
 361
 362         @param label
 363             A label for the page. This may be shown as a toolbar tooltip etc.
 364
 365         @param bmp
 366             Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 367             default image is used.
 368
 369         @param pageObj
 370             wxPropertyGridPage instance. Manager will take ownership of this
 371             object. If NULL, default page object is constructed.
 372
 373         @return Returns pointer to created page.
 374     */
 375     virtual wxPropertyGridPage* InsertPage( int index, const wxString& label,
 376                                             const wxBitmap& bmp = wxNullBitmap,
 377                                             wxPropertyGridPage* pageObj = NULL );
 378
 379     /**
 380         Returns @true if any property on any page has been modified by the user.
 381     */
 382     bool IsAnyModified() const;
 383
 384     /**
 385         Returns @true if updating is frozen (ie. Freeze() called but not yet Thaw() ).
 386     */
 387     bool IsFrozen() const;
 388
 389     /**
 390         Returns @true if any property on given page has been modified by the user.
 391     */
 392     bool IsPageModified( size_t index ) const;
 393
 394     /**
 395         Returns true if property is selected. Since selection is page
 396         based, this function checks every page in the manager.
 397     */
 398     virtual bool IsPropertySelected( wxPGPropArg id ) const;
 399
 400     /**
 401         Removes a page.
 402
 403         @return Returns @false if it was not possible to remove page in question.
 404     */
 405     virtual bool RemovePage( int page );
 406
 407     /**
 408         Select and displays a given page.
 409
 410         @param index
 411             Index of page being seleced. Can be -1 to select nothing.
 412     */
 413     void SelectPage( int index );
 414
 415     /**
 416         Select and displays a given page (by label).
 417     */
 418     void SelectPage( const wxString& label );
 419
 420     /** Select and displays a given page. */
 421     void SelectPage( wxPropertyGridPage* page );
 422
 423     /**
 424         Select a property.
 425
 426         @see wxPropertyGrid::SelectProperty(),
 427              wxPropertyGridInterface::ClearSelection()
 428     */
 429     bool SelectProperty( wxPGPropArg id, bool focus = false );
 430
 431     /**
 432         Sets number of columns on given page (default is current page).
 433
 434         @remarks If you use header, then you should always use this
 435                  member function to set the column count, instead of
 436                  ones present in wxPropertyGrid or wxPropertyGridPage.
 437     */
 438     void SetColumnCount( int colCount, int page = -1 );
 439
 440     /**
 441         Sets a column title. Default title for column 0 is "Property",
 442         and "Value" for column 1.
 443
 444         @remarks If header is not shown yet, then calling this
 445                  member function will make it visible.
 446     */
 447     void SetColumnTitle( int idx, const wxString& title );
 448
 449     /**
 450         Sets label and text in description box.
 451     */
 452     void SetDescription( const wxString& label, const wxString& content );
 453
 454     /** Sets y coordinate of the description box splitter. */
 455     void SetDescBoxHeight( int ht, bool refresh = true );
 456
 457     /**
 458         Moves splitter as left as possible, while still allowing all
 459         labels to be shown in full.
 460
 461         @param subProps
 462             If @false, will still allow sub-properties (ie. properties which
 463             parent is not root or category) to be cropped.
 464
 465         @param allPages
 466             If @true, takes labels on all pages into account.
 467     */
 468     void SetSplitterLeft( bool subProps = false, bool allPages = true );
 469
 470     /**
 471         Sets splitter position on individual page.
 472
 473         @remarks If you use header, then you should always use this
 474                  member function to set the splitter position, instead of
 475                  ones present in wxPropertyGrid or wxPropertyGridPage.
 476     */
 477     void SetPageSplitterPosition( int page, int pos, int column = 0 );
 478
 479     /**
 480         Sets splitter position for all pages.
 481
 482         @remarks Splitter position cannot exceed grid size, and therefore
 483                  setting it during form creation may fail as initial grid
 484                  size is often smaller than desired splitter position,
 485                  especially when sizers are being used.
 486
 487                  If you use header, then you should always use this
 488                  member function to set the splitter position, instead of
 489                  ones present in wxPropertyGrid or wxPropertyGridPage.
 490     */
 491     void SetSplitterPosition( int pos, int column = 0 );
 492
 493     /** Synonyme for SelectPage(name). */
 494     void SetStringSelection( const wxChar* name );
 495
 496     /**
 497         Show or hide the property grid header control. It is hidden
 498         by the default.
 499
 500         @remarks Grid may look better if you use wxPG_NO_INTERNAL_BORDER
 501                  window style when showing a header.
 502     */
 503     void ShowHeader(bool show = true);
 504
 505 protected:
 506
 507     //
 508     // Subclassing helpers
 509     //
 510
 511     /**
 512         Creates property grid for the manager. Reimplement in derived class to
 513         use subclassed wxPropertyGrid. However, if you  do this then you
 514         must also use the two-step construction (i.e. default constructor and
 515         Create() instead of constructor with arguments) when creating the
 516         manager.
 517     */
 518     virtual wxPropertyGrid* CreatePropertyGrid() const;
 519 };