]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/propgrid/propgrid.h
Added wxComboCtrl::SetHint(), GetHint()
[wxWidgets.git] / interface / wx / propgrid / propgrid.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: propgrid.h
3 // Purpose: interface of wxPropertyGrid
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9
10 /**
11 @section propgrid_window_styles wxPropertyGrid Window Styles
12
13 SetWindowStyleFlag method can be used to modify some of these at run-time.
14 @{
15 */
16 enum wxPG_WINDOW_STYLES
17 {
18
19 /**
20 This will cause Sort() automatically after an item is added.
21 When inserting a lot of items in this mode, it may make sense to
22 use Freeze() before operations and Thaw() afterwards to increase
23 performance.
24 */
25 wxPG_AUTO_SORT = 0x00000010,
26
27 /**
28 Categories are not initially shown (even if added).
29 IMPORTANT NOTE: If you do not plan to use categories, then this
30 style will waste resources.
31 This flag can also be changed using wxPropertyGrid::EnableCategories method.
32 */
33 wxPG_HIDE_CATEGORIES = 0x00000020,
34
35 /**
36 This style combines non-categoric mode and automatic sorting.
37 */
38 wxPG_ALPHABETIC_MODE = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
39
40 /**
41 Modified values are shown in bold font. Changing this requires Refresh()
42 to show changes.
43 */
44 wxPG_BOLD_MODIFIED = 0x00000040,
45
46 /**
47 When wxPropertyGrid is resized, splitter moves to the center. This
48 behavior stops once the user manually moves the splitter.
49 */
50 wxPG_SPLITTER_AUTO_CENTER = 0x00000080,
51
52 /**
53 Display tool tips for cell text that cannot be shown completely. If
54 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
55 */
56 wxPG_TOOLTIPS = 0x00000100,
57
58 /**
59 Disables margin and hides all expand/collapse buttons that would appear
60 outside the margin (for sub-properties). Toggling this style automatically
61 expands all collapsed items.
62 */
63 wxPG_HIDE_MARGIN = 0x00000200,
64
65 /**
66 This style prevents user from moving the splitter.
67 */
68 wxPG_STATIC_SPLITTER = 0x00000400,
69
70 /**
71 Combination of other styles that make it impossible for user to modify
72 the layout.
73 */
74 wxPG_STATIC_LAYOUT = (wxPG_HIDE_MARGIN|wxPG_STATIC_SPLITTER),
75
76 /**
77 Disables wxTextCtrl based editors for properties which
78 can be edited in another way. Equals calling
79 wxPropertyGrid::LimitPropertyEditing() for all added properties.
80 */
81 wxPG_LIMITED_EDITING = 0x00000800,
82
83 /**
84 wxPropertyGridManager only: Show tool bar for mode and page selection.
85 */
86 wxPG_TOOLBAR = 0x00001000,
87
88 /**
89 wxPropertyGridManager only: Show adjustable text box showing description
90 or help text, if available, for currently selected property.
91 */
92 wxPG_DESCRIPTION = 0x00002000,
93
94 /** wxPropertyGridManager only: don't show an internal border around the
95 property grid. Recommended if you use a header.
96 */
97 wxPG_NO_INTERNAL_BORDER = 0x00004000
98
99 };
100
101 enum wxPG_EX_WINDOW_STYLES
102 {
103
104 /**
105 NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
106 member function.
107
108 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
109 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not
110 activated, and switching the mode first time becomes somewhat slower.
111 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
112
113 NOTE: If you do plan not switching to non-categoric mode, or if
114 you don't plan to use categories at all, then using this style will result
115 in waste of resources.
116 */
117 wxPG_EX_INIT_NOCAT = 0x00001000,
118
119 /**
120 Extended window style that sets wxPropertyGridManager tool bar to not
121 use flat style.
122 */
123 wxPG_EX_NO_FLAT_TOOLBAR = 0x00002000,
124
125 /**
126 Shows alphabetic/categoric mode buttons from tool bar.
127 */
128 wxPG_EX_MODE_BUTTONS = 0x00008000,
129
130 /**
131 Show property help strings as tool tips instead as text on the status bar.
132 You can set the help strings using SetPropertyHelpString member function.
133 */
134 wxPG_EX_HELP_AS_TOOLTIPS = 0x00010000,
135
136 /**
137 Allows relying on native double-buffering.
138 */
139 wxPG_EX_NATIVE_DOUBLE_BUFFERING = 0x00080000,
140
141 /**
142 Set this style to let user have ability to set values of properties to
143 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
144 all properties.
145 */
146 wxPG_EX_AUTO_UNSPECIFIED_VALUES = 0x00200000,
147
148 /**
149 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and
150 wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus
151 they are not readable).
152
153 Note that this option is global, and applies to all wxPG property containers.
154 */
155 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES = 0x00400000,
156
157 /**
158 Hides page selection buttons from tool bar.
159 */
160 wxPG_EX_HIDE_PAGE_BUTTONS = 0x01000000,
161
162 /** Allows multiple properties to be selected by user (by pressing SHIFT
163 when clicking on a property, or by dragging with left mouse button
164 down).
165
166 You can get array of selected properties with
167 wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
168 mode wxPropertyGridInterface::GetSelection() returns
169 property which has editor active (usually the first one
170 selected). Other useful member functions are ClearSelection(),
171 AddToSelection() and RemoveFromSelection().
172 */
173 wxPG_EX_MULTIPLE_SELECTION = 0x02000000,
174
175 /**
176 This enables top-level window tracking which allows wxPropertyGrid to
177 notify the application of last-minute property value changes by user.
178
179 This style is not enabled by default because it may cause crashes when
180 wxPropertyGrid is used in with wxAUI or similar system.
181
182 @remarks If you are not in fact using any system that may change
183 wxPropertyGrid's top-level parent window on its own, then you
184 are recommended to enable this style.
185 */
186 wxPG_EX_ENABLE_TLP_TRACKING = 0x04000000,
187
188 /** Don't show divider above toolbar, on Windows.
189 */
190 wxPG_EX_NO_TOOLBAR_DIVIDER = 0x04000000,
191
192 /** Show a separator below the toolbar.
193 */
194 wxPG_EX_TOOLBAR_SEPARATOR = 0x08000000
195
196 };
197
198 /** Combines various styles.
199 */
200 #define wxPG_DEFAULT_STYLE (0)
201
202 /** Combines various styles.
203 */
204 #define wxPGMAN_DEFAULT_STYLE (0)
205
206 /** @}
207 */
208
209 // -----------------------------------------------------------------------
210
211 /**
212 @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
213 @{
214 */
215
216 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
217 {
218
219 /**
220 Prevents user from leaving property unless value is valid. If this
221 behavior flag is not used, then value change is instead cancelled.
222 */
223 wxPG_VFB_STAY_IN_PROPERTY = 0x01,
224
225 /**
226 Calls wxBell() on validation failure.
227 */
228 wxPG_VFB_BEEP = 0x02,
229
230 /**
231 Cell with invalid value will be marked (with red colour).
232 */
233 wxPG_VFB_MARK_CELL = 0x04,
234
235 /**
236 Display customizable text message explaining the situation.
237 */
238 wxPG_VFB_SHOW_MESSAGE = 0x08,
239
240 /**
241 Defaults.
242 */
243 wxPG_VFB_DEFAULT = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
244 };
245
246 /** @}
247 */
248
249 typedef wxByte wxPGVFBFlags;
250
251 /**
252 wxPGValidationInfo
253
254 Used to convey validation information to and from functions that
255 actually perform validation. Mostly used in custom property classes.
256 */
257 class wxPGValidationInfo
258 {
259 public:
260 /**
261 @return Returns failure behavior which is a combination of
262 @ref propgrid_vfbflags.
263 */
264 wxPGVFBFlags GetFailureBehavior();
265
266 /**
267 Returns current failure message.
268 */
269 const wxString& GetFailureMessage() const;
270
271 /**
272 Returns reference to pending value.
273 */
274 wxVariant& GetValue();
275
276 /** Set validation failure behavior
277
278 @param failureBehavior
279 Mixture of @ref propgrid_vfbflags.
280 */
281 void SetFailureBehavior(wxPGVFBFlags failureBehavior);
282
283 /**
284 Set current failure message.
285 */
286 void SetFailureMessage(const wxString& message);
287 };
288
289 // -----------------------------------------------------------------------
290
291 /**
292 @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
293
294 These are used with wxPropertyGrid::AddActionTrigger() and
295 wxPropertyGrid::ClearActionTriggers().
296 @{
297 */
298
299 enum wxPG_KEYBOARD_ACTIONS
300 {
301 wxPG_ACTION_INVALID = 0,
302 wxPG_ACTION_NEXT_PROPERTY,
303 wxPG_ACTION_PREV_PROPERTY,
304 wxPG_ACTION_EXPAND_PROPERTY,
305 wxPG_ACTION_COLLAPSE_PROPERTY,
306 wxPG_ACTION_CANCEL_EDIT,
307 wxPG_ACTION_MAX
308 };
309
310 /** @}
311 */
312
313 /** This callback function is used for sorting properties.
314
315 Call wxPropertyGrid::SetSortFunction() to set it.
316
317 Sort function should return a value greater than 0 if position of p1 is
318 after p2. So, for instance, when comparing property names, you can use
319 following implementation:
320
321 @code
322 int MyPropertySortFunction(wxPropertyGrid* propGrid,
323 wxPGProperty* p1,
324 wxPGProperty* p2)
325 {
326 return p1->GetBaseName().compare( p2->GetBaseName() );
327 }
328 @endcode
329 */
330 typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid,
331 wxPGProperty* p1,
332 wxPGProperty* p2);
333
334 // -----------------------------------------------------------------------
335
336 /**
337 @class wxPropertyGrid
338
339 wxPropertyGrid is a specialized grid for editing properties - in other
340 words name = value pairs. List of ready-to-use property classes include
341 strings, numbers, flag sets, fonts, colours and many others. It is possible,
342 for example, to categorize properties, set up a complete tree-hierarchy,
343 add more than two columns, and set arbitrary per-property attributes.
344
345 Please note that most member functions are inherited and as such not
346 documented on this page. This means you will probably also want to read
347 wxPropertyGridInterface class reference.
348
349 See also @ref overview_propgrid.
350
351 @section propgrid_window_styles_ Window Styles
352
353 See @ref propgrid_window_styles.
354
355 @section propgrid_event_handling Event Handling
356
357 To process input from a property grid control, use these event handler macros
358 to direct input to member functions that take a wxPropertyGridEvent argument.
359
360 @beginEventEmissionTable{wxPropertyGridEvent}
361 @event{EVT_PG_SELECTED (id, func)}
362 Respond to wxEVT_PG_SELECTED event, generated when a property selection
363 has been changed, either by user action or by indirect program
364 function. For instance, collapsing a parent property programmatically
365 causes any selected child property to become unselected, and may
366 therefore cause this event to be generated.
367 @event{EVT_PG_CHANGING(id, func)}
368 Respond to wxEVT_PG_CHANGING event, generated when property value
369 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
370 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
371 to prevent change from taking place, if necessary.
372 @event{EVT_PG_HIGHLIGHTED(id, func)}
373 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
374 moves over a property. Event's property is NULL if hovered area does
375 not belong to any property.
376 @event{EVT_PG_RIGHT_CLICK(id, func)}
377 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
378 clicked on with right mouse button.
379 @event{EVT_PG_DOUBLE_CLICK(id, func)}
380 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
381 double-clicked on with left mouse button.
382 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
383 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
384 a property or category.
385 @event{EVT_PG_ITEM_EXPANDED(id, func)}
386 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
387 a property or category.
388 @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
389 Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when is about to
390 begin editing a property label. You can veto this event to prevent the
391 action.
392 @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
393 Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to
394 end editing of a property label. You can veto this event to prevent the
395 action.
396 @event{EVT_PG_COL_BEGIN_DRAG(id, func)}
397 Respond to wxEVT_PG_COL_BEGIN_DRAG event, generated when user
398 starts resizing a column - can be vetoed.
399 @event{EVT_PG_COL_DRAGGING,(id, func)}
400 Respond to wxEVT_PG_COL_DRAGGING, event, generated when a
401 column resize by user is in progress. This event is also generated
402 when user double-clicks the splitter in order to recenter
403 it.
404 @event{EVT_PG_COL_END_DRAG(id, func)}
405 Respond to wxEVT_PG_COL_END_DRAG event, generated after column
406 resize by user has finished.
407 @endEventTable
408
409 @remarks
410 Use Freeze() and Thaw() respectively to disable and enable drawing.
411 This will also delay sorting etc. miscellaneous calculations to the last
412 possible moment.
413
414 @library{wxpropgrid}
415 @category{propgrid}
416 @appearance{propertygrid.png}
417 */
418 class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
419 {
420 public:
421 /**
422 Two step constructor.
423 Call Create() when this constructor is called to build up the wxPropertyGrid
424 */
425 wxPropertyGrid();
426
427 /**
428 Constructor.
429 The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
430
431 @see @ref propgrid_window_styles.
432 */
433 wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
434 const wxPoint& pos = wxDefaultPosition,
435 const wxSize& size = wxDefaultSize,
436 long style = wxPG_DEFAULT_STYLE,
437 const wxChar* name = wxPropertyGridNameStr );
438
439 /** Destructor */
440 virtual ~wxPropertyGrid();
441
442 /**
443 Adds given key combination to trigger given action.
444
445 @param action
446 Which action to trigger. See @ref propgrid_keyboard_actions.
447 @param keycode
448 Which keycode triggers the action.
449 @param modifiers
450 Which key event modifiers, in addition to keycode, are needed to
451 trigger the action.
452 */
453 void AddActionTrigger( int action, int keycode, int modifiers = 0 );
454
455 /**
456 Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
457 extra style is not used, then this has same effect as
458 calling SelectProperty().
459
460 @remarks Multiple selection is not supported for categories. This
461 means that if you have properties selected, you cannot
462 add category to selection, and also if you have category
463 selected, you cannot add other properties to selection.
464 This member function will fail silently in these cases,
465 even returning true.
466 */
467 bool AddToSelection( wxPGPropArg id );
468
469 /**
470 This static function enables or disables automatic use of
471 wxGetTranslation() for following strings: wxEnumProperty list labels,
472 wxFlagsProperty child property labels.
473
474 Default is false.
475 */
476 static void AutoGetTranslation( bool enable );
477
478 /**
479 Creates label editor wxTextCtrl for given column, for property
480 that is currently selected. When multiple selection is
481 enabled, this applies to whatever property GetSelection()
482 returns.
483
484 @param colIndex
485 Which column's label to edit. Note that you should not
486 use value 1, which is reserved for property value
487 column.
488
489 @see EndLabelEdit(), MakeColumnEditable()
490 */
491 void BeginLabelEdit( unsigned int column = 0 );
492
493 /**
494 Changes value of a property, as if from an editor. Use this instead of
495 SetPropertyValue() if you need the value to run through validation
496 process, and also send the property change event.
497
498 @return Returns true if value was successfully changed.
499 */
500 bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
501
502 /**
503 Centers the splitter. If argument is true, automatic splitter centering
504 is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
505 defined).
506 */
507 void CenterSplitter( bool enable_auto_centering = false );
508
509 /**
510 Deletes all properties.
511 */
512 virtual void Clear();
513
514 /**
515 Clears action triggers for given action.
516
517 @param action
518 Which action to trigger. @ref propgrid_keyboard_actions.
519 */
520 void ClearActionTriggers( int action );
521
522 /**
523 Forces updating the value of property from the editor control.
524 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
525 ProcessEvent, meaning your event handlers will be called immediately.
526
527 @return Returns @true if anything was changed.
528 */
529 virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
530
531 /**
532 Two step creation. Whenever the control is created without any
533 parameters, use Create to actually create it. Don't access the control's
534 public methods before this is called
535
536 @see @ref propgrid_window_styles.
537 */
538 bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
539 const wxPoint& pos = wxDefaultPosition,
540 const wxSize& size = wxDefaultSize,
541 long style = wxPG_DEFAULT_STYLE,
542 const wxChar* name = wxPropertyGridNameStr );
543
544 /**
545 Enables or disables (shows/hides) categories according to parameter
546 enable.
547
548 @remarks This functions deselects selected property, if any. Validation
549 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
550 selection is cleared even if editor had invalid value.
551 */
552 bool EnableCategories( bool enable );
553
554 /**
555 Destroys label editor wxTextCtrl, if any.
556
557 @param commit
558 Use @true (default) to store edited label text in
559 property cell data.
560
561 @see BeginLabelEdit(), MakeColumnEditable()
562 */
563 void EndLabelEdit( bool commit = true );
564
565 /**
566 Scrolls and/or expands items to ensure that the given item is visible.
567
568 @return Returns @true if something was actually done.
569 */
570 bool EnsureVisible( wxPGPropArg id );
571
572 /**
573 Reduces column sizes to minimum possible, while still retaining
574 fully visible grid contents (labels, images).
575
576 @return Minimum size for the grid to still display everything.
577
578 @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
579
580 This function only works properly if grid size prior to call was
581 already fairly large.
582
583 Note that you can also get calculated column widths by calling
584 GetState->GetColumnWidth() immediately after this function
585 returns.
586 */
587 wxSize FitColumns();
588
589 /**
590 Returns currently active label editor, NULL if none.
591 */
592 wxTextCtrl* GetLabelEditor() const;
593
594 /**
595 Returns wxWindow that the properties are painted on, and which should be
596 used as the parent for editor controls.
597 */
598 wxWindow* GetPanel();
599
600 /**
601 Returns current category caption background colour.
602 */
603 wxColour GetCaptionBackgroundColour() const;
604
605 /**
606 Returns current category caption font.
607 */
608 wxFont& GetCaptionFont();
609
610 /**
611 Returns current category caption text colour.
612 */
613 wxColour GetCaptionForegroundColour() const;
614
615 /**
616 Returns current cell background colour.
617 */
618 wxColour GetCellBackgroundColour() const;
619
620 /**
621 Returns current cell text colour when disabled.
622 */
623 wxColour GetCellDisabledTextColour() const;
624
625 /**
626 Returns current cell text colour.
627 */
628 wxColour GetCellTextColour() const;
629
630 /**
631 Returns number of columns currently on grid.
632 */
633 unsigned int GetColumnCount() const;
634
635 /**
636 Returns colour of empty space below properties.
637 */
638 wxColour GetEmptySpaceColour() const;
639
640 /**
641 Returns height of highest characters of used font.
642 */
643 int GetFontHeight() const;
644
645 /**
646 Returns pointer to itself. Dummy function that enables same kind
647 of code to use wxPropertyGrid and wxPropertyGridManager.
648 */
649 wxPropertyGrid* GetGrid();
650
651 /**
652 Returns rectangle of custom paint image.
653
654 @param property
655 Return image rectangle for this property.
656
657 @param item
658 Which choice of property to use (each choice may have
659 different image).
660 */
661 wxRect GetImageRect( wxPGProperty* property, int item ) const;
662
663 /**
664 Returns size of the custom paint image in front of property.
665
666 @param property
667 Return image rectangle for this property.
668 If this argument is NULL, then preferred size is returned.
669
670 @param item
671 Which choice of property to use (each choice may have
672 different image).
673 */
674 wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const;
675
676 /**
677 Returns last item which could be iterated using given flags.
678
679 @param flags
680 See @ref propgrid_iterator_flags.
681 */
682 wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT );
683
684 /**
685 Returns colour of lines between cells.
686 */
687 wxColour GetLineColour() const;
688
689 /**
690 Returns background colour of margin.
691 */
692 wxColour GetMarginColour() const;
693
694 /**
695 Returns "root property". It does not have name, etc. and it is not
696 visible. It is only useful for accessing its children.
697 */
698 wxPGProperty* GetRoot() const;
699
700 /**
701 Returns height of a single grid row (in pixels).
702 */
703 int GetRowHeight() const;
704
705 /**
706 Returns currently selected property.
707 */
708 wxPGProperty* GetSelectedProperty() const;
709
710 /**
711 Returns currently selected property.
712 */
713 wxPGProperty* GetSelection() const;
714
715 /**
716 Returns current selection background colour.
717 */
718 wxColour GetSelectionBackgroundColour() const;
719
720 /**
721 Returns current selection text colour.
722 */
723 wxColour GetSelectionForegroundColour() const;
724
725 /**
726 Returns the property sort function (default is @NULL).
727
728 @see SetSortFunction
729 */
730 wxPGSortCallback GetSortFunction() const;
731
732 /**
733 Returns current splitter x position.
734 */
735 int GetSplitterPosition() const;
736
737 /**
738 Returns wxTextCtrl active in currently selected property, if any. Takes
739 wxOwnerDrawnComboBox into account.
740 */
741 wxTextCtrl* GetEditorTextCtrl() const;
742
743 /**
744 Returns current appearance of unspecified value cells.
745
746 @see SetUnspecifiedValueAppearance()
747 */
748 const wxPGCell& GetUnspecifiedValueAppearance() const;
749
750 /**
751 Returns (visual) text representation of the unspecified
752 property value.
753
754 @param argFlags For internal use only.
755 */
756 wxString GetUnspecifiedValueText( int argFlags = 0 ) const;
757
758 /**
759 Returns current vertical spacing.
760 */
761 int GetVerticalSpacing() const;
762
763 /**
764 Returns information about arbitrary position in the grid.
765
766 @param pt
767 Coordinates in the virtual grid space. You may need to use
768 wxScrolledWindow::CalcScrolledPosition() for translating
769 wxPropertyGrid client coordinates into something this member
770 function can use.
771 */
772 wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
773
774 /**
775 Returns true if any property has been modified by the user.
776 */
777 bool IsAnyModified() const;
778
779 /**
780 Returns @true if a property editor control has focus.
781 */
782 bool IsEditorFocused() const;
783
784 /**
785 Returns true if updating is frozen (ie. Freeze() called but not
786 yet Thaw() ).
787 */
788 bool IsFrozen() const;
789
790 /**
791 Makes given column editable by user.
792
793 @param editable
794 Using @false here will disable column from being editable.
795
796 @see BeginLabelEdit(), EndLabelEdit()
797 */
798 void MakeColumnEditable( unsigned int column, bool editable = true );
799
800 /**
801 It is recommended that you call this function any time your code causes
802 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
803 handler should be able to detect most changes, but it is not perfect.
804
805 @param newTLP
806 New top-level parent that is about to be set. Old top-level parent
807 window should still exist as the current one.
808
809 @remarks This function is automatically called from wxPropertyGrid::
810 Reparent() and wxPropertyGridManager::Reparent(). You only
811 need to use it if you reparent wxPropertyGrid indirectly.
812 */
813 void OnTLPChanging( wxWindow* newTLP );
814
815 /**
816 Refreshes any active editor control.
817 */
818 void RefreshEditor();
819
820 /**
821 Redraws given property.
822 */
823 virtual void RefreshProperty( wxPGProperty* p );
824
825 /**
826 Registers a new editor class.
827
828 @return Returns pointer to the editor class instance that should be used.
829 */
830 static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
831 const wxString& name,
832 bool noDefCheck = false );
833
834 /**
835 Resets all colours to the original system values.
836 */
837 void ResetColours();
838
839 /**
840 Removes given property from selection. If property is not selected,
841 an assertion failure will occur.
842 */
843 bool RemoveFromSelection( wxPGPropArg id );
844
845 /**
846 Selects a property. Editor widget is automatically created, but
847 not focused unless focus is true.
848
849 @param id
850 Property to select (name or pointer).
851
852 @param focus
853 If @true, move keyboard focus to the created editor right away.
854
855 @return returns @true if selection finished successfully. Usually only
856 fails if current value in editor is not valid.
857
858 @remarks In wxPropertyGrid 1.4, this member function used to generate
859 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
860 does that.
861
862 @remarks This clears any previous selection.
863
864 @see wxPropertyGridInterface::ClearSelection()
865 */
866 bool SelectProperty( wxPGPropArg id, bool focus = false );
867
868 /**
869 Changes keyboard shortcut to push the editor button.
870
871 @remarks You can set default with keycode 0. Good value for the platform
872 is guessed, but don't expect it to be very accurate.
873 */
874 void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
875
876 /**
877 Sets category caption background colour.
878 */
879 void SetCaptionBackgroundColour(const wxColour& col);
880
881 /**
882 Sets category caption text colour.
883 */
884 void SetCaptionTextColour(const wxColour& col);
885
886 /**
887 Sets default cell background colour - applies to property cells.
888 Note that appearance of editor widgets may not be affected.
889 */
890 void SetCellBackgroundColour(const wxColour& col);
891
892 /**
893 Sets cell text colour for disabled properties.
894 */
895 void SetCellDisabledTextColour(const wxColour& col);
896
897 /**
898 Sets default cell text colour - applies to property name and value text.
899 Note that appearance of editor widgets may not be affected.
900 */
901 void SetCellTextColour(const wxColour& col);
902
903 /**
904 Set number of columns (2 or more).
905 */
906 void SetColumnCount( int colCount );
907
908 /**
909 Sets the 'current' category - Append will add non-category properties
910 under it.
911 */
912 void SetCurrentCategory( wxPGPropArg id );
913
914 /**
915 Sets colour of empty space below properties.
916 */
917 void SetEmptySpaceColour(const wxColour& col);
918
919 /**
920 Sets colour of lines between cells.
921 */
922 void SetLineColour(const wxColour& col);
923
924 /**
925 Sets background colour of margin.
926 */
927 void SetMarginColour(const wxColour& col);
928
929 /**
930 Set entire new selection from given list of properties.
931 */
932 void SetSelection( const wxArrayPGProperty& newSelection );
933
934 /**
935 Sets selection background colour - applies to selected property name
936 background.
937 */
938 void SetSelectionBackgroundColour(const wxColour& col);
939
940 /**
941 Sets selection foreground colour - applies to selected property name text.
942 */
943 void SetSelectionTextColour(const wxColour& col);
944
945
946 /**
947 Sets the property sorting function.
948
949 @param sortFunction
950 The sorting function to be used. It should return a value greater
951 than 0 if position of p1 is after p2. So, for instance, when
952 comparing property names, you can use following implementation:
953
954 @code
955 int MyPropertySortFunction(wxPropertyGrid* propGrid,
956 wxPGProperty* p1,
957 wxPGProperty* p2)
958 {
959 return p1->GetBaseName().compare( p2->GetBaseName() );
960 }
961 @endcode
962
963 @remarks
964 Default property sort function sorts properties by their labels
965 (case-insensitively).
966
967 @see GetSortFunction, wxPropertyGridInterface::Sort,
968 wxPropertyGridInterface::SortChildren
969 */
970 void SetSortFunction( wxPGSortCallback sortFunction );
971
972 /**
973 Sets x coordinate of the splitter.
974
975 @remarks Splitter position cannot exceed grid size, and therefore setting
976 it during form creation may fail as initial grid size is often
977 smaller than desired splitter position, especially when sizers
978 are being used.
979 */
980 void SetSplitterPosition( int newxpos, int col = 0 );
981
982 /**
983 Moves splitter as left as possible, while still allowing all
984 labels to be shown in full.
985
986 @param privateChildrenToo
987 If @false, will still allow private children to be cropped.
988 */
989 void SetSplitterLeft( bool privateChildrenToo = false );
990
991 /**
992 Sets appearance of value cells representing an unspecified property
993 value. Default appearance is blank.
994
995 @remarks If you set the unspecified value to have any
996 textual representation, then that will override
997 "InlineHelp" attribute.
998
999 @see wxPGProperty::SetValueToUnspecified(),
1000 wxPGProperty::IsValueUnspecified()
1001 */
1002 void SetUnspecifiedValueAppearance( const wxPGCell& cell );
1003
1004 /**
1005 Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1006 height. Value of 2 should be default on most platforms.
1007 */
1008 void SetVerticalSpacing( int vspacing );
1009
1010
1011 /**
1012 @name Property development functions
1013
1014 These member functions are usually only called when creating custom
1015 user properties.
1016 */
1017 //@{
1018
1019 /**
1020 Call when editor widget's contents is modified. For example, this is
1021 called when changes text in wxTextCtrl (used in wxStringProperty and
1022 wxIntProperty).
1023
1024 @remarks This function should only be called by custom properties.
1025
1026 @see wxPGProperty::OnEvent()
1027 */
1028 void EditorsValueWasModified();
1029
1030 /**
1031 Reverse of EditorsValueWasModified().
1032
1033 @remarks This function should only be called by custom properties.
1034 */
1035 void EditorsValueWasNotModified();
1036
1037 /**
1038 Returns most up-to-date value of selected property. This will return
1039 value different from GetSelectedProperty()->GetValue() only when text
1040 editor is activate and string edited by user represents valid,
1041 uncommitted property value.
1042 */
1043 wxVariant GetUncommittedPropertyValue();
1044
1045 /**
1046 Returns true if editor's value was marked modified.
1047 */
1048 bool IsEditorsValueModified() const;
1049
1050 /**
1051 Shows an brief error message that is related to a property.
1052 */
1053 void ShowPropertyError( wxPGPropArg id, const wxString& msg );
1054
1055 /**
1056 You can use this member function, for instance, to detect in
1057 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1058 already called in wxPGEditor::OnEvent(). It really only detects
1059 if was value was changed using wxPGProperty::SetValueInEvent(), which
1060 is usually used when a 'picker' dialog is displayed. If value was
1061 written by "normal means" in wxPGProperty::StringToValue() or
1062 IntToValue(), then this function will return false (on the other hand,
1063 wxPGProperty::OnEvent() is not even called in those cases).
1064 */
1065 bool WasValueChangedInEvent() const;
1066
1067 //@}
1068 };
1069
1070
1071 /**
1072 @class wxPropertyGridEvent
1073
1074 A property grid event holds information about events associated with
1075 wxPropertyGrid objects.
1076
1077 @library{wxpropgrid}
1078 @category{propgrid}
1079 */
1080 class wxPropertyGridEvent : public wxCommandEvent
1081 {
1082 public:
1083
1084 /** Constructor. */
1085 wxPropertyGridEvent(wxEventType commandType=0, int id=0);
1086
1087 /** Copy constructor. */
1088 wxPropertyGridEvent(const wxPropertyGridEvent& event);
1089
1090 /** Destructor. */
1091 ~wxPropertyGridEvent();
1092
1093 /**
1094 Returns true if you can veto the action that the event is signaling.
1095 */
1096 bool CanVeto() const;
1097
1098 /**
1099 Returns the column index associated with this event.
1100 For the column dragging events, it is the column to the left
1101 of the splitter being dragged
1102 */
1103 unsigned int GetColumn() const;
1104
1105 /**
1106 Returns highest level non-category, non-root parent of property for
1107 which event occurred. Useful when you have nested properties with
1108 children.
1109
1110 @remarks If immediate parent is root or category, this will return the
1111 property itself.
1112 */
1113 wxPGProperty* GetMainParent() const;
1114
1115 /**
1116 Returns property associated with this event.
1117 */
1118 wxPGProperty* GetProperty() const;
1119
1120 /**
1121 Returns current validation failure flags.
1122 */
1123 wxPGVFBFlags GetValidationFailureBehavior() const;
1124
1125 /**
1126 Returns name of the associated property.
1127
1128 @remarks Property name is stored in event, so it remains
1129 accessible even after the associated property or
1130 the property grid has been deleted.
1131 */
1132 wxString GetPropertyName() const;
1133
1134 /**
1135 Returns value of the associated property. Works for all event
1136 types, but for wxEVT_PG_CHANGING this member function returns
1137 the value that is pending, so you can call Veto() if the
1138 value is not satisfactory.
1139
1140 @remarks Property value is stored in event, so it remains
1141 accessible even after the associated property or
1142 the property grid has been deleted.
1143 */
1144 wxVariant GetPropertyValue() const
1145
1146 /**
1147 @see GetPropertyValue()
1148 */
1149 wxVariant GetValue() const;
1150
1151 /**
1152 Set if event can be vetoed.
1153 */
1154 void SetCanVeto( bool canVeto );
1155
1156 /** Changes the property associated with this event. */
1157 void SetProperty( wxPGProperty* p );
1158
1159 /**
1160 Set override validation failure behavior. Only effective if Veto() was
1161 also called, and only allowed if event type is wxEVT_PG_CHANGING.
1162 */
1163 void SetValidationFailureBehavior( wxPGVFBFlags flags );
1164
1165 /**
1166 Sets custom failure message for this time only. Only applies if
1167 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
1168 */
1169 void SetValidationFailureMessage( const wxString& message );
1170
1171 /**
1172 Call this from your event handler to veto action that the event is
1173 signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
1174 returns true.
1175
1176 @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
1177 */
1178 void Veto( bool veto = true );
1179
1180 /**
1181 Returns @true if event was vetoed.
1182 */
1183 bool WasVetoed() const;
1184 };