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