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         page = pgMan->AddPage(wxT("First Page"));
 175
 176         page->Append( new wxPropertyCategory(wxT("Category A1")) );
 177
 178         page->Append( new wxIntProperty(wxT("Number"),wxPG_LABEL,1) );
 179
 180         page->Append( new wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );
 181
 182         page = pgMan->AddPage(wxT("Second Page"));
 183
 184         page->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );
 185
 186         page->Append( new wxFontProperty(wxT("Font"),wxPG_LABEL) );
 187
 188     @endcode
 189
 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     void ClearModifiedStatus( wxPGPropArg id );
 232
 233     void ClearModifiedStatus()
 234     {
 235         m_pPropGrid->ClearModifiedStatus();
 236     }
 237
 238     /**
 239         Deletes all properties and all pages.
 240     */
 241     virtual void Clear();
 242
 243     /**
 244         Deletes all properties on given page.
 245     */
 246     void ClearPage( int page );
 247
 248     /**
 249         Forces updating the value of property from the editor control.
 250
 251         @return Returns @true if value was actually updated.
 252     */
 253     bool CommitChangesFromEditor( wxUint32 flags = 0 )
 254     {
 255         return m_pPropGrid->CommitChangesFromEditor(flags);
 256     }
 257
 258     /**
 259         Two step creation. Whenever the control is created without any parameters,
 260         use Create to actually create it. Don't access the control's public methods
 261         before this is called.
 262
 263         @see @ref propgrid_window_styles
 264     */
 265     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 266                  const wxPoint& pos = wxDefaultPosition,
 267                  const wxSize& size = wxDefaultSize,
 268                  long style = wxPGMAN_DEFAULT_STYLE,
 269                  const wxChar* name = wxPropertyGridManagerNameStr );
 270
 271     /**
 272         Enables or disables (shows/hides) categories according to parameter enable.
 273
 274         @remarks
 275             Calling his may not properly update toolbar buttons.
 276     */
 277     bool EnableCategories( bool enable )
 278     {
 279         long fl = m_windowStyle | wxPG_HIDE_CATEGORIES;
 280         if ( enable ) fl = m_windowStyle & ~(wxPG_HIDE_CATEGORIES);
 281         SetWindowStyleFlag(fl);
 282         return true;
 283     }
 284
 285     /**
 286         Selects page, scrolls and/or expands items to ensure that the
 287         given item is visible.
 288
 289         @return Returns @true if something was actually done.
 290     */
 291     bool EnsureVisible( wxPGPropArg id );
 292
 293     /**
 294         Returns number of children of the root property of the selected page.
 295     */
 296     size_t GetChildrenCount()
 297     {
 298         return GetChildrenCount( m_pPropGrid->m_pState->m_properties );
 299     }
 300
 301     /**
 302         Returns number of children of the root property of given page.
 303     */
 304     size_t GetChildrenCount( int pageIndex );
 305
 306     /**
 307         Returns number of children for the property.
 308
 309         NB: Cannot be in container methods class due to name hiding.
 310     */
 311     size_t GetChildrenCount( wxPGPropArg id ) const
 312     {
 313         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
 314         return p->GetChildCount();
 315     }
 316
 317     /**
 318         Returns number of columns on given page. By the default,
 319         returns number of columns on current page.
 320     */
 321     int GetColumnCount( int page = -1 ) const;
 322
 323     /**
 324         Returns height of the description text box.
 325     */
 326     int GetDescBoxHeight() const;
 327
 328     /**
 329         Returns pointer to the contained wxPropertyGrid. This does not change
 330         after wxPropertyGridManager has been created, so you can safely obtain
 331         pointer once and use it for the entire lifetime of the manager
 332         instance.
 333     */
 334     wxPropertyGrid* GetGrid();
 335
 336     /**
 337         Similar to GetIterator, but instead returns wxPGVIterator instance,
 338         which can be useful for forward-iterating through arbitrary property
 339         containers.
 340     */
 341     virtual wxPGVIterator GetVIterator( int flags ) const;
 342
 343     /**
 344         Returns currently selected page.
 345     */
 346     wxPropertyGridPage* GetCurrentPage() const;
 347
 348     /**
 349         Returns page object for given page index.
 350     */
 351     wxPropertyGridPage* GetPage( unsigned int ind ) const
 352     {
 353         return (wxPropertyGridPage*)m_arrPages.Item(ind);
 354     }
 355
 356     /**
 357         Returns page object for given page name.
 358     */
 359     wxPropertyGridPage* GetPage( const wxString& name ) const
 360     {
 361         return GetPage(GetPageByName(name));
 362     }
 363
 364     /**
 365         Returns index for a page name. If no match is found, wxNOT_FOUND is
 366         returned.
 367     */
 368     int GetPageByName( const wxString& name ) const;
 369
 370     /**
 371         Returns number of managed pages.
 372     */
 373     size_t GetPageCount() const;
 374
 375     /** Returns name of given page. */
 376     const wxString& GetPageName( int index ) const;
 377
 378     /**
 379         Returns "root property" of the given page. It does not have name, etc.
 380         and it is not visible. It is only useful for accessing its children.
 381     */
 382     wxPGProperty* GetPageRoot( int index ) const;
 383
 384     /** Returns index to currently selected page. */
 385     int GetSelectedPage() const { return m_selPage; }
 386
 387     /** Shortcut for GetGrid()->GetSelection(). */
 388     wxPGProperty* GetSelectedProperty() const
 389     {
 390         return m_pPropGrid->GetSelection();
 391     }
 392
 393     /** Synonyme for GetSelectedPage. */
 394     int GetSelection() const { return m_selPage; }
 395
 396     /**
 397         Returns a pointer to the toolbar currently associated with the
 398         wxPropertyGridManager (if any).
 399     */
 400     wxToolBar* GetToolBar() const { return m_pToolbar; }
 401
 402     /** Creates new property page. Note that the first page is not created
 403         automatically.
 404
 405         @param index
 406             Add to this position. -1 will add as the last item.
 407
 408         @param label
 409             A label for the page. This may be shown as a toolbar tooltip etc.
 410
 411         @param bmp
 412             Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
 413             default image is used.
 414
 415         @param pageObj
 416             wxPropertyGridPage instance. Manager will take ownership of this
 417             object. If NULL, default page object is constructed.
 418
 419         @return Returns pointer to created page.
 420     */
 421     virtual wxPropertyGridPage* InsertPage( int index, const wxString& label,
 422                                             const wxBitmap& bmp = wxNullBitmap,
 423                                             wxPropertyGridPage* pageObj = NULL );
 424
 425     /**
 426         Returns @true if any property on any page has been modified by the user.
 427     */
 428     bool IsAnyModified() const;
 429
 430     /**
 431         Returns @true if updating is frozen (ie. Freeze() called but not yet
 432         Thaw() ).
 433     */
 434     bool IsFrozen() const;
 435
 436     /**
 437         Returns @true if any property on given page has been modified by the user.
 438     */
 439     bool IsPageModified( size_t index ) const;
 440
 441     /** Removes a page.
 442
 443         @return Returns @false if it was not possible to remove page in question.
 444     */
 445     virtual bool RemovePage( int page );
 446
 447     /** Select and displays a given page.
 448
 449         @param index
 450             Index of page being seleced. Can be -1 to select nothing.
 451     */
 452     void SelectPage( int index );
 453
 454     /**
 455         Select and displays a given page (by label).
 456     */
 457     void SelectPage( const wxString& label );
 458
 459     /** Select and displays a given page. */
 460     void SelectPage( wxPropertyGridPage* page );
 461
 462     /** Select a property. */
 463     bool SelectProperty( wxPGPropArg id, bool focus = false );
 464
 465     /**
 466         Sets number of columns on given page (default is current page).
 467     */
 468     void SetColumnCount( int colCount, int page = -1 );
 469
 470     /** Sets label and text in description box.
 471     */
 472     void SetDescription( const wxString& label, const wxString& content );
 473
 474     /** Sets y coordinate of the description box splitter. */
 475     void SetDescBoxHeight( int ht, bool refresh = true );
 476
 477     /** Moves splitter as left as possible, while still allowing all
 478         labels to be shown in full.
 479
 480         @param subProps
 481             If @false, will still allow sub-properties (ie. properties which
 482             parent is not root or category) to be cropped.
 483
 484         @param allPages
 485             If @true, takes labels on all pages into account.
 486     */
 487     void SetSplitterLeft( bool subProps = false, bool allPages = true );
 488
 489     /** Sets splitter position on individual page. */
 490     void SetPageSplitterPosition( int page, int pos, int column = 0 )
 491     {
 492         GetPage(page)->DoSetSplitterPosition( pos, column );
 493     }
 494
 495     /**
 496         Sets splitter position for all pages.
 497
 498         @remarks Splitter position cannot exceed grid size, and therefore setting
 499                 it during form creation may fail as initial grid size is often
 500                 smaller than desired splitter position, especially when sizers
 501                 are being used.
 502     */
 503     void SetSplitterPosition( int pos, int column = 0 );
 504
 505     /** Synonyme for SelectPage(name). */
 506     void SetStringSelection( const wxChar* name )
 507     {
 508         SelectPage( GetPageByName(name) );
 509     }
 510
 511 protected:
 512
 513     //
 514     // Subclassing helpers
 515     //
 516
 517     /**
 518         Creates property grid for the manager. Override to use subclassed
 519         wxPropertyGrid.
 520     */
 521     virtual wxPropertyGrid* CreatePropertyGrid() const;
 522 };
 523
 524 // -----------------------------------------------------------------------