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