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"
26 #include "wx/headerctrl.h"
28 // -----------------------------------------------------------------------
31 extern WXDLLIMPEXP_DATA_PROPGRID(const char) wxPropertyGridManagerNameStr
[];
34 /** @class wxPropertyGridPage
36 Holder of property grid page information. You can subclass this and
37 give instance in wxPropertyGridManager::AddPage. It inherits from
38 wxEvtHandler and can be used to process events specific to this
39 page (id of events will still be same as manager's). If you don't
40 want to use it to process all events of the page, you need to
41 return false in the derived wxPropertyGridPage::IsHandlingAllEvents.
43 Please note that wxPropertyGridPage lacks many non-const property
44 manipulation functions found in wxPropertyGridManager. Please use
45 parent manager (m_manager member variable) when needed.
47 Please note that most member functions are inherited and as such not
48 documented on this page. This means you will probably also want to read
49 wxPropertyGridInterface class reference.
51 @section propgridpage_event_handling Event Handling
53 wxPropertyGridPage receives events emitted by its wxPropertyGridManager, but
54 only those events that are specific to that page. If
55 wxPropertyGridPage::IsHandlingAllEvents returns false, then unhandled
56 events are sent to the manager's parent, as usual.
58 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
64 class WXDLLIMPEXP_PROPGRID wxPropertyGridPage
: public wxEvtHandler
,
65 public wxPropertyGridInterface
,
66 public wxPropertyGridPageState
68 friend class wxPropertyGridManager
;
69 DECLARE_CLASS(wxPropertyGridPage
)
73 virtual ~wxPropertyGridPage();
75 /** Deletes all properties on page.
80 Reduces column sizes to minimum possible that contents are still
81 visibly (naturally some margin space will be applied as well).
84 Minimum size for the page to still display everything.
87 This function only works properly if size of containing grid was
90 Note that you can also get calculated column widths by calling
91 GetColumnWidth() immediately after this function returns.
95 /** Returns page index in manager;
97 inline int GetIndex() const;
99 /** Returns x-coordinate position of splitter on a page.
101 int GetSplitterPosition( int col
= 0 ) const
102 { return GetStatePtr()->DoGetSplitterPosition(col
); }
104 /** Returns "root property". It does not have name, etc. and it is not
105 visible. It is only useful for accessing its children.
107 wxPGProperty
* GetRoot() const { return GetStatePtr()->DoGetRoot(); }
109 /** Return pointer to contained property grid state.
111 wxPropertyGridPageState
* GetStatePtr()
116 /** Return pointer to contained property grid state.
118 const wxPropertyGridPageState
* GetStatePtr() const
124 Returns id of the tool bar item that represents this page on
125 wxPropertyGridManager's wxToolBar.
127 int GetToolId() const
132 /** Do any member initialization in this method.
134 - Called every time the page is added into a manager.
135 - You can add properties to the page here.
137 virtual void Init() {}
139 /** Return false here to indicate unhandled events should be
140 propagated to manager's parent, as normal.
142 virtual bool IsHandlingAllEvents() const { return true; }
144 /** Called every time page is about to be shown.
145 Useful, for instance, creating properties just-in-time.
147 virtual void OnShow();
149 virtual void RefreshProperty( wxPGProperty
* p
);
151 /** Sets splitter position on page.
153 Splitter position cannot exceed grid size, and therefore setting it
154 during form creation may fail as initial grid size is often smaller
155 than desired splitter position, especially when sizers are being used.
157 void SetSplitterPosition( int splitterPos
, int col
= 0 );
161 /** Propagate to other pages.
163 virtual void DoSetSplitterPosition( int pos
,
164 int splitterColumn
= 0,
165 int flags
= wxPG_SPLITTER_REFRESH
);
167 /** Page label (may be referred as name in some parts of documentation).
168 Can be set in constructor, or passed in
169 wxPropertyGridManager::AddPage(), but *not* in both.
175 //virtual bool ProcessEvent( wxEvent& event );
177 wxPropertyGridManager
* m_manager
;
179 int m_id
; // toolbar index
182 bool m_isDefault
; // is this base page object?
185 DECLARE_EVENT_TABLE()
189 // -----------------------------------------------------------------------
192 class wxPGHeaderCtrl
;
196 /** @class wxPropertyGridManager
198 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
199 which can optionally have toolbar for mode and page selection, and help
201 Use window flags to select components to include.
203 @section propgridmanager_window_styles_ Window Styles
205 See @ref propgrid_window_styles.
207 @section propgridmanager_event_handling Event Handling
209 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
210 for more information.
215 class WXDLLIMPEXP_PROPGRID
216 wxPropertyGridManager
: public wxPanel
, public wxPropertyGridInterface
218 DECLARE_CLASS(wxPropertyGridManager
)
219 friend class wxPropertyGridPage
;
224 Two step constructor.
225 Call Create when this constructor is called to build up the
226 wxPropertyGridManager.
228 wxPropertyGridManager();
231 /** The default constructor. The styles to be used are styles valid for
233 @see @link wndflags Additional Window Styles@endlink
235 wxPropertyGridManager( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
236 const wxPoint
& pos
= wxDefaultPosition
,
237 const wxSize
& size
= wxDefaultSize
,
238 long style
= wxPGMAN_DEFAULT_STYLE
,
239 const wxString
& name
= wxPropertyGridManagerNameStr
);
242 virtual ~wxPropertyGridManager();
244 /** Creates new property page. Note that the first page is not created
247 A label for the page. This may be shown as a toolbar tooltip etc.
249 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
250 default image is used.
252 wxPropertyGridPage instance. Manager will take ownership of this object.
253 NULL indicates that a default page instance should be created.
256 Returns pointer to created page.
259 If toolbar is used, it is highly recommended that the pages are
260 added when the toolbar is not turned off using window style flag
263 wxPropertyGridPage
* AddPage( const wxString
& label
= wxEmptyString
,
264 const wxBitmap
& bmp
= wxPG_NULL_BITMAP
,
265 wxPropertyGridPage
* pageObj
= NULL
)
267 return InsertPage(-1, label
, bmp
, pageObj
);
270 /** Deletes all all properties and all pages.
272 virtual void Clear();
274 /** Deletes all properties on given page.
276 void ClearPage( int page
);
278 /** Forces updating the value of property from the editor control.
279 Returns true if DoPropertyChanged was actually called.
281 bool CommitChangesFromEditor( wxUint32 flags
= 0 )
283 return m_pPropGrid
->CommitChangesFromEditor(flags
);
288 Whenever the control is created without any parameters, use Create to
289 actually create it. Don't access the control's public methods before
291 @see @link wndflags Additional Window Styles@endlink
293 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
294 const wxPoint
& pos
= wxDefaultPosition
,
295 const wxSize
& size
= wxDefaultSize
,
296 long style
= wxPGMAN_DEFAULT_STYLE
,
297 const wxString
& name
= wxPropertyGridManagerNameStr
);
300 Enables or disables (shows/hides) categories according to parameter
303 WARNING: Not tested properly, use at your own risk.
305 bool EnableCategories( bool enable
)
307 long fl
= m_windowStyle
| wxPG_HIDE_CATEGORIES
;
308 if ( enable
) fl
= m_windowStyle
& ~(wxPG_HIDE_CATEGORIES
);
309 SetWindowStyleFlag(fl
);
313 /** Selects page, scrolls and/or expands items to ensure that the
314 given item is visible. Returns true if something was actually done.
316 bool EnsureVisible( wxPGPropArg id
);
318 /** Returns number of columns on given page. By the default,
319 returns number of columns on current page. */
320 int GetColumnCount( int page
= -1 ) const;
322 /** Returns height of the description text box. */
323 int GetDescBoxHeight() const;
325 /** Returns pointer to the contained wxPropertyGrid. This does not change
326 after wxPropertyGridManager has been created, so you can safely obtain
327 pointer once and use it for the entire lifetime of the instance.
329 wxPropertyGrid
* GetGrid()
331 wxASSERT(m_pPropGrid
);
335 const wxPropertyGrid
* GetGrid() const
337 wxASSERT(m_pPropGrid
);
338 return (const wxPropertyGrid
*)m_pPropGrid
;
341 /** Returns iterator class instance.
343 Calling this method in wxPropertyGridManager causes run-time assertion
344 failure. Please only iterate through individual pages or use
347 wxPropertyGridIterator
GetIterator( int flags
= wxPG_ITERATE_DEFAULT
,
348 wxPGProperty
* firstProp
= NULL
)
350 wxFAIL_MSG( "Please only iterate through individual pages "
351 "or use CreateVIterator()" );
352 return wxPropertyGridInterface::GetIterator( flags
, firstProp
);
355 wxPropertyGridConstIterator
356 GetIterator(int flags
= wxPG_ITERATE_DEFAULT
,
357 wxPGProperty
* firstProp
= NULL
) const
359 wxFAIL_MSG( "Please only iterate through individual pages "
360 " or use CreateVIterator()" );
361 return wxPropertyGridInterface::GetIterator( flags
, firstProp
);
364 /** Returns iterator class instance.
366 Calling this method in wxPropertyGridManager causes run-time assertion
367 failure. Please only iterate through individual pages or use
370 wxPropertyGridIterator
GetIterator( int flags
, int startPos
)
372 wxFAIL_MSG( "Please only iterate through individual pages "
373 "or use CreateVIterator()" );
375 return wxPropertyGridInterface::GetIterator( flags
, startPos
);
378 wxPropertyGridConstIterator
GetIterator( int flags
, int startPos
) const
380 wxFAIL_MSG( "Please only iterate through individual pages "
381 "or use CreateVIterator()" );
382 return wxPropertyGridInterface::GetIterator( flags
, startPos
);
385 /** Similar to GetIterator, but instead returns wxPGVIterator instance,
386 which can be useful for forward-iterating through arbitrary property
389 virtual wxPGVIterator
GetVIterator( int flags
) const;
391 /** Returns currently selected page.
393 wxPropertyGridPage
* GetCurrentPage() const
395 return GetPage(m_selPage
);
398 /** Returns page object for given page index.
400 wxPropertyGridPage
* GetPage( unsigned int ind
) const
402 return m_arrPages
[ind
];
405 /** Returns page object for given page name.
407 wxPropertyGridPage
* GetPage( const wxString
& name
) const
409 return GetPage(GetPageByName(name
));
413 Returns index for a page name.
415 If no match is found, wxNOT_FOUND is returned.
417 int GetPageByName( const wxString
& name
) const;
419 /** Returns index for a relevant propertygrid state.
421 If no match is found, wxNOT_FOUND is returned.
423 int GetPageByState( const wxPropertyGridPageState
* pstate
) const;
426 /** Returns wxPropertyGridPageState of given page, current page's for -1.
428 virtual wxPropertyGridPageState
* GetPageState( int page
) const;
431 /** Returns number of managed pages. */
432 size_t GetPageCount() const;
434 /** Returns name of given page. */
435 const wxString
& GetPageName( int index
) const;
437 /** Returns "root property" of the given page. It does not have name, etc.
438 and it is not visible. It is only useful for accessing its children.
440 wxPGProperty
* GetPageRoot( int index
) const;
442 /** Returns index to currently selected page. */
443 int GetSelectedPage() const { return m_selPage
; }
445 /** Alias for GetSelection(). */
446 wxPGProperty
* GetSelectedProperty() const
448 return GetSelection();
451 /** Shortcut for GetGrid()->GetSelection(). */
452 wxPGProperty
* GetSelection() const
454 return m_pPropGrid
->GetSelection();
457 /** Returns a pointer to the toolbar currently associated with the
458 wxPropertyGridManager (if any). */
459 wxToolBar
* GetToolBar() const { return m_pToolbar
; }
461 /** Creates new property page. Note that the first page is not created
464 Add to this position. -1 will add as the last item.
466 A label for the page. This may be shown as a toolbar tooltip etc.
468 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
469 default image is used.
471 wxPropertyGridPage instance. Manager will take ownership of this object.
472 If NULL, default page object is constructed.
475 Returns pointer to created page.
477 virtual wxPropertyGridPage
* InsertPage( int index
,
478 const wxString
& label
,
479 const wxBitmap
& bmp
= wxNullBitmap
,
480 wxPropertyGridPage
* pageObj
= NULL
);
483 Returns true if any property on any page has been modified by the user.
485 bool IsAnyModified() const;
488 Returns true if updating is frozen (ie Freeze() called but not yet
491 bool IsFrozen() const { return m_pPropGrid
->m_frozen
> 0; }
494 Returns true if any property on given page has been modified by the
497 bool IsPageModified( size_t index
) const;
500 Returns true if property is selected. Since selection is page
501 based, this function checks every page in the manager.
503 virtual bool IsPropertySelected( wxPGPropArg id
) const;
505 virtual void Refresh( bool eraseBackground
= true,
506 const wxRect
* rect
= (const wxRect
*) NULL
);
510 Returns false if it was not possible to remove page in question.
512 virtual bool RemovePage( int page
);
514 /** Select and displays a given page.
517 Index of page being seleced. Can be -1 to select nothing.
519 void SelectPage( int index
);
521 /** Select and displays a given page (by label). */
522 void SelectPage( const wxString
& label
)
524 int index
= GetPageByName(label
);
525 wxCHECK_RET( index
>= 0, wxT("No page with such name") );
529 /** Select and displays a given page. */
530 void SelectPage( wxPropertyGridPage
* ptr
)
532 SelectPage( GetPageByState(ptr
) );
535 /** Select a property. */
536 bool SelectProperty( wxPGPropArg id
, bool focus
= false )
538 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
539 return p
->GetParentState()->DoSelectProperty(p
, focus
);
543 Sets a column title. Default title for column 0 is "Property",
544 and "Value" for column 1.
546 @remarks If header is not shown yet, then calling this
547 member function will make it visible.
549 void SetColumnTitle( int idx
, const wxString
& title
);
552 Sets number of columns on given page (default is current page).
554 @remarks If you use header, then you should always use this
555 member function to set the column count, instead of
556 ones present in wxPropertyGrid or wxPropertyGridPage.
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 );
578 Sets splitter position on individual page.
580 @remarks If you use header, then you should always use this
581 member function to set the splitter position, instead of
582 ones present in wxPropertyGrid or wxPropertyGridPage.
584 void SetPageSplitterPosition( int page
, int pos
, int column
= 0 );
587 Sets splitter position for all pages.
589 @remarks Splitter position cannot exceed grid size, and therefore
590 setting it during form creation may fail as initial grid
591 size is often smaller than desired splitter position,
592 especially when sizers are being used.
594 If you use header, then you should always use this
595 member function to set the splitter position, instead of
596 ones present in wxPropertyGrid or wxPropertyGridPage.
598 void SetSplitterPosition( int pos
, int column
= 0 );
602 Show or hide the property grid header control. It is hidden
605 @remarks Grid may look better if you use wxPG_NO_INTERNAL_BORDER
606 window style when showing a header.
608 void ShowHeader(bool show
= true);
614 // Subclassing helpers
618 Creates property grid for the manager. Reimplement in derived class to
619 use subclassed wxPropertyGrid. However, if you you do this then you
620 must also use the two-step construction (ie. default constructor and
621 Create() instead of constructor with arguments) when creating the
624 virtual wxPropertyGrid
* CreatePropertyGrid() const;
627 virtual void RefreshProperty( wxPGProperty
* p
);
630 // Overridden functions - no documentation required.
633 void SetId( wxWindowID winid
);
635 virtual void Freeze();
637 virtual void SetExtraStyle ( long exStyle
);
638 virtual bool SetFont ( const wxFont
& font
);
639 virtual void SetWindowStyleFlag ( long style
);
640 virtual bool Reparent( wxWindowBase
*newParent
);
645 virtual wxSize
DoGetBestSize() const;
650 void OnMouseMove( wxMouseEvent
&event
);
651 void OnMouseClick( wxMouseEvent
&event
);
652 void OnMouseUp( wxMouseEvent
&event
);
653 void OnMouseEntry( wxMouseEvent
&event
);
655 void OnPaint( wxPaintEvent
&event
);
657 void OnToolbarClick( wxCommandEvent
&event
);
658 void OnResize( wxSizeEvent
& event
);
659 void OnPropertyGridSelect( wxPropertyGridEvent
& event
);
660 void OnPGColDrag( wxPropertyGridEvent
& event
);
663 wxPropertyGrid
* m_pPropGrid
;
665 wxVector
<wxPropertyGridPage
*> m_arrPages
;
668 wxToolBar
* m_pToolbar
;
671 wxPGHeaderCtrl
* m_pHeaderCtrl
;
673 wxStaticText
* m_pTxtHelpCaption
;
674 wxStaticText
* m_pTxtHelpContent
;
676 wxPropertyGridPage
* m_emptyPage
;
678 wxArrayString m_columnLabels
;
682 // Selected page index.
693 int m_splitterHeight
;
699 wxCursor m_cursorSizeNS
;
701 int m_nextDescBoxSize
;
705 unsigned char m_dragStatus
;
707 unsigned char m_onSplitter
;
711 virtual wxPGProperty
* DoGetPropertyByName( const wxString
& name
) const;
713 /** Select and displays a given page. */
714 virtual bool DoSelectPage( int index
);
716 // Sets some members to defaults.
719 // Initializes some members.
720 void Init2( int style
);
723 virtual WXDWORD MSWGetStyle(long flags, WXDWORD *exstyle) const;
726 virtual bool ProcessEvent( wxEvent
& event
);
728 /** Recalculates new positions for components, according to the
731 void RecalculatePositions( int width
, int height
);
733 /** (Re)creates/destroys controls, according to the window style bits. */
734 void RecreateControls();
736 void UpdateDescriptionBox( int new_splittery
, int new_width
, int new_height
);
738 void RepaintDescBoxDecorations( wxDC
& dc
,
743 void SetDescribedProperty( wxPGProperty
* p
);
745 // Reimplement these to handle "descboxheight" state item
746 virtual bool SetEditableStateItem( const wxString
& name
, wxVariant value
);
747 virtual wxVariant
GetEditableStateItem( const wxString
& name
) const;
750 DECLARE_EVENT_TABLE()
751 #endif // #ifndef SWIG
754 // -----------------------------------------------------------------------
756 inline int wxPropertyGridPage::GetIndex() const
760 return m_manager
->GetPageByState(this);
763 // -----------------------------------------------------------------------
765 #endif // wxUSE_PROPGRID
767 #endif // _WX_PROPGRID_MANAGER_H_