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