AddPage(), InsertPage() now return page ptr instead of index
[wxWidgets.git] / include / wx / propgrid / manager.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/propgrid/manager.h
3 // Purpose: wxPropertyGridManager
4 // Author: Jaakko Salli
5 // Modified by:
6 // Created: 2005-01-14
7 // RCS-ID: $Id:
8 // Copyright: (c) Jaakko Salli
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_PROPGRID_MANAGER_H_
13 #define _WX_PROPGRID_MANAGER_H_
14
15 #if wxUSE_PROPGRID
16
17 #include "wx/propgrid/propgrid.h"
18
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
27 // -----------------------------------------------------------------------
28
29 #ifndef SWIG
30 extern WXDLLIMPEXP_PROPGRID const wxChar *wxPropertyGridManagerNameStr;
31 #endif
32
33 /** @class wxPropertyGridPage
34
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.
41
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.
45
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.
49
50 @section propgridpage_event_handling Event Handling
51
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.
56
57 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
58 for more information.
59
60 @library{wxpropgrid}
61 @category{propgrid}
62 */
63 class WXDLLIMPEXP_PROPGRID wxPropertyGridPage : public wxEvtHandler,
64 public wxPropertyGridInterface,
65 public wxPropertyGridPageState
66 {
67 friend class wxPropertyGridManager;
68 #ifndef SWIG
69 DECLARE_CLASS(wxPropertyGridPage)
70 #endif
71 public:
72
73 wxPropertyGridPage();
74 virtual ~wxPropertyGridPage();
75
76 /** Deletes all properties on page.
77 */
78 virtual void Clear();
79
80 /**
81 Reduces column sizes to minimum possible that contents are still
82 visibly (naturally some margin space will be applied as well).
83
84 @return
85 Minimum size for the page to still display everything.
86
87 @remarks
88 This function only works properly if size of containing grid was
89 already fairly large.
90
91 Note that you can also get calculated column widths by calling
92 GetColumnWidth() immediately after this function returns.
93 */
94 wxSize FitColumns();
95
96 /** Returns page index in manager;
97 */
98 inline int GetIndex() const;
99
100 /** Returns x-coordinate position of splitter on a page.
101 */
102 int GetSplitterPosition( int col = 0 ) const
103 { return GetStatePtr()->DoGetSplitterPosition(col); }
104
105 /** Returns "root property". It does not have name, etc. and it is not
106 visible. It is only useful for accessing its children.
107 */
108 wxPGProperty* GetRoot() const { return GetStatePtr()->DoGetRoot(); }
109
110 /** Return pointer to contained property grid state.
111 */
112 wxPropertyGridPageState* GetStatePtr()
113 {
114 return this;
115 }
116
117 /** Return pointer to contained property grid state.
118 */
119 const wxPropertyGridPageState* GetStatePtr() const
120 {
121 return this;
122 }
123
124 /**
125 Returns id of the tool bar item that represents this page on
126 wxPropertyGridManager's wxToolBar.
127 */
128 int GetToolId() const
129 {
130 return m_id;
131 }
132
133 /** Do any member initialization in this method.
134 @remarks
135 - Called every time the page is added into a manager.
136 - You can add properties to the page here.
137 */
138 virtual void Init() {}
139
140 /** Return false here to indicate unhandled events should be
141 propagated to manager's parent, as normal.
142 */
143 virtual bool IsHandlingAllEvents() const { return true; }
144
145 /** Called every time page is about to be shown.
146 Useful, for instance, creating properties just-in-time.
147 */
148 virtual void OnShow();
149
150 virtual void RefreshProperty( wxPGProperty* p );
151
152 /** Sets splitter position on page.
153 @remarks
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.
157 */
158 void SetSplitterPosition( int splitterPos, int col = 0 );
159
160 protected:
161
162 /** Propagate to other pages.
163 */
164 virtual void DoSetSplitterPosition( int pos,
165 int splitterColumn = 0,
166 bool allPages = false );
167
168 /** Propagate to other pages.
169 */
170 void DoSetSplitterPositionThisPage( int pos, int splitterColumn = 0 )
171 {
172 wxPropertyGridPageState::DoSetSplitterPosition( pos, splitterColumn );
173 }
174
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.
178 */
179 wxString m_label;
180
181 #ifndef SWIG
182
183 //virtual bool ProcessEvent( wxEvent& event );
184
185 wxPropertyGridManager* m_manager;
186
187 int m_id; // toolbar index
188
189 private:
190 bool m_isDefault; // is this base page object?
191
192 private:
193 DECLARE_EVENT_TABLE()
194 #endif
195 };
196
197 // -----------------------------------------------------------------------
198
199 /** @class wxPropertyGridManager
200
201 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
202 which can optionally have toolbar for mode and page selection, and help
203 text box.
204 Use window flags to select components to include.
205
206 @section propgridmanager_window_styles_ Window Styles
207
208 See @ref propgrid_window_styles.
209
210 @section propgridmanager_event_handling Event Handling
211
212 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
213 for more information.
214
215 @library{wxpropgrid}
216 @category{propgrid}
217 */
218 class WXDLLIMPEXP_PROPGRID
219 wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
220 {
221 #ifndef SWIG
222 DECLARE_CLASS(wxPropertyGridManager)
223 #endif
224 friend class wxPropertyGridPage;
225 public:
226
227 #ifdef SWIG
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 = {}
235 }
236 %pythonAppend wxPropertyGridManager() ""
237
238 wxPropertyGridManager( wxWindow *parent, wxWindowID id = wxID_ANY,
239 const wxPoint& pos = wxDefaultPosition,
240 const wxSize& size = wxDefaultSize,
241 long style = wxPGMAN_DEFAULT_STYLE,
242 const wxChar* name =
243 wxPyPropertyGridManagerNameStr );
244 %RenameCtor(PrePropertyGridManager, wxPropertyGridManager());
245
246 #else
247
248 /**
249 Two step constructor.
250 Call Create when this constructor is called to build up the
251 wxPropertyGridManager.
252 */
253 wxPropertyGridManager();
254
255 /** The default constructor. The styles to be used are styles valid for
256 the wxWindow.
257 @see @link wndflags Additional Window Styles@endlink
258 */
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 );
264
265 /** Destructor */
266 virtual ~wxPropertyGridManager();
267
268 #endif
269
270 /** Creates new property page. Note that the first page is not created
271 automatically.
272 @param label
273 A label for the page. This may be shown as a toolbar tooltip etc.
274 @param bmp
275 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
276 default image is used.
277 @param pageObj
278 wxPropertyGridPage instance. Manager will take ownership of this object.
279 NULL indicates that a default page instance should be created.
280
281 @return
282 Returns pointer to created page.
283
284 @remarks
285 If toolbar is used, it is highly recommended that the pages are
286 added when the toolbar is not turned off using window style flag
287 switching.
288 */
289 wxPropertyGridPage* AddPage( const wxString& label = wxEmptyString,
290 const wxBitmap& bmp = wxPG_NULL_BITMAP,
291 wxPropertyGridPage* pageObj = NULL )
292 {
293 return InsertPage(-1, label, bmp, pageObj);
294 }
295
296 void ClearModifiedStatus ( wxPGPropArg id );
297
298 void ClearModifiedStatus ()
299 {
300 m_pPropGrid->ClearModifiedStatus();
301 }
302
303 /** Deletes all all properties and all pages.
304 */
305 virtual void Clear();
306
307 /** Deletes all properties on given page.
308 */
309 void ClearPage( int page );
310
311 /** Forces updating the value of property from the editor control.
312 Returns true if DoPropertyChanged was actually called.
313 */
314 bool CommitChangesFromEditor( wxUint32 flags = 0 )
315 {
316 return m_pPropGrid->CommitChangesFromEditor(flags);
317 }
318
319 /**
320 Two step creation.
321 Whenever the control is created without any parameters, use Create to
322 actually create it. Don't access the control's public methods before
323 this is called.
324 @see @link wndflags Additional Window Styles@endlink
325 */
326 bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
327 const wxPoint& pos = wxDefaultPosition,
328 const wxSize& size = wxDefaultSize,
329 long style = wxPGMAN_DEFAULT_STYLE,
330 const wxChar* name = wxPropertyGridManagerNameStr );
331
332 /**
333 Enables or disables (shows/hides) categories according to parameter
334 enable.
335
336 WARNING: Not tested properly, use at your own risk.
337 */
338 bool EnableCategories( bool enable )
339 {
340 long fl = m_windowStyle | wxPG_HIDE_CATEGORIES;
341 if ( enable ) fl = m_windowStyle & ~(wxPG_HIDE_CATEGORIES);
342 SetWindowStyleFlag(fl);
343 return true;
344 }
345
346 /** Selects page, scrolls and/or expands items to ensure that the
347 given item is visible. Returns true if something was actually done.
348 */
349 bool EnsureVisible( wxPGPropArg id );
350
351 /** Returns number of children of the root property of the selected page. */
352 size_t GetChildrenCount()
353 {
354 return GetChildrenCount( m_pPropGrid->m_pState->m_properties );
355 }
356
357 /** Returns number of children of the root property of given page. */
358 size_t GetChildrenCount( int pageIndex );
359
360 /** Returns number of children for the property.
361
362 NB: Cannot be in container methods class due to name hiding.
363 */
364 size_t GetChildrenCount( wxPGPropArg id ) const
365 {
366 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
367 return p->GetChildCount();
368 }
369
370 /** Returns number of columns on given page. By the default,
371 returns number of columns on current page. */
372 int GetColumnCount( int page = -1 ) const;
373
374 /** Returns height of the description text box. */
375 int GetDescBoxHeight() const;
376
377 /** Returns pointer to the contained wxPropertyGrid. This does not change
378 after wxPropertyGridManager has been created, so you can safely obtain
379 pointer once and use it for the entire lifetime of the instance.
380 */
381 wxPropertyGrid* GetGrid()
382 {
383 wxASSERT(m_pPropGrid);
384 return m_pPropGrid;
385 };
386
387 const wxPropertyGrid* GetGrid() const
388 {
389 wxASSERT(m_pPropGrid);
390 return (const wxPropertyGrid*)m_pPropGrid;
391 };
392
393 /** Returns iterator class instance.
394 @remarks
395 Calling this method in wxPropertyGridManager causes run-time assertion
396 failure. Please only iterate through individual pages or use
397 CreateVIterator().
398 */
399 wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
400 wxPGProperty* firstProp = NULL )
401 {
402 wxFAIL_MSG( "Please only iterate through individual pages "
403 "or use CreateVIterator()" );
404 return wxPropertyGridInterface::GetIterator( flags, firstProp );
405 }
406
407 wxPropertyGridConstIterator
408 GetIterator(int flags = wxPG_ITERATE_DEFAULT,
409 wxPGProperty* firstProp = NULL) const
410 {
411 wxFAIL_MSG( "Please only iterate through individual pages "
412 " or use CreateVIterator()" );
413 return wxPropertyGridInterface::GetIterator( flags, firstProp );
414 }
415
416 /** Returns iterator class instance.
417 @remarks
418 Calling this method in wxPropertyGridManager causes run-time assertion
419 failure. Please only iterate through individual pages or use
420 CreateVIterator().
421 */
422 wxPropertyGridIterator GetIterator( int flags, int startPos )
423 {
424 wxFAIL_MSG( "Please only iterate through individual pages "
425 "or use CreateVIterator()" );
426
427 return wxPropertyGridInterface::GetIterator( flags, startPos );
428 }
429
430 wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
431 {
432 wxFAIL_MSG( "Please only iterate through individual pages "
433 "or use CreateVIterator()" );
434 return wxPropertyGridInterface::GetIterator( flags, startPos );
435 }
436
437 /** Similar to GetIterator, but instead returns wxPGVIterator instance,
438 which can be useful for forward-iterating through arbitrary property
439 containers.
440 */
441 virtual wxPGVIterator GetVIterator( int flags ) const;
442
443 /** Returns currently selected page.
444 */
445 wxPropertyGridPage* GetCurrentPage() const
446 {
447 return GetPage(m_selPage);
448 }
449
450 /** Returns page object for given page index.
451 */
452 wxPropertyGridPage* GetPage( unsigned int ind ) const
453 {
454 return (wxPropertyGridPage*)m_arrPages.Item(ind);
455 }
456
457 /** Returns page object for given page name.
458 */
459 wxPropertyGridPage* GetPage( const wxString& name ) const
460 {
461 return GetPage(GetPageByName(name));
462 }
463
464 /**
465 Returns index for a page name.
466
467 If no match is found, wxNOT_FOUND is returned.
468 */
469 int GetPageByName( const wxString& name ) const;
470
471 /** Returns index for a relevant propertygrid state.
472
473 If no match is found, wxNOT_FOUND is returned.
474 */
475 int GetPageByState( const wxPropertyGridPageState* pstate ) const;
476
477 /** Returns wxPropertyGridPageState of given page, current page's for -1.
478 */
479 virtual wxPropertyGridPageState* GetPageState( int page ) const;
480
481 /** Returns number of managed pages. */
482 size_t GetPageCount() const;
483
484 /** Returns name of given page. */
485 const wxString& GetPageName( int index ) const;
486
487 /** Returns "root property" of the given page. It does not have name, etc.
488 and it is not visible. It is only useful for accessing its children.
489 */
490 wxPGProperty* GetPageRoot( int index ) const;
491
492 /** Returns index to currently selected page. */
493 int GetSelectedPage() const { return m_selPage; }
494
495 /** Shortcut for GetGrid()->GetSelection(). */
496 wxPGProperty* GetSelection() const
497 {
498 return m_pPropGrid->GetSelection();
499 }
500
501 /** Returns a pointer to the toolbar currently associated with the
502 wxPropertyGridManager (if any). */
503 wxToolBar* GetToolBar() const { return m_pToolbar; }
504
505 /** Creates new property page. Note that the first page is not created
506 automatically.
507 @param index
508 Add to this position. -1 will add as the last item.
509 @param label
510 A label for the page. This may be shown as a toolbar tooltip etc.
511 @param bmp
512 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
513 default image is used.
514 @param pageObj
515 wxPropertyGridPage instance. Manager will take ownership of this object.
516 If NULL, default page object is constructed.
517
518 @return
519 Returns pointer to created page.
520 */
521 virtual wxPropertyGridPage* InsertPage( int index,
522 const wxString& label,
523 const wxBitmap& bmp = wxNullBitmap,
524 wxPropertyGridPage* pageObj = NULL );
525
526 /**
527 Returns true if any property on any page has been modified by the user.
528 */
529 bool IsAnyModified() const;
530
531 /**
532 Returns true if updating is frozen (ie Freeze() called but not yet
533 Thaw() ).
534 */
535 bool IsFrozen() const { return m_pPropGrid->m_frozen > 0; }
536
537 /**
538 Returns true if any property on given page has been modified by the
539 user.
540 */
541 bool IsPageModified( size_t index ) const;
542
543 virtual void Refresh( bool eraseBackground = true,
544 const wxRect* rect = (const wxRect*) NULL );
545
546 /** Removes a page.
547 @return
548 Returns false if it was not possible to remove page in question.
549 */
550 virtual bool RemovePage( int page );
551
552 /** Select and displays a given page.
553
554 @param index
555 Index of page being seleced. Can be -1 to select nothing.
556 */
557 void SelectPage( int index );
558
559 /** Select and displays a given page (by label). */
560 void SelectPage( const wxString& label )
561 {
562 int index = GetPageByName(label);
563 wxCHECK_RET( index >= 0, wxT("No page with such name") );
564 SelectPage( index );
565 }
566
567 /** Select and displays a given page. */
568 void SelectPage( wxPropertyGridPage* ptr )
569 {
570 SelectPage( GetPageByState(ptr) );
571 }
572
573 /** Select a property. */
574 bool SelectProperty( wxPGPropArg id, bool focus = false )
575 {
576 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
577 return p->GetParentState()->DoSelectProperty(p, focus);
578 }
579
580 /** Sets number of columns on given page (default is current page).
581 */
582 void SetColumnCount( int colCount, int page = -1 );
583
584 /** Sets label and text in description box.
585 */
586 void SetDescription( const wxString& label, const wxString& content );
587
588 /** Sets y coordinate of the description box splitter. */
589 void SetDescBoxHeight( int ht, bool refresh = true );
590
591 /** Moves splitter as left as possible, while still allowing all
592 labels to be shown in full.
593 @param subProps
594 If false, will still allow sub-properties (ie. properties which
595 parent is not root or category) to be cropped.
596 @param allPages
597 If true, takes labels on all pages into account.
598 */
599 void SetSplitterLeft( bool subProps = false, bool allPages = true );
600
601 /** Sets splitter position on individual page. */
602 void SetPageSplitterPosition( int page, int pos, int column = 0 )
603 {
604 GetPage(page)->DoSetSplitterPosition( pos, column );
605 }
606
607 /** Sets splitter position for all pages.
608 @remarks
609 Splitter position cannot exceed grid size, and therefore setting it
610 during form creation may fail as initial grid size is often smaller
611 than desired splitter position, especially when sizers are being used.
612 */
613 void SetSplitterPosition( int pos, int column = 0 );
614
615 #ifdef SWIG
616 %pythoncode {
617 def GetValuesFromPage(self,
618 page,
619 dict_=None,
620 as_strings=False,
621 inc_attributes=False):
622 "Same as GetValues, but returns values from specific page only."
623 "For argument descriptions, see GetValues."
624 return page.GetPropertyValues(dict_, as_strings, inc_attributes)
625 }
626 #endif
627
628 protected:
629
630 //
631 // Subclassing helpers
632 //
633
634 /** Creates property grid for the manager. Override to use subclassed
635 wxPropertyGrid.
636 */
637 virtual wxPropertyGrid* CreatePropertyGrid() const;
638
639 virtual void RefreshProperty( wxPGProperty* p );
640
641 public:
642
643 #ifndef DOXYGEN
644
645 //
646 // Overridden functions - no documentation required.
647 //
648
649 virtual wxSize DoGetBestSize() const;
650 void SetId( wxWindowID winid );
651
652 virtual void Freeze();
653 virtual void Thaw();
654 virtual void SetExtraStyle ( long exStyle );
655 virtual bool SetFont ( const wxFont& font );
656 virtual void SetWindowStyleFlag ( long style );
657
658 protected:
659
660 public:
661
662 #ifndef SWIG
663
664 //
665 // Event handlers
666 //
667 void OnMouseMove( wxMouseEvent &event );
668 void OnMouseClick( wxMouseEvent &event );
669 void OnMouseUp( wxMouseEvent &event );
670 void OnMouseEntry( wxMouseEvent &event );
671
672 void OnPaint( wxPaintEvent &event );
673
674 void OnToolbarClick( wxCommandEvent &event );
675 void OnResize( wxSizeEvent& event );
676 void OnPropertyGridSelect( wxPropertyGridEvent& event );
677
678 protected:
679
680 wxPropertyGrid* m_pPropGrid;
681
682 wxArrayPtrVoid m_arrPages;
683
684 #if wxUSE_TOOLBAR
685 wxToolBar* m_pToolbar;
686 #endif
687 wxStaticText* m_pTxtHelpCaption;
688 wxStaticText* m_pTxtHelpContent;
689
690 wxPropertyGridPage* m_emptyPage;
691
692 long m_iFlags;
693
694 // Selected page index.
695 int m_selPage;
696
697 int m_width;
698
699 int m_height;
700
701 int m_extraHeight;
702
703 int m_splitterY;
704
705 int m_splitterHeight;
706
707 int m_nextTbInd;
708
709 int m_dragOffset;
710
711 wxCursor m_cursorSizeNS;
712
713 int m_nextDescBoxSize;
714
715 wxWindowID m_baseId;
716
717 unsigned char m_dragStatus;
718
719 unsigned char m_onSplitter;
720
721 virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
722
723 /** Select and displays a given page. */
724 virtual bool DoSelectPage( int index );
725
726 // Sets some members to defaults.
727 void Init1();
728
729 // Initializes some members.
730 void Init2( int style );
731
732 /*#ifdef __WXMSW__
733 virtual WXDWORD MSWGetStyle(long flags, WXDWORD *exstyle) const;
734 #endif*/
735
736 /** Recalculates new positions for components, according to the
737 given size.
738 */
739 void RecalculatePositions( int width, int height );
740
741 /** (Re)creates/destroys controls, according to the window style bits. */
742 void RecreateControls();
743
744 void RefreshHelpBox( int new_splittery, int new_width, int new_height );
745
746 void RepaintSplitter( wxDC& dc,
747 int new_splittery,
748 int new_width,
749 int new_height,
750 bool desc_too );
751
752 void SetDescribedProperty( wxPGProperty* p );
753
754 virtual bool ProcessEvent( wxEvent& event );
755
756 private:
757 DECLARE_EVENT_TABLE()
758 #endif // #ifndef SWIG
759 #endif // #ifndef DOXYGEN
760 };
761
762 // -----------------------------------------------------------------------
763
764 inline int wxPropertyGridPage::GetIndex() const
765 {
766 if ( !m_manager )
767 return wxNOT_FOUND;
768 return m_manager->GetPageByState(this);
769 }
770
771 // -----------------------------------------------------------------------
772
773 #endif // wxUSE_PROPGRID
774
775 #endif // _WX_PROPGRID_MANAGER_H_