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_
17 #include "wx/propgrid/propgrid.h"
19 #include "wx/dcclient.h"
20 #include "wx/scrolwin.h"
21 #include "wx/toolbar.h"
22 #include "wx/stattext.h"
23 #include "wx/button.h"
24 #include "wx/textctrl.h"
25 #include "wx/dialog.h"
27 // -----------------------------------------------------------------------
30 extern WXDLLIMPEXP_PROPGRID
const wxChar
*wxPropertyGridManagerNameStr
;
33 /** @class wxPropertyGridPage
35 Holder of property grid page information. You can subclass this and
36 give instance in wxPropertyGridManager::AddPage. It inherits from
37 wxEvtHandler and can be used to process events specific to this
38 page (id of events will still be same as manager's). If you don't
39 want to use it to process all events of the page, you need to
40 return false in the derived wxPropertyGridPage::IsHandlingAllEvents.
42 Please note that wxPropertyGridPage lacks many non-const property
43 manipulation functions found in wxPropertyGridManager. Please use
44 parent manager (m_manager member variable) when needed.
46 Please note that most member functions are inherited and as such not
47 documented on this page. This means you will probably also want to read
48 wxPropertyGridInterface class reference.
50 @section propgridpage_event_handling Event Handling
52 wxPropertyGridPage receives events emitted by its wxPropertyGridManager, but
53 only those events that are specific to that page. If
54 wxPropertyGridPage::IsHandlingAllEvents returns false, then unhandled
55 events are sent to the manager's parent, as usual.
57 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
63 class WXDLLIMPEXP_PROPGRID wxPropertyGridPage
: public wxEvtHandler
,
64 public wxPropertyGridInterface
,
65 public wxPropertyGridPageState
67 friend class wxPropertyGridManager
;
69 DECLARE_CLASS(wxPropertyGridPage
)
74 virtual ~wxPropertyGridPage();
76 /** Deletes all properties on page.
81 Reduces column sizes to minimum possible that contents are still
82 visibly (naturally some margin space will be applied as well).
85 Minimum size for the page to still display everything.
88 This function only works properly if size of containing grid was
91 Note that you can also get calculated column widths by calling
92 GetColumnWidth() immediately after this function returns.
96 /** Returns page index in manager;
98 inline int GetIndex() const;
100 /** Returns x-coordinate position of splitter on a page.
102 int GetSplitterPosition( int col
= 0 ) const
103 { return GetStatePtr()->DoGetSplitterPosition(col
); }
105 /** Returns "root property". It does not have name, etc. and it is not
106 visible. It is only useful for accessing its children.
108 wxPGProperty
* GetRoot() const { return GetStatePtr()->DoGetRoot(); }
110 /** Return pointer to contained property grid state.
112 wxPropertyGridPageState
* GetStatePtr()
117 /** Return pointer to contained property grid state.
119 const wxPropertyGridPageState
* GetStatePtr() const
125 Returns id of the tool bar item that represents this page on
126 wxPropertyGridManager's wxToolBar.
128 int GetToolId() const
133 /** Do any member initialization in this method.
135 - Called every time the page is added into a manager.
136 - You can add properties to the page here.
138 virtual void Init() {}
140 /** Return false here to indicate unhandled events should be
141 propagated to manager's parent, as normal.
143 virtual bool IsHandlingAllEvents() const { return true; }
145 /** Called every time page is about to be shown.
146 Useful, for instance, creating properties just-in-time.
148 virtual void OnShow();
150 virtual void RefreshProperty( wxPGProperty
* p
);
152 /** Sets splitter position on page.
154 Splitter position cannot exceed grid size, and therefore setting it
155 during form creation may fail as initial grid size is often smaller
156 than desired splitter position, especially when sizers are being used.
158 void SetSplitterPosition( int splitterPos
, int col
= 0 );
162 /** Propagate to other pages.
164 virtual void DoSetSplitterPosition( int pos
,
165 int splitterColumn
= 0,
166 bool allPages
= false );
168 /** Propagate to other pages.
170 void DoSetSplitterPositionThisPage( int pos
, int splitterColumn
= 0 )
172 wxPropertyGridPageState::DoSetSplitterPosition( pos
, splitterColumn
);
175 /** Page label (may be referred as name in some parts of documentation).
176 Can be set in constructor, or passed in
177 wxPropertyGridManager::AddPage(), but *not* in both.
183 //virtual bool ProcessEvent( wxEvent& event );
185 wxPropertyGridManager
* m_manager
;
187 int m_id
; // toolbar index
190 bool m_isDefault
; // is this base page object?
193 DECLARE_EVENT_TABLE()
197 // -----------------------------------------------------------------------
199 /** @class wxPropertyGridManager
201 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
202 which can optionally have toolbar for mode and page selection, and help
204 Use window flags to select components to include.
206 @section propgridmanager_window_styles_ Window Styles
208 See @ref propgrid_window_styles.
210 @section propgridmanager_event_handling Event Handling
212 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
213 for more information.
218 class WXDLLIMPEXP_PROPGRID
219 wxPropertyGridManager
: public wxPanel
, public wxPropertyGridInterface
222 DECLARE_CLASS(wxPropertyGridManager
)
224 friend class wxPropertyGridPage
;
228 %pythonAppend wxPropertyGridManager
{
229 self
._setOORInfo(self
)
230 self
.DoDefaultTypeMappings()
231 self
.edited_objects
= {}
232 self
.DoDefaultValueTypeMappings()
233 if not hasattr(self
.__class__
,'_vt2setter'):
234 self
.__class__
._vt2setter
= {}
236 %pythonAppend
wxPropertyGridManager() ""
238 wxPropertyGridManager( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
239 const wxPoint
& pos
= wxDefaultPosition
,
240 const wxSize
& size
= wxDefaultSize
,
241 long style
= wxPGMAN_DEFAULT_STYLE
,
243 wxPyPropertyGridManagerNameStr
);
244 %RenameCtor
(PrePropertyGridManager
, wxPropertyGridManager());
249 Two step constructor.
250 Call Create when this constructor is called to build up the
251 wxPropertyGridManager.
253 wxPropertyGridManager();
255 /** The default constructor. The styles to be used are styles valid for
257 @see @link wndflags Additional Window Styles@endlink
259 wxPropertyGridManager( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
260 const wxPoint
& pos
= wxDefaultPosition
,
261 const wxSize
& size
= wxDefaultSize
,
262 long style
= wxPGMAN_DEFAULT_STYLE
,
263 const wxChar
* name
= wxPropertyGridManagerNameStr
);
266 virtual ~wxPropertyGridManager();
270 /** Creates new property page. Note that the first page is not created
273 A label for the page. This may be shown as a toolbar tooltip etc.
275 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
276 default image is used.
278 wxPropertyGridPage instance. Manager will take ownership of this object.
279 NULL indicates that a default page instance should be created.
281 Returns index to the page created.
283 If toolbar is used, it is highly recommended that the pages are
284 added when the toolbar is not turned off using window style flag
287 int AddPage( const wxString
& label
= wxEmptyString
,
288 const wxBitmap
& bmp
= wxPG_NULL_BITMAP
,
289 wxPropertyGridPage
* pageObj
= (wxPropertyGridPage
*) NULL
)
291 return InsertPage(-1,label
,bmp
,pageObj
);
294 void ClearModifiedStatus ( wxPGPropArg id
);
296 void ClearModifiedStatus ()
298 m_pPropGrid
->ClearModifiedStatus();
301 /** Deletes all all properties and all pages.
303 virtual void Clear();
305 /** Deletes all properties on given page.
307 void ClearPage( int page
);
309 /** Forces updating the value of property from the editor control.
310 Returns true if DoPropertyChanged was actually called.
312 bool CommitChangesFromEditor( wxUint32 flags
= 0 )
314 return m_pPropGrid
->CommitChangesFromEditor(flags
);
319 Whenever the control is created without any parameters, use Create to
320 actually create it. Don't access the control's public methods before
322 @see @link wndflags Additional Window Styles@endlink
324 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
325 const wxPoint
& pos
= wxDefaultPosition
,
326 const wxSize
& size
= wxDefaultSize
,
327 long style
= wxPGMAN_DEFAULT_STYLE
,
328 const wxChar
* name
= wxPropertyGridManagerNameStr
);
331 Enables or disables (shows/hides) categories according to parameter
334 WARNING: Not tested properly, use at your own risk.
336 bool EnableCategories( bool enable
)
338 long fl
= m_windowStyle
| wxPG_HIDE_CATEGORIES
;
339 if ( enable
) fl
= m_windowStyle
& ~(wxPG_HIDE_CATEGORIES
);
340 SetWindowStyleFlag(fl
);
344 /** Selects page, scrolls and/or expands items to ensure that the
345 given item is visible. Returns true if something was actually done.
347 bool EnsureVisible( wxPGPropArg id
);
349 /** Returns number of children of the root property of the selected page. */
350 size_t GetChildrenCount()
352 return GetChildrenCount( m_pPropGrid
->m_pState
->m_properties
);
355 /** Returns number of children of the root property of given page. */
356 size_t GetChildrenCount( int pageIndex
);
358 /** Returns number of children for the property.
360 NB: Cannot be in container methods class due to name hiding.
362 size_t GetChildrenCount( wxPGPropArg id
) const
364 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
365 return p
->GetChildCount();
368 /** Returns number of columns on given page. By the default,
369 returns number of columns on current page. */
370 int GetColumnCount( int page
= -1 ) const;
372 /** Returns height of the description text box. */
373 int GetDescBoxHeight() const;
375 /** Returns pointer to the contained wxPropertyGrid. This does not change
376 after wxPropertyGridManager has been created, so you can safely obtain
377 pointer once and use it for the entire lifetime of the instance.
379 wxPropertyGrid
* GetGrid()
381 wxASSERT(m_pPropGrid
);
385 const wxPropertyGrid
* GetGrid() const
387 wxASSERT(m_pPropGrid
);
388 return (const wxPropertyGrid
*)m_pPropGrid
;
391 /** Returns iterator class instance.
393 Calling this method in wxPropertyGridManager causes run-time assertion
394 failure. Please only iterate through individual pages or use
397 wxPropertyGridIterator
GetIterator( int flags
= wxPG_ITERATE_DEFAULT
,
398 wxPGProperty
* firstProp
= NULL
)
400 wxFAIL_MSG( "Please only iterate through individual pages "
401 "or use CreateVIterator()" );
402 return wxPropertyGridInterface::GetIterator( flags
, firstProp
);
405 wxPropertyGridConstIterator
406 GetIterator(int flags
= wxPG_ITERATE_DEFAULT
,
407 wxPGProperty
* firstProp
= NULL
) const
409 wxFAIL_MSG( "Please only iterate through individual pages "
410 " or use CreateVIterator()" );
411 return wxPropertyGridInterface::GetIterator( flags
, firstProp
);
414 /** Returns iterator class instance.
416 Calling this method in wxPropertyGridManager causes run-time assertion
417 failure. Please only iterate through individual pages or use
420 wxPropertyGridIterator
GetIterator( int flags
, int startPos
)
422 wxFAIL_MSG( "Please only iterate through individual pages "
423 "or use CreateVIterator()" );
425 return wxPropertyGridInterface::GetIterator( flags
, startPos
);
428 wxPropertyGridConstIterator
GetIterator( int flags
, int startPos
) const
430 wxFAIL_MSG( "Please only iterate through individual pages "
431 "or use CreateVIterator()" );
432 return wxPropertyGridInterface::GetIterator( flags
, startPos
);
435 /** Similar to GetIterator, but instead returns wxPGVIterator instance,
436 which can be useful for forward-iterating through arbitrary property
439 virtual wxPGVIterator
GetVIterator( int flags
) const;
441 /** Returns currently selected page.
443 wxPropertyGridPage
* GetCurrentPage() const
445 return GetPage(m_selPage
);
448 /** Returns last page.
450 wxPropertyGridPage
* GetLastPage() const
452 return GetPage(m_arrPages
.size()-1);
455 /** Returns page object for given page index.
457 wxPropertyGridPage
* GetPage( unsigned int ind
) const
459 return (wxPropertyGridPage
*)m_arrPages
.Item(ind
);
462 /** Returns page object for given page name.
464 wxPropertyGridPage
* GetPage( const wxString
& name
) const
466 return GetPage(GetPageByName(name
));
470 Returns index for a page name.
472 If no match is found, wxNOT_FOUND is returned.
474 int GetPageByName( const wxString
& name
) const;
476 /** Returns index for a relevant propertygrid state.
478 If no match is found, wxNOT_FOUND is returned.
480 int GetPageByState( const wxPropertyGridPageState
* pstate
) const;
482 /** Returns wxPropertyGridPageState of given page, current page's for -1.
484 virtual wxPropertyGridPageState
* GetPageState( int page
) const;
486 /** Returns number of managed pages. */
487 size_t GetPageCount() const;
489 /** Returns name of given page. */
490 const wxString
& GetPageName( int index
) const;
492 /** Returns "root property" of the given page. It does not have name, etc.
493 and it is not visible. It is only useful for accessing its children.
495 wxPGProperty
* GetPageRoot( int index
) const;
497 /** Returns index to currently selected page. */
498 int GetSelectedPage() const { return m_selPage
; }
500 /** Shortcut for GetGrid()->GetSelection(). */
501 wxPGProperty
* GetSelectedProperty() const
503 return m_pPropGrid
->GetSelection();
506 /** Synonyme for GetSelectedPage. */
507 int GetSelection() const { return m_selPage
; }
509 /** Returns a pointer to the toolbar currently associated with the
510 wxPropertyGridManager (if any). */
511 wxToolBar
* GetToolBar() const { return m_pToolbar
; }
513 /** Creates new property page. Note that the first page is not created
516 Add to this position. -1 will add as the last item.
518 A label for the page. This may be shown as a toolbar tooltip etc.
520 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
521 default image is used.
523 wxPropertyGridPage instance. Manager will take ownership of this object.
524 If NULL, default page object is constructed.
526 Returns index to the page created.
528 virtual int InsertPage( int index
,
529 const wxString
& label
,
530 const wxBitmap
& bmp
= wxNullBitmap
,
531 wxPropertyGridPage
* pageObj
= NULL
);
534 Returns true if any property on any page has been modified by the user.
536 bool IsAnyModified() const;
539 Returns true if updating is frozen (ie Freeze() called but not yet
542 bool IsFrozen() const { return m_pPropGrid
->m_frozen
> 0; }
545 Returns true if any property on given page has been modified by the
548 bool IsPageModified( size_t index
) const;
550 virtual void Refresh( bool eraseBackground
= true,
551 const wxRect
* rect
= (const wxRect
*) NULL
);
555 Returns false if it was not possible to remove page in question.
557 virtual bool RemovePage( int page
);
559 /** Select and displays a given page.
562 Index of page being seleced. Can be -1 to select nothing.
564 void SelectPage( int index
);
566 /** Select and displays a given page (by label). */
567 void SelectPage( const wxString
& label
)
569 int index
= GetPageByName(label
);
570 wxCHECK_RET( index
>= 0, wxT("No page with such name") );
574 /** Select and displays a given page. */
575 void SelectPage( wxPropertyGridPage
* ptr
)
577 SelectPage( GetPageByState(ptr
) );
580 /** Select a property. */
581 bool SelectProperty( wxPGPropArg id
, bool focus
= false )
583 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
584 return p
->GetParentState()->DoSelectProperty(p
, focus
);
587 /** Sets number of columns on given page (default is current page).
589 void SetColumnCount( int colCount
, int page
= -1 );
591 /** Sets label and text in description box.
593 void SetDescription( const wxString
& label
, const wxString
& content
);
595 /** Sets y coordinate of the description box splitter. */
596 void SetDescBoxHeight( int ht
, bool refresh
= true );
598 /** Moves splitter as left as possible, while still allowing all
599 labels to be shown in full.
601 If false, will still allow sub-properties (ie. properties which
602 parent is not root or category) to be cropped.
604 If true, takes labels on all pages into account.
606 void SetSplitterLeft( bool subProps
= false, bool allPages
= true );
608 /** Sets splitter position on individual page. */
609 void SetPageSplitterPosition( int page
, int pos
, int column
= 0 )
611 GetPage(page
)->DoSetSplitterPosition( pos
, column
);
614 /** Sets splitter position for all pages.
616 Splitter position cannot exceed grid size, and therefore setting it
617 during form creation may fail as initial grid size is often smaller
618 than desired splitter position, especially when sizers are being used.
620 void SetSplitterPosition( int pos
, int column
= 0 );
622 /** Synonyme for SelectPage(name). */
623 void SetStringSelection( const wxChar
* name
)
625 SelectPage( GetPageByName(name
) );
630 def
GetValuesFromPage(self
,
634 inc_attributes
=False
):
635 "Same as GetValues, but returns values from specific page only."
636 "For argument descriptions, see GetValues."
637 return page
.GetPropertyValues(dict_
, as_strings
, inc_attributes
)
644 // Subclassing helpers
647 /** Creates property grid for the manager. Override to use subclassed
650 virtual wxPropertyGrid
* CreatePropertyGrid() const;
652 virtual void RefreshProperty( wxPGProperty
* p
);
659 // Overridden functions - no documentation required.
662 virtual wxSize
DoGetBestSize() const;
663 void SetId( wxWindowID winid
);
665 virtual void Freeze();
667 virtual void SetExtraStyle ( long exStyle
);
668 virtual bool SetFont ( const wxFont
& font
);
669 virtual void SetWindowStyleFlag ( long style
);
680 void OnMouseMove( wxMouseEvent
&event
);
681 void OnMouseClick( wxMouseEvent
&event
);
682 void OnMouseUp( wxMouseEvent
&event
);
683 void OnMouseEntry( wxMouseEvent
&event
);
685 void OnPaint( wxPaintEvent
&event
);
687 void OnToolbarClick( wxCommandEvent
&event
);
688 void OnResize( wxSizeEvent
& event
);
689 void OnPropertyGridSelect( wxPropertyGridEvent
& event
);
693 wxPropertyGrid
* m_pPropGrid
;
695 wxArrayPtrVoid m_arrPages
;
698 wxToolBar
* m_pToolbar
;
700 wxStaticText
* m_pTxtHelpCaption
;
701 wxStaticText
* m_pTxtHelpContent
;
703 wxPropertyGridPage
* m_emptyPage
;
707 // Selected page index.
718 int m_splitterHeight
;
724 wxCursor m_cursorSizeNS
;
726 int m_nextDescBoxSize
;
730 unsigned char m_dragStatus
;
732 unsigned char m_onSplitter
;
734 virtual wxPGProperty
* DoGetPropertyByName( const wxString
& name
) const;
736 /** Select and displays a given page. */
737 virtual bool DoSelectPage( int index
);
739 // Sets some members to defaults.
742 // Initializes some members.
743 void Init2( int style
);
746 virtual WXDWORD MSWGetStyle(long flags, WXDWORD *exstyle) const;
749 /** Recalculates new positions for components, according to the
752 void RecalculatePositions( int width
, int height
);
754 /** (Re)creates/destroys controls, according to the window style bits. */
755 void RecreateControls();
757 void RefreshHelpBox( int new_splittery
, int new_width
, int new_height
);
759 void RepaintSplitter( wxDC
& dc
,
765 void SetDescribedProperty( wxPGProperty
* p
);
767 virtual bool ProcessEvent( wxEvent
& event
);
770 DECLARE_EVENT_TABLE()
771 #endif // #ifndef SWIG
772 #endif // #ifndef DOXYGEN
775 // -----------------------------------------------------------------------
777 inline int wxPropertyGridPage::GetIndex() const
781 return m_manager
->GetPageByState(this);
784 // -----------------------------------------------------------------------
786 #endif // wxUSE_PROPGRID
788 #endif // _WX_PROPGRID_MANAGER_H_