]> git.saurik.com Git - wxWidgets.git/blob - include/wx/propgrid/manager.h
do override SetSplitterPosition() in wxPropertyGridPage: this was clearly meant to...
[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_DATA_PROPGRID(const char) 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 bool fromAutoCenter = false );
168
169 /** Propagate to other pages.
170 */
171 void DoSetSplitterPositionThisPage( int pos, int splitterColumn = 0 )
172 {
173 wxPropertyGridPageState::DoSetSplitterPosition( pos, splitterColumn );
174 }
175
176 /** Page label (may be referred as name in some parts of documentation).
177 Can be set in constructor, or passed in
178 wxPropertyGridManager::AddPage(), but *not* in both.
179 */
180 wxString m_label;
181
182 #ifndef SWIG
183
184 //virtual bool ProcessEvent( wxEvent& event );
185
186 wxPropertyGridManager* m_manager;
187
188 int m_id; // toolbar index
189
190 private:
191 bool m_isDefault; // is this base page object?
192
193 private:
194 DECLARE_EVENT_TABLE()
195 #endif
196 };
197
198 // -----------------------------------------------------------------------
199
200 /** @class wxPropertyGridManager
201
202 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
203 which can optionally have toolbar for mode and page selection, and help
204 text box.
205 Use window flags to select components to include.
206
207 @section propgridmanager_window_styles_ Window Styles
208
209 See @ref propgrid_window_styles.
210
211 @section propgridmanager_event_handling Event Handling
212
213 See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
214 for more information.
215
216 @library{wxpropgrid}
217 @category{propgrid}
218 */
219 class WXDLLIMPEXP_PROPGRID
220 wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
221 {
222 #ifndef SWIG
223 DECLARE_CLASS(wxPropertyGridManager)
224 #endif
225 friend class wxPropertyGridPage;
226 public:
227
228 #ifdef SWIG
229 %pythonAppend wxPropertyGridManager {
230 self._setOORInfo(self)
231 self.DoDefaultTypeMappings()
232 self.edited_objects = {}
233 self.DoDefaultValueTypeMappings()
234 if not hasattr(self.__class__,'_vt2setter'):
235 self.__class__._vt2setter = {}
236 }
237 %pythonAppend wxPropertyGridManager() ""
238
239 wxPropertyGridManager( wxWindow *parent, wxWindowID id = wxID_ANY,
240 const wxPoint& pos = wxDefaultPosition,
241 const wxSize& size = wxDefaultSize,
242 long style = wxPGMAN_DEFAULT_STYLE,
243 const wxChar* name =
244 wxPyPropertyGridManagerNameStr );
245 %RenameCtor(PrePropertyGridManager, wxPropertyGridManager());
246
247 #else
248
249 /**
250 Two step constructor.
251 Call Create when this constructor is called to build up the
252 wxPropertyGridManager.
253 */
254 wxPropertyGridManager();
255
256 /** The default constructor. The styles to be used are styles valid for
257 the wxWindow.
258 @see @link wndflags Additional Window Styles@endlink
259 */
260 wxPropertyGridManager( wxWindow *parent, wxWindowID id = wxID_ANY,
261 const wxPoint& pos = wxDefaultPosition,
262 const wxSize& size = wxDefaultSize,
263 long style = wxPGMAN_DEFAULT_STYLE,
264 const wxString& name = wxPropertyGridManagerNameStr );
265
266 /** Destructor */
267 virtual ~wxPropertyGridManager();
268
269 #endif
270
271 /** Creates new property page. Note that the first page is not created
272 automatically.
273 @param label
274 A label for the page. This may be shown as a toolbar tooltip etc.
275 @param bmp
276 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
277 default image is used.
278 @param pageObj
279 wxPropertyGridPage instance. Manager will take ownership of this object.
280 NULL indicates that a default page instance should be created.
281
282 @return
283 Returns pointer to created page.
284
285 @remarks
286 If toolbar is used, it is highly recommended that the pages are
287 added when the toolbar is not turned off using window style flag
288 switching.
289 */
290 wxPropertyGridPage* AddPage( const wxString& label = wxEmptyString,
291 const wxBitmap& bmp = wxPG_NULL_BITMAP,
292 wxPropertyGridPage* pageObj = NULL )
293 {
294 return InsertPage(-1, label, bmp, pageObj);
295 }
296
297 /** Deletes all all properties and all pages.
298 */
299 virtual void Clear();
300
301 /** Deletes all properties on given page.
302 */
303 void ClearPage( int page );
304
305 /** Forces updating the value of property from the editor control.
306 Returns true if DoPropertyChanged was actually called.
307 */
308 bool CommitChangesFromEditor( wxUint32 flags = 0 )
309 {
310 return m_pPropGrid->CommitChangesFromEditor(flags);
311 }
312
313 /**
314 Two step creation.
315 Whenever the control is created without any parameters, use Create to
316 actually create it. Don't access the control's public methods before
317 this is called.
318 @see @link wndflags Additional Window Styles@endlink
319 */
320 bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
321 const wxPoint& pos = wxDefaultPosition,
322 const wxSize& size = wxDefaultSize,
323 long style = wxPGMAN_DEFAULT_STYLE,
324 const wxString& name = wxPropertyGridManagerNameStr );
325
326 /**
327 Enables or disables (shows/hides) categories according to parameter
328 enable.
329
330 WARNING: Not tested properly, use at your own risk.
331 */
332 bool EnableCategories( bool enable )
333 {
334 long fl = m_windowStyle | wxPG_HIDE_CATEGORIES;
335 if ( enable ) fl = m_windowStyle & ~(wxPG_HIDE_CATEGORIES);
336 SetWindowStyleFlag(fl);
337 return true;
338 }
339
340 /** Selects page, scrolls and/or expands items to ensure that the
341 given item is visible. Returns true if something was actually done.
342 */
343 bool EnsureVisible( wxPGPropArg id );
344
345 /** Returns number of columns on given page. By the default,
346 returns number of columns on current page. */
347 int GetColumnCount( int page = -1 ) const;
348
349 /** Returns height of the description text box. */
350 int GetDescBoxHeight() const;
351
352 /** Returns pointer to the contained wxPropertyGrid. This does not change
353 after wxPropertyGridManager has been created, so you can safely obtain
354 pointer once and use it for the entire lifetime of the instance.
355 */
356 wxPropertyGrid* GetGrid()
357 {
358 wxASSERT(m_pPropGrid);
359 return m_pPropGrid;
360 };
361
362 const wxPropertyGrid* GetGrid() const
363 {
364 wxASSERT(m_pPropGrid);
365 return (const wxPropertyGrid*)m_pPropGrid;
366 };
367
368 /** Returns iterator class instance.
369 @remarks
370 Calling this method in wxPropertyGridManager causes run-time assertion
371 failure. Please only iterate through individual pages or use
372 CreateVIterator().
373 */
374 wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
375 wxPGProperty* firstProp = NULL )
376 {
377 wxFAIL_MSG( "Please only iterate through individual pages "
378 "or use CreateVIterator()" );
379 return wxPropertyGridInterface::GetIterator( flags, firstProp );
380 }
381
382 wxPropertyGridConstIterator
383 GetIterator(int flags = wxPG_ITERATE_DEFAULT,
384 wxPGProperty* firstProp = NULL) const
385 {
386 wxFAIL_MSG( "Please only iterate through individual pages "
387 " or use CreateVIterator()" );
388 return wxPropertyGridInterface::GetIterator( flags, firstProp );
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, int startPos )
398 {
399 wxFAIL_MSG( "Please only iterate through individual pages "
400 "or use CreateVIterator()" );
401
402 return wxPropertyGridInterface::GetIterator( flags, startPos );
403 }
404
405 wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
406 {
407 wxFAIL_MSG( "Please only iterate through individual pages "
408 "or use CreateVIterator()" );
409 return wxPropertyGridInterface::GetIterator( flags, startPos );
410 }
411
412 /** Similar to GetIterator, but instead returns wxPGVIterator instance,
413 which can be useful for forward-iterating through arbitrary property
414 containers.
415 */
416 virtual wxPGVIterator GetVIterator( int flags ) const;
417
418 /** Returns currently selected page.
419 */
420 wxPropertyGridPage* GetCurrentPage() const
421 {
422 return GetPage(m_selPage);
423 }
424
425 /** Returns page object for given page index.
426 */
427 wxPropertyGridPage* GetPage( unsigned int ind ) const
428 {
429 return m_arrPages[ind];
430 }
431
432 /** Returns page object for given page name.
433 */
434 wxPropertyGridPage* GetPage( const wxString& name ) const
435 {
436 return GetPage(GetPageByName(name));
437 }
438
439 /**
440 Returns index for a page name.
441
442 If no match is found, wxNOT_FOUND is returned.
443 */
444 int GetPageByName( const wxString& name ) const;
445
446 /** Returns index for a relevant propertygrid state.
447
448 If no match is found, wxNOT_FOUND is returned.
449 */
450 int GetPageByState( const wxPropertyGridPageState* pstate ) const;
451
452 /** Returns wxPropertyGridPageState of given page, current page's for -1.
453 */
454 virtual wxPropertyGridPageState* GetPageState( int page ) const;
455
456 /** Returns number of managed pages. */
457 size_t GetPageCount() const;
458
459 /** Returns name of given page. */
460 const wxString& GetPageName( int index ) const;
461
462 /** Returns "root property" of the given page. It does not have name, etc.
463 and it is not visible. It is only useful for accessing its children.
464 */
465 wxPGProperty* GetPageRoot( int index ) const;
466
467 /** Returns index to currently selected page. */
468 int GetSelectedPage() const { return m_selPage; }
469
470 /** Alias for GetSelection(). */
471 wxPGProperty* GetSelectedProperty() const
472 {
473 return GetSelection();
474 }
475
476 /** Shortcut for GetGrid()->GetSelection(). */
477 wxPGProperty* GetSelection() const
478 {
479 return m_pPropGrid->GetSelection();
480 }
481
482 /** Returns a pointer to the toolbar currently associated with the
483 wxPropertyGridManager (if any). */
484 wxToolBar* GetToolBar() const { return m_pToolbar; }
485
486 /** Creates new property page. Note that the first page is not created
487 automatically.
488 @param index
489 Add to this position. -1 will add as the last item.
490 @param label
491 A label for the page. This may be shown as a toolbar tooltip etc.
492 @param bmp
493 Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
494 default image is used.
495 @param pageObj
496 wxPropertyGridPage instance. Manager will take ownership of this object.
497 If NULL, default page object is constructed.
498
499 @return
500 Returns pointer to created page.
501 */
502 virtual wxPropertyGridPage* InsertPage( int index,
503 const wxString& label,
504 const wxBitmap& bmp = wxNullBitmap,
505 wxPropertyGridPage* pageObj = NULL );
506
507 /**
508 Returns true if any property on any page has been modified by the user.
509 */
510 bool IsAnyModified() const;
511
512 /**
513 Returns true if updating is frozen (ie Freeze() called but not yet
514 Thaw() ).
515 */
516 bool IsFrozen() const { return m_pPropGrid->m_frozen > 0; }
517
518 /**
519 Returns true if any property on given page has been modified by the
520 user.
521 */
522 bool IsPageModified( size_t index ) const;
523
524 virtual void Refresh( bool eraseBackground = true,
525 const wxRect* rect = (const wxRect*) NULL );
526
527 /** Removes a page.
528 @return
529 Returns false if it was not possible to remove page in question.
530 */
531 virtual bool RemovePage( int page );
532
533 /** Select and displays a given page.
534
535 @param index
536 Index of page being seleced. Can be -1 to select nothing.
537 */
538 void SelectPage( int index );
539
540 /** Select and displays a given page (by label). */
541 void SelectPage( const wxString& label )
542 {
543 int index = GetPageByName(label);
544 wxCHECK_RET( index >= 0, wxT("No page with such name") );
545 SelectPage( index );
546 }
547
548 /** Select and displays a given page. */
549 void SelectPage( wxPropertyGridPage* ptr )
550 {
551 SelectPage( GetPageByState(ptr) );
552 }
553
554 /** Select a property. */
555 bool SelectProperty( wxPGPropArg id, bool focus = false )
556 {
557 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
558 return p->GetParentState()->DoSelectProperty(p, focus);
559 }
560
561 /** Sets number of columns on given page (default is current page).
562 */
563 void SetColumnCount( int colCount, int page = -1 );
564
565 /** Sets label and text in description box.
566 */
567 void SetDescription( const wxString& label, const wxString& content );
568
569 /** Sets y coordinate of the description box splitter. */
570 void SetDescBoxHeight( int ht, bool refresh = true );
571
572 /** Moves splitter as left as possible, while still allowing all
573 labels to be shown in full.
574 @param subProps
575 If false, will still allow sub-properties (ie. properties which
576 parent is not root or category) to be cropped.
577 @param allPages
578 If true, takes labels on all pages into account.
579 */
580 void SetSplitterLeft( bool subProps = false, bool allPages = true );
581
582 /** Sets splitter position on individual page. */
583 void SetPageSplitterPosition( int page, int pos, int column = 0 )
584 {
585 GetPage(page)->DoSetSplitterPosition( pos, column );
586 }
587
588 /** Sets splitter position for all pages.
589 @remarks
590 Splitter position cannot exceed grid size, and therefore setting it
591 during form creation may fail as initial grid size is often smaller
592 than desired splitter position, especially when sizers are being used.
593 */
594 void SetSplitterPosition( int pos, int column = 0 );
595
596 #ifdef SWIG
597 %pythoncode {
598 def GetValuesFromPage(self,
599 page,
600 dict_=None,
601 as_strings=False,
602 inc_attributes=False):
603 "Same as GetValues, but returns values from specific page only."
604 "For argument descriptions, see GetValues."
605 return page.GetPropertyValues(dict_, as_strings, inc_attributes)
606 }
607 #endif
608
609 protected:
610
611 //
612 // Subclassing helpers
613 //
614
615 /** Creates property grid for the manager. Override to use subclassed
616 wxPropertyGrid.
617 */
618 virtual wxPropertyGrid* CreatePropertyGrid() const;
619
620 virtual void RefreshProperty( wxPGProperty* p );
621
622 public:
623
624 //
625 // Overridden functions - no documentation required.
626 //
627
628 virtual wxSize DoGetBestSize() const;
629 void SetId( wxWindowID winid );
630
631 virtual void Freeze();
632 virtual void Thaw();
633 virtual void SetExtraStyle ( long exStyle );
634 virtual bool SetFont ( const wxFont& font );
635 virtual void SetWindowStyleFlag ( long style );
636
637 protected:
638
639 public:
640
641 #ifndef SWIG
642
643 //
644 // Event handlers
645 //
646 void OnMouseMove( wxMouseEvent &event );
647 void OnMouseClick( wxMouseEvent &event );
648 void OnMouseUp( wxMouseEvent &event );
649 void OnMouseEntry( wxMouseEvent &event );
650
651 void OnPaint( wxPaintEvent &event );
652
653 void OnToolbarClick( wxCommandEvent &event );
654 void OnResize( wxSizeEvent& event );
655 void OnPropertyGridSelect( wxPropertyGridEvent& event );
656
657 protected:
658
659 wxPropertyGrid* m_pPropGrid;
660
661 wxVector<wxPropertyGridPage*> m_arrPages;
662
663 #if wxUSE_TOOLBAR
664 wxToolBar* m_pToolbar;
665 #endif
666 wxStaticText* m_pTxtHelpCaption;
667 wxStaticText* m_pTxtHelpContent;
668
669 wxPropertyGridPage* m_emptyPage;
670
671 long m_iFlags;
672
673 // Selected page index.
674 int m_selPage;
675
676 int m_width;
677
678 int m_height;
679
680 int m_extraHeight;
681
682 int m_splitterY;
683
684 int m_splitterHeight;
685
686 int m_nextTbInd;
687
688 int m_dragOffset;
689
690 wxCursor m_cursorSizeNS;
691
692 int m_nextDescBoxSize;
693
694 wxWindowID m_baseId;
695
696 unsigned char m_dragStatus;
697
698 unsigned char m_onSplitter;
699
700 virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
701
702 /** Select and displays a given page. */
703 virtual bool DoSelectPage( int index );
704
705 // Sets some members to defaults.
706 void Init1();
707
708 // Initializes some members.
709 void Init2( int style );
710
711 /*#ifdef __WXMSW__
712 virtual WXDWORD MSWGetStyle(long flags, WXDWORD *exstyle) const;
713 #endif*/
714
715 /** Recalculates new positions for components, according to the
716 given size.
717 */
718 void RecalculatePositions( int width, int height );
719
720 /** (Re)creates/destroys controls, according to the window style bits. */
721 void RecreateControls();
722
723 void RefreshHelpBox( int new_splittery, int new_width, int new_height );
724
725 void RepaintSplitter( wxDC& dc,
726 int new_splittery,
727 int new_width,
728 int new_height,
729 bool desc_too );
730
731 void SetDescribedProperty( wxPGProperty* p );
732
733 // Reimplement these to handle "descboxheight" state item
734 virtual bool SetEditableStateItem( const wxString& name, wxVariant value );
735 virtual wxVariant GetEditableStateItem( const wxString& name ) const;
736
737 virtual bool ProcessEvent( wxEvent& event );
738
739 private:
740 DECLARE_EVENT_TABLE()
741 #endif // #ifndef SWIG
742 };
743
744 // -----------------------------------------------------------------------
745
746 inline int wxPropertyGridPage::GetIndex() const
747 {
748 if ( !m_manager )
749 return wxNOT_FOUND;
750 return m_manager->GetPageByState(this);
751 }
752
753 // -----------------------------------------------------------------------
754
755 #endif // wxUSE_PROPGRID
756
757 #endif // _WX_PROPGRID_MANAGER_H_