1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/propgrid/manager.h
3 // Purpose: wxPropertyGridManager
4 // Author: Jaakko Salli
8 // Copyright: (c) Jaakko Salli
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_PROPGRID_MANAGER_H_
13 #define _WX_PROPGRID_MANAGER_H_
15 #include "wx/propgrid/propgrid.h"
17 #include "wx/dcclient.h"
18 #include "wx/scrolwin.h"
19 #include "wx/toolbar.h"
20 #include "wx/stattext.h"
21 #include "wx/button.h"
22 #include "wx/textctrl.h"
23 #include "wx/dialog.h"
25 // -----------------------------------------------------------------------
28 extern WXDLLIMPEXP_PROPGRID
const wxChar
*wxPropertyGridManagerNameStr
;
31 /** @class wxPropertyGridPage
33 Holder of property grid page information. You can subclass this and
34 give instance in wxPropertyGridManager::AddPage. It inherits from
35 wxEvtHandler and can be used to process events specific to this
36 page (id of events will still be same as manager's). If you don't
37 want to use it to process all events of the page, you need to
38 return false in the derived wxPropertyGridPage::IsHandlingAllEvents.
40 Please note that wxPropertyGridPage lacks many non-const property
41 manipulation functions found in wxPropertyGridManager. Please use
42 parent manager (m_manager member variable) when needed.
44 Please note that most member functions are inherited and as such not
45 documented on this page. This means you will probably also want to read
46 wxPropertyGridInterface class reference.
48 @section propgridpage_event_handling Event Handling
50 wxPropertyGridPage receives events emitted by its wxPropertyGridManager, but
51 only those events that are specific to that page. If
52 wxPropertyGridPage::IsHandlingAllEvents returns false, then unhandled
53 events are sent to the manager's parent, as usual.
55 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
61 class WXDLLIMPEXP_PROPGRID wxPropertyGridPage
: public wxEvtHandler
,
62 public wxPropertyGridInterface
,
63 public wxPropertyGridPageState
65 friend class wxPropertyGridManager
;
67 DECLARE_CLASS(wxPropertyGridPage
)
72 virtual ~wxPropertyGridPage();
74 /** Deletes all properties on page.
79 Reduces column sizes to minimum possible that contents are still
80 visibly (naturally some margin space will be applied as well).
83 Minimum size for the page to still display everything.
86 This function only works properly if size of containing grid was
89 Note that you can also get calculated column widths by calling
90 GetColumnWidth() immediately after this function returns.
94 /** Returns page index in manager;
96 inline int GetIndex() const;
98 /** Returns x-coordinate position of splitter on a page.
100 int GetSplitterPosition( int col
= 0 ) const
101 { return GetStatePtr()->DoGetSplitterPosition(col
); }
103 /** Returns "root property". It does not have name, etc. and it is not
104 visible. It is only useful for accessing its children.
106 wxPGProperty
* GetRoot() const { return GetStatePtr()->DoGetRoot(); }
108 /** Return pointer to contained property grid state.
110 wxPropertyGridPageState
* GetStatePtr()
115 /** Return pointer to contained property grid state.
117 const wxPropertyGridPageState
* GetStatePtr() const
123 Returns id of the tool bar item that represents this page on
124 wxPropertyGridManager's wxToolBar.
126 int GetToolId() const
131 /** Do any member initialization in this method.
133 - Called every time the page is added into a manager.
134 - You can add properties to the page here.
136 virtual void Init() {}
138 /** Return false here to indicate unhandled events should be
139 propagated to manager's parent, as normal.
141 virtual bool IsHandlingAllEvents() const { return true; }
143 /** Called every time page is about to be shown.
144 Useful, for instance, creating properties just-in-time.
146 virtual void OnShow();
148 virtual void RefreshProperty( wxPGProperty
* p
);
150 /** Sets splitter position on page.
152 Splitter position cannot exceed grid size, and therefore setting it
153 during form creation may fail as initial grid size is often smaller
154 than desired splitter position, especially when sizers are being used.
156 void SetSplitterPosition( int splitterPos
, int col
= 0 );
160 /** Propagate to other pages.
162 virtual void DoSetSplitterPosition( int pos
,
163 int splitterColumn
= 0,
164 bool allPages
= false );
166 /** Propagate to other pages.
168 void DoSetSplitterPositionThisPage( int pos
, int splitterColumn
= 0 )
170 wxPropertyGridPageState::DoSetSplitterPosition( pos
, splitterColumn
);
173 /** Page label (may be referred as name in some parts of documentation).
174 Can be set in constructor, or passed in
175 wxPropertyGridManager::AddPage(), but *not* in both.
181 //virtual bool ProcessEvent( wxEvent& event );
183 wxPropertyGridManager
* m_manager
;
185 int m_id
; // toolbar index
188 bool m_isDefault
; // is this base page object?
191 DECLARE_EVENT_TABLE()
195 // -----------------------------------------------------------------------
197 /** @class wxPropertyGridManager
199 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
200 which can optionally have toolbar for mode and page selection, and help
202 Use window flags to select components to include.
204 @section propgridmanager_window_styles_ Window Styles
206 See @ref propgrid_window_styles.
208 @section propgridmanager_event_handling Event Handling
210 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
211 for more information.
216 class WXDLLIMPEXP_PROPGRID
217 wxPropertyGridManager
: public wxPanel
, public wxPropertyGridInterface
220 DECLARE_CLASS(wxPropertyGridManager
)
222 friend class wxPropertyGridPage
;
226 %pythonAppend wxPropertyGridManager
{
227 self
._setOORInfo(self
)
228 self
.DoDefaultTypeMappings()
229 self
.edited_objects
= {}
230 self
.DoDefaultValueTypeMappings()
231 if not hasattr(self
.__class__
,'_vt2setter'):
232 self
.__class__
._vt2setter
= {}
234 %pythonAppend
wxPropertyGridManager() ""
236 wxPropertyGridManager( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
237 const wxPoint
& pos
= wxDefaultPosition
,
238 const wxSize
& size
= wxDefaultSize
,
239 long style
= wxPGMAN_DEFAULT_STYLE
,
241 wxPyPropertyGridManagerNameStr
);
242 %RenameCtor
(PrePropertyGridManager
, wxPropertyGridManager());
247 Two step constructor.
248 Call Create when this constructor is called to build up the
249 wxPropertyGridManager.
251 wxPropertyGridManager();
253 /** The default constructor. The styles to be used are styles valid for
255 @see @link wndflags Additional Window Styles@endlink
257 wxPropertyGridManager( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
258 const wxPoint
& pos
= wxDefaultPosition
,
259 const wxSize
& size
= wxDefaultSize
,
260 long style
= wxPGMAN_DEFAULT_STYLE
,
261 const wxChar
* name
= wxPropertyGridManagerNameStr
);
264 virtual ~wxPropertyGridManager();
268 /** Creates new property page. Note that the first page is not created
271 A label for the page. This may be shown as a toolbar tooltip etc.
273 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
274 default image is used.
276 wxPropertyGridPage instance. Manager will take ownership of this object.
277 NULL indicates that a default page instance should be created.
279 Returns index to the page created.
281 If toolbar is used, it is highly recommended that the pages are
282 added when the toolbar is not turned off using window style flag
285 int AddPage( const wxString
& label
= wxEmptyString
,
286 const wxBitmap
& bmp
= wxPG_NULL_BITMAP
,
287 wxPropertyGridPage
* pageObj
= (wxPropertyGridPage
*) NULL
)
289 return InsertPage(-1,label
,bmp
,pageObj
);
292 void ClearModifiedStatus ( wxPGPropArg id
);
294 void ClearModifiedStatus ()
296 m_pPropGrid
->ClearModifiedStatus();
299 /** Deletes all all properties and all pages.
301 virtual void Clear();
303 /** Deletes all properties on given page.
305 void ClearPage( int page
);
307 /** Forces updating the value of property from the editor control.
308 Returns true if DoPropertyChanged was actually called.
310 bool CommitChangesFromEditor( wxUint32 flags
= 0 )
312 return m_pPropGrid
->CommitChangesFromEditor(flags
);
317 Whenever the control is created without any parameters, use Create to
318 actually create it. Don't access the control's public methods before
320 @see @link wndflags Additional Window Styles@endlink
322 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
323 const wxPoint
& pos
= wxDefaultPosition
,
324 const wxSize
& size
= wxDefaultSize
,
325 long style
= wxPGMAN_DEFAULT_STYLE
,
326 const wxChar
* name
= wxPropertyGridManagerNameStr
);
329 Enables or disables (shows/hides) categories according to parameter
332 WARNING: Not tested properly, use at your own risk.
334 bool EnableCategories( bool enable
)
336 long fl
= m_windowStyle
| wxPG_HIDE_CATEGORIES
;
337 if ( enable
) fl
= m_windowStyle
& ~(wxPG_HIDE_CATEGORIES
);
338 SetWindowStyleFlag(fl
);
342 /** Selects page, scrolls and/or expands items to ensure that the
343 given item is visible. Returns true if something was actually done.
345 bool EnsureVisible( wxPGPropArg id
);
347 /** Returns number of children of the root property of the selected page. */
348 size_t GetChildrenCount()
350 return GetChildrenCount( m_pPropGrid
->m_pState
->m_properties
);
353 /** Returns number of children of the root property of given page. */
354 size_t GetChildrenCount( int pageIndex
);
356 /** Returns number of children for the property.
358 NB: Cannot be in container methods class due to name hiding.
360 size_t GetChildrenCount( wxPGPropArg id
) const
362 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
363 return p
->GetChildCount();
366 /** Returns number of columns on given page. By the default,
367 returns number of columns on current page. */
368 int GetColumnCount( int page
= -1 ) const;
370 /** Returns height of the description text box. */
371 int GetDescBoxHeight() const;
373 /** Returns pointer to the contained wxPropertyGrid. This does not change
374 after wxPropertyGridManager has been created, so you can safely obtain
375 pointer once and use it for the entire lifetime of the instance.
377 wxPropertyGrid
* GetGrid()
379 wxASSERT(m_pPropGrid
);
383 const wxPropertyGrid
* GetGrid() const
385 wxASSERT(m_pPropGrid
);
386 return (const wxPropertyGrid
*)m_pPropGrid
;
389 /** Returns iterator class instance.
391 Calling this method in wxPropertyGridManager causes run-time assertion
392 failure. Please only iterate through individual pages or use
395 wxPropertyGridIterator
GetIterator( int flags
= wxPG_ITERATE_DEFAULT
,
396 wxPGProperty
* firstProp
= NULL
)
398 wxFAIL_MSG( "Please only iterate through individual pages "
399 "or use CreateVIterator()" );
400 return wxPropertyGridInterface::GetIterator( flags
, firstProp
);
403 wxPropertyGridConstIterator
404 GetIterator(int flags
= wxPG_ITERATE_DEFAULT
,
405 wxPGProperty
* firstProp
= NULL
) const
407 wxFAIL_MSG( "Please only iterate through individual pages "
408 " or use CreateVIterator()" );
409 return wxPropertyGridInterface::GetIterator( flags
, firstProp
);
412 /** Returns iterator class instance.
414 Calling this method in wxPropertyGridManager causes run-time assertion
415 failure. Please only iterate through individual pages or use
418 wxPropertyGridIterator
GetIterator( int flags
, int startPos
)
420 wxFAIL_MSG( "Please only iterate through individual pages "
421 "or use CreateVIterator()" );
423 return wxPropertyGridInterface::GetIterator( flags
, startPos
);
426 wxPropertyGridConstIterator
GetIterator( int flags
, int startPos
) const
428 wxFAIL_MSG( "Please only iterate through individual pages "
429 "or use CreateVIterator()" );
430 return wxPropertyGridInterface::GetIterator( flags
, startPos
);
433 /** Similar to GetIterator, but instead returns wxPGVIterator instance,
434 which can be useful for forward-iterating through arbitrary property
437 virtual wxPGVIterator
GetVIterator( int flags
) const;
439 /** Returns currently selected page.
441 wxPropertyGridPage
* GetCurrentPage() const
443 return GetPage(m_selPage
);
446 /** Returns last page.
448 wxPropertyGridPage
* GetLastPage() const
450 return GetPage(m_arrPages
.size()-1);
453 /** Returns page object for given page index.
455 wxPropertyGridPage
* GetPage( unsigned int ind
) const
457 return (wxPropertyGridPage
*)m_arrPages
.Item(ind
);
460 /** Returns page object for given page name.
462 wxPropertyGridPage
* GetPage( const wxString
& name
) const
464 return GetPage(GetPageByName(name
));
468 Returns index for a page name.
470 If no match is found, wxNOT_FOUND is returned.
472 int GetPageByName( const wxString
& name
) const;
474 /** Returns index for a relevant propertygrid state.
476 If no match is found, wxNOT_FOUND is returned.
478 int GetPageByState( const wxPropertyGridPageState
* pstate
) const;
480 /** Returns wxPropertyGridPageState of given page, current page's for -1.
482 virtual wxPropertyGridPageState
* GetPageState( int page
) const;
484 /** Returns number of managed pages. */
485 size_t GetPageCount() const;
487 /** Returns name of given page. */
488 const wxString
& GetPageName( int index
) const;
490 /** Returns "root property" of the given page. It does not have name, etc.
491 and it is not visible. It is only useful for accessing its children.
493 wxPGProperty
* GetPageRoot( int index
) const;
495 /** Returns index to currently selected page. */
496 int GetSelectedPage() const { return m_selPage
; }
498 /** Shortcut for GetGrid()->GetSelection(). */
499 wxPGProperty
* GetSelectedProperty() const
501 return m_pPropGrid
->GetSelection();
504 /** Synonyme for GetSelectedPage. */
505 int GetSelection() const { return m_selPage
; }
507 /** Returns a pointer to the toolbar currently associated with the
508 wxPropertyGridManager (if any). */
509 wxToolBar
* GetToolBar() const { return m_pToolbar
; }
511 /** Creates new property page. Note that the first page is not created
514 Add to this position. -1 will add as the last item.
516 A label for the page. This may be shown as a toolbar tooltip etc.
518 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
519 default image is used.
521 wxPropertyGridPage instance. Manager will take ownership of this object.
522 If NULL, default page object is constructed.
524 Returns index to the page created.
526 virtual int InsertPage( int index
,
527 const wxString
& label
,
528 const wxBitmap
& bmp
= wxNullBitmap
,
529 wxPropertyGridPage
* pageObj
= NULL
);
532 Returns true if any property on any page has been modified by the user.
534 bool IsAnyModified() const;
537 Returns true if updating is frozen (ie Freeze() called but not yet
540 bool IsFrozen() const { return m_pPropGrid
->m_frozen
> 0; }
543 Returns true if any property on given page has been modified by the
546 bool IsPageModified( size_t index
) const;
548 virtual void Refresh( bool eraseBackground
= true,
549 const wxRect
* rect
= (const wxRect
*) NULL
);
553 Returns false if it was not possible to remove page in question.
555 virtual bool RemovePage( int page
);
557 /** Select and displays a given page. Also makes it target page for
558 insert operations etc.
560 Index of page being seleced. Can be -1 to select nothing.
562 void SelectPage( int index
);
564 /** Select and displays a given page (by label). */
565 void SelectPage( const wxString
& label
)
567 int index
= GetPageByName(label
);
568 wxCHECK_RET( index
>= 0, wxT("No page with such name") );
572 /** Select and displays a given page. */
573 void SelectPage( wxPropertyGridPage
* ptr
)
575 SelectPage( GetPageByState(ptr
) );
578 /** Select a property. */
579 bool SelectProperty( wxPGPropArg id
, bool focus
= false )
581 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
582 return p
->GetParentState()->DoSelectProperty(p
, focus
);
585 /** Sets number of columns on given page (default is current page).
587 void SetColumnCount( int colCount
, int page
= -1 );
589 /** Sets label and text in description box.
591 void SetDescription( const wxString
& label
, const wxString
& content
);
593 /** Sets y coordinate of the description box splitter. */
594 void SetDescBoxHeight( int ht
, bool refresh
= true );
596 /** Sets property attribute for all applicapple properties.
597 Be sure to use this method after all properties have been
600 void SetPropertyAttributeAll( const wxString
& name
, wxVariant value
);
602 /** Moves splitter as left as possible, while still allowing all
603 labels to be shown in full.
605 If false, will still allow sub-properties (ie. properties which
606 parent is not root or category) to be cropped.
608 If true, takes labels on all pages into account.
610 void SetSplitterLeft( bool subProps
= false, bool allPages
= true );
612 /** Sets splitter position on individual page. */
613 void SetPageSplitterPosition( int page
, int pos
, int column
= 0 )
615 GetPage(page
)->DoSetSplitterPosition( pos
, column
);
618 /** Sets splitter position for all pages.
620 Splitter position cannot exceed grid size, and therefore setting it
621 during form creation may fail as initial grid size is often smaller
622 than desired splitter position, especially when sizers are being used.
624 void SetSplitterPosition( int pos
, int column
= 0 );
626 /** Synonyme for SelectPage(name). */
627 void SetStringSelection( const wxChar
* name
)
629 SelectPage( GetPageByName(name
) );
634 def
GetValuesFromPage(self
,
638 inc_attributes
=False
):
639 "Same as GetValues, but returns values from specific page only."
640 "For argument descriptions, see GetValues."
641 return page
.GetPropertyValues(dict_
, as_strings
, inc_attributes
)
648 // Subclassing helpers
651 /** Creates property grid for the manager. Override to use subclassed
654 virtual wxPropertyGrid
* CreatePropertyGrid() const;
656 virtual void RefreshProperty( wxPGProperty
* p
);
663 // Overridden functions - no documentation required.
666 virtual wxSize
DoGetBestSize() const;
667 void SetId( wxWindowID winid
);
669 virtual void Freeze();
671 virtual void SetExtraStyle ( long exStyle
);
672 virtual bool SetFont ( const wxFont
& font
);
673 virtual void SetWindowStyleFlag ( long style
);
684 void OnMouseMove( wxMouseEvent
&event
);
685 void OnMouseClick( wxMouseEvent
&event
);
686 void OnMouseUp( wxMouseEvent
&event
);
687 void OnMouseEntry( wxMouseEvent
&event
);
689 void OnPaint( wxPaintEvent
&event
);
691 void OnToolbarClick( wxCommandEvent
&event
);
692 void OnResize( wxSizeEvent
& event
);
693 void OnPropertyGridSelect( wxPropertyGridEvent
& event
);
697 wxPropertyGrid
* m_pPropGrid
;
699 wxArrayPtrVoid m_arrPages
;
702 wxToolBar
* m_pToolbar
;
704 wxStaticText
* m_pTxtHelpCaption
;
705 wxStaticText
* m_pTxtHelpContent
;
707 wxPropertyGridPage
* m_emptyPage
;
711 // Selected page index.
722 int m_splitterHeight
;
728 wxCursor m_cursorSizeNS
;
730 int m_nextDescBoxSize
;
734 unsigned char m_dragStatus
;
736 unsigned char m_onSplitter
;
738 virtual wxPGProperty
* DoGetPropertyByName( const wxString
& name
) const;
740 /** Select and displays a given page. */
741 virtual bool DoSelectPage( int index
);
743 // Sets some members to defaults.
746 // Initializes some members.
747 void Init2( int style
);
750 virtual WXDWORD MSWGetStyle(long flags, WXDWORD *exstyle) const;
753 /** Recalculates new positions for components, according to the
756 void RecalculatePositions( int width
, int height
);
758 /** (Re)creates/destroys controls, according to the window style bits. */
759 void RecreateControls();
761 void RefreshHelpBox( int new_splittery
, int new_width
, int new_height
);
763 void RepaintSplitter( wxDC
& dc
,
769 void SetDescribedProperty( wxPGProperty
* p
);
771 virtual bool ProcessEvent( wxEvent
& event
);
774 DECLARE_EVENT_TABLE()
775 #endif // #ifndef SWIG
776 #endif // #ifndef DOXYGEN
779 // -----------------------------------------------------------------------
781 inline int wxPropertyGridPage::GetIndex() const
785 return m_manager
->GetPageByState(this);
788 // -----------------------------------------------------------------------
790 #endif // _WX_PROPGRID_MANAGER_H_