interface/wx/propgrid/manager.h

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