1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPropertyGridManager
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxPropertyGridPage
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.
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.
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.
27 @section propgridpage_event_handling Event Handling
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.
34 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
40 class WXDLLIMPEXP_PROPGRID wxPropertyGridPage
: public wxEvtHandler
,
41 public wxPropertyGridInterface
43 friend class wxPropertyGridManager
;
47 virtual ~wxPropertyGridPage();
50 Deletes all properties on page.
55 Reduces column sizes to minimum possible that contents are still visibly
56 (naturally some margin space will be applied as well).
58 @return Returns minimum size for the page to still display everything.
60 @remarks This function only works properly if size of containing grid was
63 Note that you can also get calculated column widths by calling
64 GetColumnWidth() immediately after this function returns.
69 Returns page index in manager;
71 inline int GetIndex() const;
74 Returns "root property". It does not have name, etc. and it is not
75 visible. It is only useful for accessing its children.
77 wxPGProperty
* GetRoot() const;
80 Returns x-coordinate position of splitter on a page.
82 int GetSplitterPosition( int col
= 0 ) const;
85 Returns id of the tool bar item that represents this page on
86 wxPropertyGridManager's wxToolBar.
88 int GetToolId() const;
91 Do any member initialization in this method.
93 @remarks - Called every time the page is added into a manager.
94 - You can add properties to the page here.
99 Return false here to indicate unhandled events should be
100 propagated to manager's parent, as normal.
102 virtual bool IsHandlingAllEvents() const;
105 Called every time page is about to be shown.
106 Useful, for instance, creating properties just-in-time.
108 virtual void OnShow();
111 Refreshes given property on page.
113 virtual void RefreshProperty( wxPGProperty
* p
);
116 Sets splitter position on page.
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.
123 void SetSplitterPosition( int splitterPos
, int col
= 0 );
128 @class wxPropertyGridManager
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
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.
139 To operate explicitly on properties on specific page, use
140 wxPropertyGridManager::GetPage() to obtain pointer to page's
141 wxPropertyGridPage object.
143 Visual methods, such as SetCellBackgroundColour() are only available in
144 wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain pointer to it.
146 Non-virtual iterators will not work in wxPropertyGridManager. Instead, you must
147 acquire the internal grid (GetGrid()) or wxPropertyGridPage object (GetPage()).
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).
153 Here's some example code for creating and populating a wxPropertyGridManager:
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|
163 // Include description box.
165 // Include compactor.
168 wxPGMAN_DEFAULT_STYLE
171 wxPropertyGridPage* page;
173 page = pgMan->AddPage("First Page");
175 page->Append( new wxPropertyCategory("Category A1") );
177 page->Append( new wxIntProperty("Number",wxPG_LABEL,1) );
179 page->Append( new wxColourProperty("Colour",wxPG_LABEL,*wxWHITE) );
181 page = pgMan->AddPage("Second Page");
183 page->Append( "Text",wxPG_LABEL,"(no text)" );
185 page->Append( new wxFontProperty("Font",wxPG_LABEL) );
188 @section propgridmanager_window_styles_ Window Styles
190 See @ref propgrid_window_styles.
192 @section propgridmanager_event_handling Event Handling
194 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
195 for more information.
200 class wxPropertyGridManager
: public wxPanel
, public wxPropertyGridInterface
204 Creates new property page. Note that the first page is not created
208 A label for the page. This may be shown as a toolbar tooltip etc.
211 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
212 default image is used.
215 wxPropertyGridPage instance. Manager will take ownership of this
216 object. NULL indicates that a default page instance should be created.
218 @return Returns pointer to created property grid page.
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.
224 wxPropertyGridPage
* AddPage( const wxString
& label
= wxEmptyString
,
225 const wxBitmap
& bmp
= wxPG_NULL_BITMAP
,
226 wxPropertyGridPage
* pageObj
= NULL
);
229 Deletes all properties and all pages.
231 virtual void Clear();
234 Deletes all properties on given page.
236 void ClearPage( int page
);
239 Forces updating the value of property from the editor control.
241 @return Returns @true if value was actually updated.
243 bool CommitChangesFromEditor( wxUint32 flags
= 0 );
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.
250 @see @ref propgrid_window_styles
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
);
259 Enables or disables (shows/hides) categories according to parameter enable.
262 Calling his may not properly update toolbar buttons.
264 bool EnableCategories( bool enable
);
267 Selects page, scrolls and/or expands items to ensure that the
268 given item is visible.
270 @return Returns @true if something was actually done.
272 bool EnsureVisible( wxPGPropArg id
);
275 Returns number of columns on given page. By the default,
276 returns number of columns on current page.
278 int GetColumnCount( int page
= -1 ) const;
281 Returns height of the description text box.
283 int GetDescBoxHeight() const;
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
291 wxPropertyGrid
* GetGrid();
294 Similar to GetIterator, but instead returns wxPGVIterator instance,
295 which can be useful for forward-iterating through arbitrary property
298 virtual wxPGVIterator
GetVIterator( int flags
) const;
301 Returns currently selected page.
303 wxPropertyGridPage
* GetCurrentPage() const;
306 Returns page object for given page index.
308 wxPropertyGridPage
* GetPage( unsigned int ind
) const;
311 Returns page object for given page name.
313 wxPropertyGridPage
* GetPage( const wxString
& name
) const;
316 Returns index for a page name. If no match is found, wxNOT_FOUND is
319 int GetPageByName( const wxString
& name
) const;
322 Returns number of managed pages.
324 size_t GetPageCount() const;
327 Returns name of given page.
329 const wxString
& GetPageName( int index
) const;
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.
335 wxPGProperty
* GetPageRoot( int index
) const;
337 /** Returns index to currently selected page. */
338 int GetSelectedPage() const;
340 /** Shortcut for GetGrid()->GetSelection(). */
341 wxPGProperty
* GetSelectedProperty() const;
343 /** Synonyme for GetSelectedPage. */
344 int GetSelection() const;
347 Returns a pointer to the toolbar currently associated with the
348 wxPropertyGridManager (if any).
350 wxToolBar
* GetToolBar() const;
353 Creates new property page. Note that the first page is not created
357 Add to this position. -1 will add as the last item.
360 A label for the page. This may be shown as a toolbar tooltip etc.
363 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
364 default image is used.
367 wxPropertyGridPage instance. Manager will take ownership of this
368 object. If NULL, default page object is constructed.
370 @return Returns pointer to created page.
372 virtual wxPropertyGridPage
* InsertPage( int index
, const wxString
& label
,
373 const wxBitmap
& bmp
= wxNullBitmap
,
374 wxPropertyGridPage
* pageObj
= NULL
);
377 Returns @true if any property on any page has been modified by the user.
379 bool IsAnyModified() const;
382 Returns @true if updating is frozen (ie. Freeze() called but not yet Thaw() ).
384 bool IsFrozen() const;
387 Returns @true if any property on given page has been modified by the user.
389 bool IsPageModified( size_t index
) const;
394 @return Returns @false if it was not possible to remove page in question.
396 virtual bool RemovePage( int page
);
399 Select and displays a given page.
402 Index of page being seleced. Can be -1 to select nothing.
404 void SelectPage( int index
);
407 Select and displays a given page (by label).
409 void SelectPage( const wxString
& label
);
411 /** Select and displays a given page. */
412 void SelectPage( wxPropertyGridPage
* page
);
417 @see wxPropertyGrid::SelectProperty(),
418 wxPropertyGridInterface::ClearSelection()
420 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
423 Sets number of columns on given page (default is current page).
425 void SetColumnCount( int colCount
, int page
= -1 );
428 Sets label and text in description box.
430 void SetDescription( const wxString
& label
, const wxString
& content
);
432 /** Sets y coordinate of the description box splitter. */
433 void SetDescBoxHeight( int ht
, bool refresh
= true );
436 Moves splitter as left as possible, while still allowing all
437 labels to be shown in full.
440 If @false, will still allow sub-properties (ie. properties which
441 parent is not root or category) to be cropped.
444 If @true, takes labels on all pages into account.
446 void SetSplitterLeft( bool subProps
= false, bool allPages
= true );
448 /** Sets splitter position on individual page. */
449 void SetPageSplitterPosition( int page
, int pos
, int column
= 0 );
452 Sets splitter position for all pages.
454 @remarks Splitter position cannot exceed grid size, and therefore setting
455 it during form creation may fail as initial grid size is often
456 smaller than desired splitter position, especially when sizers
459 void SetSplitterPosition( int pos
, int column
= 0 );
461 /** Synonyme for SelectPage(name). */
462 void SetStringSelection( const wxChar
* name
);
467 // Subclassing helpers
471 Creates property grid for the manager. Reimplement in derived class to
472 use subclassed wxPropertyGrid. However, if you you do this then you
473 must also use the two-step construction (ie. default constructor and
474 Create() instead of constructor with arguments) when creating the
477 virtual wxPropertyGrid
* CreatePropertyGrid() const;