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