Reduce ambiguity of selection functions in wxPropertyGridManager, make them better...
[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 @return
281 Returns index to the page created.
282 @remarks
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
285 switching.
286 */
287 int AddPage( const wxString& label = wxEmptyString,
288 const wxBitmap& bmp = wxPG_NULL_BITMAP,
289 wxPropertyGridPage* pageObj = (wxPropertyGridPage*) NULL )
290 {
291 return InsertPage(-1,label,bmp,pageObj);
292 }
293
294 void ClearModifiedStatus ( wxPGPropArg id );
295
296 void ClearModifiedStatus ()
297 {
298 m_pPropGrid->ClearModifiedStatus();
299 }
300
301 /** Deletes all all properties and all pages.
302 */
303 virtual void Clear();
304
305 /** Deletes all properties on given page.
306 */
307 void ClearPage( int page );
308
309 /** Forces updating the value of property from the editor control.
310 Returns true if DoPropertyChanged was actually called.
311 */
312 bool CommitChangesFromEditor( wxUint32 flags = 0 )
313 {
314 return m_pPropGrid->CommitChangesFromEditor(flags);
315 }
316
317 /**
318 Two step creation.
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
321 this is called.
322 @see @link wndflags Additional Window Styles@endlink
323 */
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 );
329
330 /**
331 Enables or disables (shows/hides) categories according to parameter
332 enable.
333
334 WARNING: Not tested properly, use at your own risk.
335 */
336 bool EnableCategories( bool enable )
337 {
338 long fl = m_windowStyle | wxPG_HIDE_CATEGORIES;
339 if ( enable ) fl = m_windowStyle & ~(wxPG_HIDE_CATEGORIES);
340 SetWindowStyleFlag(fl);
341 return true;
342 }
343
344 /** Selects page, scrolls and/or expands items to ensure that the
345 given item is visible. Returns true if something was actually done.
346 */
347 bool EnsureVisible( wxPGPropArg id );
348
349 /** Returns number of children of the root property of the selected page. */
350 size_t GetChildrenCount()
351 {
352 return GetChildrenCount( m_pPropGrid->m_pState->m_properties );
353 }
354
355 /** Returns number of children of the root property of given page. */
356 size_t GetChildrenCount( int pageIndex );
357
358 /** Returns number of children for the property.
359
360 NB: Cannot be in container methods class due to name hiding.
361 */
362 size_t GetChildrenCount( wxPGPropArg id ) const
363 {
364 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
365 return p->GetChildCount();
366 }
367
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;
371
372 /** Returns height of the description text box. */
373 int GetDescBoxHeight() const;
374
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.
378 */
379 wxPropertyGrid* GetGrid()
380 {
381 wxASSERT(m_pPropGrid);
382 return m_pPropGrid;
383 };
384
385 const wxPropertyGrid* GetGrid() const
386 {
387 wxASSERT(m_pPropGrid);
388 return (const wxPropertyGrid*)m_pPropGrid;
389 };
390
391 /** Returns iterator class instance.
392 @remarks
393 Calling this method in wxPropertyGridManager causes run-time assertion
394 failure. Please only iterate through individual pages or use
395 CreateVIterator().
396 */
397 wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
398 wxPGProperty* firstProp = NULL )
399 {
400 wxFAIL_MSG( "Please only iterate through individual pages "
401 "or use CreateVIterator()" );
402 return wxPropertyGridInterface::GetIterator( flags, firstProp );
403 }
404
405 wxPropertyGridConstIterator
406 GetIterator(int flags = wxPG_ITERATE_DEFAULT,
407 wxPGProperty* firstProp = NULL) const
408 {
409 wxFAIL_MSG( "Please only iterate through individual pages "
410 " or use CreateVIterator()" );
411 return wxPropertyGridInterface::GetIterator( flags, firstProp );
412 }
413
414 /** Returns iterator class instance.
415 @remarks
416 Calling this method in wxPropertyGridManager causes run-time assertion
417 failure. Please only iterate through individual pages or use
418 CreateVIterator().
419 */
420 wxPropertyGridIterator GetIterator( int flags, int startPos )
421 {
422 wxFAIL_MSG( "Please only iterate through individual pages "
423 "or use CreateVIterator()" );
424
425 return wxPropertyGridInterface::GetIterator( flags, startPos );
426 }
427
428 wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
429 {
430 wxFAIL_MSG( "Please only iterate through individual pages "
431 "or use CreateVIterator()" );
432 return wxPropertyGridInterface::GetIterator( flags, startPos );
433 }
434
435 /** Similar to GetIterator, but instead returns wxPGVIterator instance,
436 which can be useful for forward-iterating through arbitrary property
437 containers.
438 */
439 virtual wxPGVIterator GetVIterator( int flags ) const;
440
441 /** Returns currently selected page.
442 */
443 wxPropertyGridPage* GetCurrentPage() const
444 {
445 return GetPage(m_selPage);
446 }
447
448 /** Returns last page.
449 */
450 wxPropertyGridPage* GetLastPage() const
451 {
452 return GetPage(m_arrPages.size()-1);
453 }
454
455 /** Returns page object for given page index.
456 */
457 wxPropertyGridPage* GetPage( unsigned int ind ) const
458 {
459 return (wxPropertyGridPage*)m_arrPages.Item(ind);
460 }
461
462 /** Returns page object for given page name.
463 */
464 wxPropertyGridPage* GetPage( const wxString& name ) const
465 {
466 return GetPage(GetPageByName(name));
467 }
468
469 /**
470 Returns index for a page name.
471
472 If no match is found, wxNOT_FOUND is returned.
473 */
474 int GetPageByName( const wxString& name ) const;
475
476 /** Returns index for a relevant propertygrid state.
477
478 If no match is found, wxNOT_FOUND is returned.
479 */
480 int GetPageByState( const wxPropertyGridPageState* pstate ) const;
481
482 /** Returns wxPropertyGridPageState of given page, current page's for -1.
483 */
484 virtual wxPropertyGridPageState* GetPageState( int page ) const;
485
486 /** Returns number of managed pages. */
487 size_t GetPageCount() const;
488
489 /** Returns name of given page. */
490 const wxString& GetPageName( int index ) const;
491
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.
494 */
495 wxPGProperty* GetPageRoot( int index ) const;
496
497 /** Returns index to currently selected page. */
498 int GetSelectedPage() const { return m_selPage; }
499
500 /** Shortcut for GetGrid()->GetSelection(). */
501 wxPGProperty* GetSelection() const
502 {
503 return m_pPropGrid->GetSelection();
504 }
505
506 /** Returns a pointer to the toolbar currently associated with the
507 wxPropertyGridManager (if any). */
508 wxToolBar* GetToolBar() const { return m_pToolbar; }
509
510 /** Creates new property page. Note that the first page is not created
511 automatically.
512 @param index
513 Add to this position. -1 will add as the last item.
514 @param label
515 A label for the page. This may be shown as a toolbar tooltip etc.
516 @param bmp
517 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
518 default image is used.
519 @param pageObj
520 wxPropertyGridPage instance. Manager will take ownership of this object.
521 If NULL, default page object is constructed.
522 @return
523 Returns index to the page created.
524 */
525 virtual int InsertPage( int index,
526 const wxString& label,
527 const wxBitmap& bmp = wxNullBitmap,
528 wxPropertyGridPage* pageObj = NULL );
529
530 /**
531 Returns true if any property on any page has been modified by the user.
532 */
533 bool IsAnyModified() const;
534
535 /**
536 Returns true if updating is frozen (ie Freeze() called but not yet
537 Thaw() ).
538 */
539 bool IsFrozen() const { return m_pPropGrid->m_frozen > 0; }
540
541 /**
542 Returns true if any property on given page has been modified by the
543 user.
544 */
545 bool IsPageModified( size_t index ) const;
546
547 virtual void Refresh( bool eraseBackground = true,
548 const wxRect* rect = (const wxRect*) NULL );
549
550 /** Removes a page.
551 @return
552 Returns false if it was not possible to remove page in question.
553 */
554 virtual bool RemovePage( int page );
555
556 /** Select and displays a given page.
557
558 @param index
559 Index of page being seleced. Can be -1 to select nothing.
560 */
561 void SelectPage( int index );
562
563 /** Select and displays a given page (by label). */
564 void SelectPage( const wxString& label )
565 {
566 int index = GetPageByName(label);
567 wxCHECK_RET( index >= 0, wxT("No page with such name") );
568 SelectPage( index );
569 }
570
571 /** Select and displays a given page. */
572 void SelectPage( wxPropertyGridPage* ptr )
573 {
574 SelectPage( GetPageByState(ptr) );
575 }
576
577 /** Select a property. */
578 bool SelectProperty( wxPGPropArg id, bool focus = false )
579 {
580 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
581 return p->GetParentState()->DoSelectProperty(p, focus);
582 }
583
584 /** Sets number of columns on given page (default is current page).
585 */
586 void SetColumnCount( int colCount, int page = -1 );
587
588 /** Sets label and text in description box.
589 */
590 void SetDescription( const wxString& label, const wxString& content );
591
592 /** Sets y coordinate of the description box splitter. */
593 void SetDescBoxHeight( int ht, bool refresh = true );
594
595 /** Moves splitter as left as possible, while still allowing all
596 labels to be shown in full.
597 @param subProps
598 If false, will still allow sub-properties (ie. properties which
599 parent is not root or category) to be cropped.
600 @param allPages
601 If true, takes labels on all pages into account.
602 */
603 void SetSplitterLeft( bool subProps = false, bool allPages = true );
604
605 /** Sets splitter position on individual page. */
606 void SetPageSplitterPosition( int page, int pos, int column = 0 )
607 {
608 GetPage(page)->DoSetSplitterPosition( pos, column );
609 }
610
611 /** Sets splitter position for all pages.
612 @remarks
613 Splitter position cannot exceed grid size, and therefore setting it
614 during form creation may fail as initial grid size is often smaller
615 than desired splitter position, especially when sizers are being used.
616 */
617 void SetSplitterPosition( int pos, int column = 0 );
618
619 #ifdef SWIG
620 %pythoncode {
621 def GetValuesFromPage(self,
622 page,
623 dict_=None,
624 as_strings=False,
625 inc_attributes=False):
626 "Same as GetValues, but returns values from specific page only."
627 "For argument descriptions, see GetValues."
628 return page.GetPropertyValues(dict_, as_strings, inc_attributes)
629 }
630 #endif
631
632 protected:
633
634 //
635 // Subclassing helpers
636 //
637
638 /** Creates property grid for the manager. Override to use subclassed
639 wxPropertyGrid.
640 */
641 virtual wxPropertyGrid* CreatePropertyGrid() const;
642
643 virtual void RefreshProperty( wxPGProperty* p );
644
645 public:
646
647 #ifndef DOXYGEN
648
649 //
650 // Overridden functions - no documentation required.
651 //
652
653 virtual wxSize DoGetBestSize() const;
654 void SetId( wxWindowID winid );
655
656 virtual void Freeze();
657 virtual void Thaw();
658 virtual void SetExtraStyle ( long exStyle );
659 virtual bool SetFont ( const wxFont& font );
660 virtual void SetWindowStyleFlag ( long style );
661
662 protected:
663
664 public:
665
666 #ifndef SWIG
667
668 //
669 // Event handlers
670 //
671 void OnMouseMove( wxMouseEvent &event );
672 void OnMouseClick( wxMouseEvent &event );
673 void OnMouseUp( wxMouseEvent &event );
674 void OnMouseEntry( wxMouseEvent &event );
675
676 void OnPaint( wxPaintEvent &event );
677
678 void OnToolbarClick( wxCommandEvent &event );
679 void OnResize( wxSizeEvent& event );
680 void OnPropertyGridSelect( wxPropertyGridEvent& event );
681
682 protected:
683
684 wxPropertyGrid* m_pPropGrid;
685
686 wxArrayPtrVoid m_arrPages;
687
688 #if wxUSE_TOOLBAR
689 wxToolBar* m_pToolbar;
690 #endif
691 wxStaticText* m_pTxtHelpCaption;
692 wxStaticText* m_pTxtHelpContent;
693
694 wxPropertyGridPage* m_emptyPage;
695
696 long m_iFlags;
697
698 // Selected page index.
699 int m_selPage;
700
701 int m_width;
702
703 int m_height;
704
705 int m_extraHeight;
706
707 int m_splitterY;
708
709 int m_splitterHeight;
710
711 int m_nextTbInd;
712
713 int m_dragOffset;
714
715 wxCursor m_cursorSizeNS;
716
717 int m_nextDescBoxSize;
718
719 wxWindowID m_baseId;
720
721 unsigned char m_dragStatus;
722
723 unsigned char m_onSplitter;
724
725 virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
726
727 /** Select and displays a given page. */
728 virtual bool DoSelectPage( int index );
729
730 // Sets some members to defaults.
731 void Init1();
732
733 // Initializes some members.
734 void Init2( int style );
735
736 /*#ifdef __WXMSW__
737 virtual WXDWORD MSWGetStyle(long flags, WXDWORD *exstyle) const;
738 #endif*/
739
740 /** Recalculates new positions for components, according to the
741 given size.
742 */
743 void RecalculatePositions( int width, int height );
744
745 /** (Re)creates/destroys controls, according to the window style bits. */
746 void RecreateControls();
747
748 void RefreshHelpBox( int new_splittery, int new_width, int new_height );
749
750 void RepaintSplitter( wxDC& dc,
751 int new_splittery,
752 int new_width,
753 int new_height,
754 bool desc_too );
755
756 void SetDescribedProperty( wxPGProperty* p );
757
758 virtual bool ProcessEvent( wxEvent& event );
759
760 private:
761 DECLARE_EVENT_TABLE()
762 #endif // #ifndef SWIG
763 #endif // #ifndef DOXYGEN
764 };
765
766 // -----------------------------------------------------------------------
767
768 inline int wxPropertyGridPage::GetIndex() const
769 {
770 if ( !m_manager )
771 return wxNOT_FOUND;
772 return m_manager->GetPageByState(this);
773 }
774
775 // -----------------------------------------------------------------------
776
777 #endif // wxUSE_PROPGRID
778
779 #endif // _WX_PROPGRID_MANAGER_H_