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_DATA_PROPGRID(const char) 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,
167 bool fromAutoCenter
= false );
169 /** Page label (may be referred as name in some parts of documentation).
170 Can be set in constructor, or passed in
171 wxPropertyGridManager::AddPage(), but *not* in both.
177 //virtual bool ProcessEvent( wxEvent& event );
179 wxPropertyGridManager
* m_manager
;
181 int m_id
; // toolbar index
184 bool m_isDefault
; // is this base page object?
187 DECLARE_EVENT_TABLE()
191 // -----------------------------------------------------------------------
193 /** @class wxPropertyGridManager
195 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
196 which can optionally have toolbar for mode and page selection, and help
198 Use window flags to select components to include.
200 @section propgridmanager_window_styles_ Window Styles
202 See @ref propgrid_window_styles.
204 @section propgridmanager_event_handling Event Handling
206 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
207 for more information.
212 class WXDLLIMPEXP_PROPGRID
213 wxPropertyGridManager
: public wxPanel
, public wxPropertyGridInterface
216 DECLARE_CLASS(wxPropertyGridManager
)
218 friend class wxPropertyGridPage
;
222 %pythonAppend wxPropertyGridManager
{
223 self
._setOORInfo(self
)
224 self
.DoDefaultTypeMappings()
225 self
.edited_objects
= {}
226 self
.DoDefaultValueTypeMappings()
227 if not hasattr(self
.__class__
,'_vt2setter'):
228 self
.__class__
._vt2setter
= {}
230 %pythonAppend
wxPropertyGridManager() ""
232 wxPropertyGridManager( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
233 const wxPoint
& pos
= wxDefaultPosition
,
234 const wxSize
& size
= wxDefaultSize
,
235 long style
= wxPGMAN_DEFAULT_STYLE
,
237 wxPyPropertyGridManagerNameStr
);
238 %RenameCtor
(PrePropertyGridManager
, wxPropertyGridManager());
243 Two step constructor.
244 Call Create when this constructor is called to build up the
245 wxPropertyGridManager.
247 wxPropertyGridManager();
249 /** The default constructor. The styles to be used are styles valid for
251 @see @link wndflags Additional Window Styles@endlink
253 wxPropertyGridManager( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
254 const wxPoint
& pos
= wxDefaultPosition
,
255 const wxSize
& size
= wxDefaultSize
,
256 long style
= wxPGMAN_DEFAULT_STYLE
,
257 const wxString
& name
= wxPropertyGridManagerNameStr
);
260 virtual ~wxPropertyGridManager();
264 /** Creates new property page. Note that the first page is not created
267 A label for the page. This may be shown as a toolbar tooltip etc.
269 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
270 default image is used.
272 wxPropertyGridPage instance. Manager will take ownership of this object.
273 NULL indicates that a default page instance should be created.
276 Returns pointer to created page.
279 If toolbar is used, it is highly recommended that the pages are
280 added when the toolbar is not turned off using window style flag
283 wxPropertyGridPage
* AddPage( const wxString
& label
= wxEmptyString
,
284 const wxBitmap
& bmp
= wxPG_NULL_BITMAP
,
285 wxPropertyGridPage
* pageObj
= NULL
)
287 return InsertPage(-1, label
, bmp
, pageObj
);
290 /** Deletes all all properties and all pages.
292 virtual void Clear();
294 /** Deletes all properties on given page.
296 void ClearPage( int page
);
298 /** Forces updating the value of property from the editor control.
299 Returns true if DoPropertyChanged was actually called.
301 bool CommitChangesFromEditor( wxUint32 flags
= 0 )
303 return m_pPropGrid
->CommitChangesFromEditor(flags
);
308 Whenever the control is created without any parameters, use Create to
309 actually create it. Don't access the control's public methods before
311 @see @link wndflags Additional Window Styles@endlink
313 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
314 const wxPoint
& pos
= wxDefaultPosition
,
315 const wxSize
& size
= wxDefaultSize
,
316 long style
= wxPGMAN_DEFAULT_STYLE
,
317 const wxString
& name
= wxPropertyGridManagerNameStr
);
320 Enables or disables (shows/hides) categories according to parameter
323 WARNING: Not tested properly, use at your own risk.
325 bool EnableCategories( bool enable
)
327 long fl
= m_windowStyle
| wxPG_HIDE_CATEGORIES
;
328 if ( enable
) fl
= m_windowStyle
& ~(wxPG_HIDE_CATEGORIES
);
329 SetWindowStyleFlag(fl
);
333 /** Selects page, scrolls and/or expands items to ensure that the
334 given item is visible. Returns true if something was actually done.
336 bool EnsureVisible( wxPGPropArg id
);
338 /** Returns number of columns on given page. By the default,
339 returns number of columns on current page. */
340 int GetColumnCount( int page
= -1 ) const;
342 /** Returns height of the description text box. */
343 int GetDescBoxHeight() const;
345 /** Returns pointer to the contained wxPropertyGrid. This does not change
346 after wxPropertyGridManager has been created, so you can safely obtain
347 pointer once and use it for the entire lifetime of the instance.
349 wxPropertyGrid
* GetGrid()
351 wxASSERT(m_pPropGrid
);
355 const wxPropertyGrid
* GetGrid() const
357 wxASSERT(m_pPropGrid
);
358 return (const wxPropertyGrid
*)m_pPropGrid
;
361 /** Returns iterator class instance.
363 Calling this method in wxPropertyGridManager causes run-time assertion
364 failure. Please only iterate through individual pages or use
367 wxPropertyGridIterator
GetIterator( int flags
= wxPG_ITERATE_DEFAULT
,
368 wxPGProperty
* firstProp
= NULL
)
370 wxFAIL_MSG( "Please only iterate through individual pages "
371 "or use CreateVIterator()" );
372 return wxPropertyGridInterface::GetIterator( flags
, firstProp
);
375 wxPropertyGridConstIterator
376 GetIterator(int flags
= wxPG_ITERATE_DEFAULT
,
377 wxPGProperty
* firstProp
= NULL
) const
379 wxFAIL_MSG( "Please only iterate through individual pages "
380 " or use CreateVIterator()" );
381 return wxPropertyGridInterface::GetIterator( flags
, firstProp
);
384 /** Returns iterator class instance.
386 Calling this method in wxPropertyGridManager causes run-time assertion
387 failure. Please only iterate through individual pages or use
390 wxPropertyGridIterator
GetIterator( int flags
, int startPos
)
392 wxFAIL_MSG( "Please only iterate through individual pages "
393 "or use CreateVIterator()" );
395 return wxPropertyGridInterface::GetIterator( flags
, startPos
);
398 wxPropertyGridConstIterator
GetIterator( int flags
, int startPos
) const
400 wxFAIL_MSG( "Please only iterate through individual pages "
401 "or use CreateVIterator()" );
402 return wxPropertyGridInterface::GetIterator( flags
, startPos
);
405 /** Similar to GetIterator, but instead returns wxPGVIterator instance,
406 which can be useful for forward-iterating through arbitrary property
409 virtual wxPGVIterator
GetVIterator( int flags
) const;
411 /** Returns currently selected page.
413 wxPropertyGridPage
* GetCurrentPage() const
415 return GetPage(m_selPage
);
418 /** Returns page object for given page index.
420 wxPropertyGridPage
* GetPage( unsigned int ind
) const
422 return m_arrPages
[ind
];
425 /** Returns page object for given page name.
427 wxPropertyGridPage
* GetPage( const wxString
& name
) const
429 return GetPage(GetPageByName(name
));
433 Returns index for a page name.
435 If no match is found, wxNOT_FOUND is returned.
437 int GetPageByName( const wxString
& name
) const;
439 /** Returns index for a relevant propertygrid state.
441 If no match is found, wxNOT_FOUND is returned.
443 int GetPageByState( const wxPropertyGridPageState
* pstate
) const;
446 /** Returns wxPropertyGridPageState of given page, current page's for -1.
448 virtual wxPropertyGridPageState
* GetPageState( int page
) const;
451 /** Returns number of managed pages. */
452 size_t GetPageCount() const;
454 /** Returns name of given page. */
455 const wxString
& GetPageName( int index
) const;
457 /** Returns "root property" of the given page. It does not have name, etc.
458 and it is not visible. It is only useful for accessing its children.
460 wxPGProperty
* GetPageRoot( int index
) const;
462 /** Returns index to currently selected page. */
463 int GetSelectedPage() const { return m_selPage
; }
465 /** Alias for GetSelection(). */
466 wxPGProperty
* GetSelectedProperty() const
468 return GetSelection();
471 /** Shortcut for GetGrid()->GetSelection(). */
472 wxPGProperty
* GetSelection() const
474 return m_pPropGrid
->GetSelection();
477 /** Returns a pointer to the toolbar currently associated with the
478 wxPropertyGridManager (if any). */
479 wxToolBar
* GetToolBar() const { return m_pToolbar
; }
481 /** Creates new property page. Note that the first page is not created
484 Add to this position. -1 will add as the last item.
486 A label for the page. This may be shown as a toolbar tooltip etc.
488 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
489 default image is used.
491 wxPropertyGridPage instance. Manager will take ownership of this object.
492 If NULL, default page object is constructed.
495 Returns pointer to created page.
497 virtual wxPropertyGridPage
* InsertPage( int index
,
498 const wxString
& label
,
499 const wxBitmap
& bmp
= wxNullBitmap
,
500 wxPropertyGridPage
* pageObj
= NULL
);
503 Returns true if any property on any page has been modified by the user.
505 bool IsAnyModified() const;
508 Returns true if updating is frozen (ie Freeze() called but not yet
511 bool IsFrozen() const { return m_pPropGrid
->m_frozen
> 0; }
514 Returns true if any property on given page has been modified by the
517 bool IsPageModified( size_t index
) const;
519 virtual void Refresh( bool eraseBackground
= true,
520 const wxRect
* rect
= (const wxRect
*) NULL
);
524 Returns false if it was not possible to remove page in question.
526 virtual bool RemovePage( int page
);
528 /** Select and displays a given page.
531 Index of page being seleced. Can be -1 to select nothing.
533 void SelectPage( int index
);
535 /** Select and displays a given page (by label). */
536 void SelectPage( const wxString
& label
)
538 int index
= GetPageByName(label
);
539 wxCHECK_RET( index
>= 0, wxT("No page with such name") );
543 /** Select and displays a given page. */
544 void SelectPage( wxPropertyGridPage
* ptr
)
546 SelectPage( GetPageByState(ptr
) );
549 /** Select a property. */
550 bool SelectProperty( wxPGPropArg id
, bool focus
= false )
552 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
553 return p
->GetParentState()->DoSelectProperty(p
, focus
);
556 /** Sets number of columns on given page (default is current page).
558 void SetColumnCount( int colCount
, int page
= -1 );
560 /** Sets label and text in description box.
562 void SetDescription( const wxString
& label
, const wxString
& content
);
564 /** Sets y coordinate of the description box splitter. */
565 void SetDescBoxHeight( int ht
, bool refresh
= true );
567 /** Moves splitter as left as possible, while still allowing all
568 labels to be shown in full.
570 If false, will still allow sub-properties (ie. properties which
571 parent is not root or category) to be cropped.
573 If true, takes labels on all pages into account.
575 void SetSplitterLeft( bool subProps
= false, bool allPages
= true );
577 /** Sets splitter position on individual page. */
578 void SetPageSplitterPosition( int page
, int pos
, int column
= 0 )
580 GetPage(page
)->DoSetSplitterPosition( pos
, column
);
583 /** Sets splitter position for all pages.
585 Splitter position cannot exceed grid size, and therefore setting it
586 during form creation may fail as initial grid size is often smaller
587 than desired splitter position, especially when sizers are being used.
589 void SetSplitterPosition( int pos
, int column
= 0 );
593 def
GetValuesFromPage(self
,
597 inc_attributes
=False
):
598 "Same as GetValues, but returns values from specific page only."
599 "For argument descriptions, see GetValues."
600 return page
.GetPropertyValues(dict_
, as_strings
, inc_attributes
)
607 // Subclassing helpers
611 Creates property grid for the manager. Reimplement in derived class to
612 use subclassed wxPropertyGrid. However, if you you do this then you
613 must also use the two-step construction (ie. default constructor and
614 Create() instead of constructor with arguments) when creating the
617 virtual wxPropertyGrid
* CreatePropertyGrid() const;
620 virtual void RefreshProperty( wxPGProperty
* p
);
623 // Overridden functions - no documentation required.
626 void SetId( wxWindowID winid
);
628 virtual void Freeze();
630 virtual void SetExtraStyle ( long exStyle
);
631 virtual bool SetFont ( const wxFont
& font
);
632 virtual void SetWindowStyleFlag ( long style
);
635 virtual wxSize
DoGetBestSize() const;
644 void OnMouseMove( wxMouseEvent
&event
);
645 void OnMouseClick( wxMouseEvent
&event
);
646 void OnMouseUp( wxMouseEvent
&event
);
647 void OnMouseEntry( wxMouseEvent
&event
);
649 void OnPaint( wxPaintEvent
&event
);
651 void OnToolbarClick( wxCommandEvent
&event
);
652 void OnResize( wxSizeEvent
& event
);
653 void OnPropertyGridSelect( wxPropertyGridEvent
& event
);
657 wxPropertyGrid
* m_pPropGrid
;
659 wxVector
<wxPropertyGridPage
*> m_arrPages
;
662 wxToolBar
* m_pToolbar
;
664 wxStaticText
* m_pTxtHelpCaption
;
665 wxStaticText
* m_pTxtHelpContent
;
667 wxPropertyGridPage
* m_emptyPage
;
671 // Selected page index.
682 int m_splitterHeight
;
688 wxCursor m_cursorSizeNS
;
690 int m_nextDescBoxSize
;
694 unsigned char m_dragStatus
;
696 unsigned char m_onSplitter
;
698 virtual wxPGProperty
* DoGetPropertyByName( const wxString
& name
) const;
700 /** Select and displays a given page. */
701 virtual bool DoSelectPage( int index
);
703 // Sets some members to defaults.
706 // Initializes some members.
707 void Init2( int style
);
710 virtual WXDWORD MSWGetStyle(long flags, WXDWORD *exstyle) const;
713 virtual bool ProcessEvent( wxEvent
& event
);
715 /** Recalculates new positions for components, according to the
718 void RecalculatePositions( int width
, int height
);
720 /** (Re)creates/destroys controls, according to the window style bits. */
721 void RecreateControls();
723 void UpdateDescriptionBox( int new_splittery
, int new_width
, int new_height
);
725 void RepaintDescBoxDecorations( wxDC
& dc
,
730 void SetDescribedProperty( wxPGProperty
* p
);
732 // Reimplement these to handle "descboxheight" state item
733 virtual bool SetEditableStateItem( const wxString
& name
, wxVariant value
);
734 virtual wxVariant
GetEditableStateItem( const wxString
& name
) const;
737 DECLARE_EVENT_TABLE()
738 #endif // #ifndef SWIG
741 // -----------------------------------------------------------------------
743 inline int wxPropertyGridPage::GetIndex() const
747 return m_manager
->GetPageByState(this);
750 // -----------------------------------------------------------------------
752 #endif // wxUSE_PROPGRID
754 #endif // _WX_PROPGRID_MANAGER_H_