1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/propgrid/property.h
3 // Purpose: wxPGProperty and related support classes
4 // Author: Jaakko Salli
8 // Copyright: (c) Jaakko Salli
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_PROPGRID_PROPERTY_H_
13 #define _WX_PROPGRID_PROPERTY_H_
17 #include "wx/propgrid/propgriddefs.h"
19 // -----------------------------------------------------------------------
21 #define wxNullProperty ((wxPGProperty*)NULL)
24 /** @class wxPGPaintData
26 Contains information relayed to property's OnCustomPaint.
30 /** wxPropertyGrid. */
31 const wxPropertyGrid
* m_parent
;
34 Normally -1, otherwise index to drop-down list item that has to be
39 /** Set to drawn width in OnCustomPaint (optional). */
43 In a measure item call, set this to the height of item at m_choiceItem
53 // space between vertical sides of a custom image
54 #define wxPG_CUSTOM_IMAGE_SPACINGY 1
56 // space between caption and selection rectangle,
57 #define wxPG_CAPRECTXMARGIN 2
59 // horizontally and vertically
60 #define wxPG_CAPRECTYMARGIN 1
63 /** @class wxPGCellRenderer
65 Base class for wxPropertyGrid cell renderers.
67 class WXDLLIMPEXP_PROPGRID wxPGCellRenderer
: public wxObjectRefData
72 : wxObjectRefData() { }
73 virtual ~wxPGCellRenderer() { }
78 // We are painting selected item
79 Selected
= 0x00010000,
81 // We are painting item in choice popup
82 ChoicePopup
= 0x00020000,
84 // We are rendering wxOwnerDrawnComboBox control
85 // (or other owner drawn control, but that is only
86 // officially supported one ATM).
89 // We are painting a disable property
90 Disabled
= 0x00080000,
92 // We are painting selected, disabled, or similar
93 // item that dictates fore- and background colours,
94 // overriding any cell values.
95 DontUseCellFgCol
= 0x00100000,
96 DontUseCellBgCol
= 0x00200000,
97 DontUseCellColours
= DontUseCellFgCol
|
101 virtual void Render( wxDC
& dc
,
103 const wxPropertyGrid
* propertyGrid
,
104 wxPGProperty
* property
,
107 int flags
) const = 0;
109 /** Returns size of the image in front of the editable area.
111 If property is NULL, then this call is for a custom value. In that case
112 the item is index to wxPropertyGrid's custom values.
114 virtual wxSize
GetImageSize( const wxPGProperty
* property
,
118 /** Paints property category selection rectangle.
120 virtual void DrawCaptionSelectionRect( wxDC
& dc
,
122 int w
, int h
) const;
124 /** Utility to draw vertically centered text.
126 void DrawText( wxDC
& dc
,
129 const wxString
& text
) const;
132 Utility to draw editor's value, or vertically aligned text if editor is
135 void DrawEditorValue( wxDC
& dc
, const wxRect
& rect
,
136 int xOffset
, const wxString
& text
,
137 wxPGProperty
* property
,
138 const wxPGEditor
* editor
) const;
140 /** Utility to render cell bitmap and set text colour plus bg brush colour.
142 Returns image width that, for instance, can be passed to DrawText.
144 int PreDrawCell( wxDC
& dc
,
146 const wxPGCell
& cell
,
151 class WXDLLIMPEXP_PROPGRID wxPGCellData
: public wxObjectRefData
153 friend class wxPGCell
;
157 void SetText( const wxString
& text
)
160 m_hasValidText
= true;
162 void SetBitmap( const wxBitmap
& bitmap
) { m_bitmap
= bitmap
; }
163 void SetFgCol( const wxColour
& col
) { m_fgCol
= col
; }
164 void SetBgCol( const wxColour
& col
) { m_bgCol
= col
; }
167 virtual ~wxPGCellData() { }
174 // True if m_text is valid and specified
180 Base class for simple wxPropertyGrid cell information.
182 class WXDLLIMPEXP_PROPGRID wxPGCell
: public wxObject
186 wxPGCell(const wxPGCell
& other
)
191 wxPGCell( const wxString
& text
,
192 const wxBitmap
& bitmap
= wxNullBitmap
,
193 const wxColour
& fgCol
= wxNullColour
,
194 const wxColour
& bgCol
= wxNullColour
);
196 virtual ~wxPGCell() { }
198 wxPGCellData
* GetData()
200 return (wxPGCellData
*) m_refData
;
203 const wxPGCellData
* GetData() const
205 return (const wxPGCellData
*) m_refData
;
210 return (m_refData
&& GetData()->m_hasValidText
);
214 Merges valid data from srcCell into this.
216 void MergeFrom( const wxPGCell
& srcCell
);
218 void SetText( const wxString
& text
);
219 void SetBitmap( const wxBitmap
& bitmap
);
220 void SetFgCol( const wxColour
& col
);
221 void SetBgCol( const wxColour
& col
);
223 const wxString
& GetText() const { return GetData()->m_text
; }
224 const wxBitmap
& GetBitmap() const { return GetData()->m_bitmap
; }
225 const wxColour
& GetFgCol() const { return GetData()->m_fgCol
; }
226 const wxColour
& GetBgCol() const { return GetData()->m_bgCol
; }
228 wxPGCell
& operator=( const wxPGCell
& other
)
230 if ( this != &other
)
238 virtual wxObjectRefData
*CreateRefData() const
239 { return new wxPGCellData(); }
241 virtual wxObjectRefData
*CloneRefData(const wxObjectRefData
*data
) const;
245 /** @class wxPGDefaultRenderer
247 Default cell renderer, that can handles the common
250 class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer
: public wxPGCellRenderer
253 virtual void Render( wxDC
& dc
,
255 const wxPropertyGrid
* propertyGrid
,
256 wxPGProperty
* property
,
261 virtual wxSize
GetImageSize( const wxPGProperty
* property
,
268 // -----------------------------------------------------------------------
270 /** @class wxPGAttributeStorage
272 wxPGAttributeStorage is somewhat optimized storage for
273 key=variant pairs (ie. a map).
275 class WXDLLIMPEXP_PROPGRID wxPGAttributeStorage
278 wxPGAttributeStorage();
279 ~wxPGAttributeStorage();
281 void Set( const wxString
& name
, const wxVariant
& value
);
282 unsigned int GetCount() const { return (unsigned int) m_map
.size(); }
283 wxVariant
FindValue( const wxString
& name
) const
285 wxPGHashMapS2P::const_iterator it
= m_map
.find(name
);
286 if ( it
!= m_map
.end() )
288 wxVariantData
* data
= (wxVariantData
*) it
->second
;
290 return wxVariant(data
, it
->first
);
295 typedef wxPGHashMapS2P::const_iterator const_iterator
;
296 const_iterator
StartIteration() const
298 return m_map
.begin();
300 bool GetNext( const_iterator
& it
, wxVariant
& variant
) const
302 if ( it
== m_map
.end() )
305 wxVariantData
* data
= (wxVariantData
*) it
->second
;
307 variant
.SetData(data
);
308 variant
.SetName(it
->first
);
314 wxPGHashMapS2P m_map
;
319 // -----------------------------------------------------------------------
321 /** @section propgrid_propflags wxPGProperty Flags
325 enum wxPG_PROPERTY_FLAGS
328 /** Indicates bold font.
330 wxPG_PROP_MODIFIED
= 0x0001,
332 /** Disables ('greyed' text and editor does not activate) property.
334 wxPG_PROP_DISABLED
= 0x0002,
336 /** Hider button will hide this property.
338 wxPG_PROP_HIDDEN
= 0x0004,
340 /** This property has custom paint image just in front of its value.
341 If property only draws custom images into a popup list, then this
342 flag should not be set.
344 wxPG_PROP_CUSTOMIMAGE
= 0x0008,
346 /** Do not create text based editor for this property (but button-triggered
347 dialog and choice are ok).
349 wxPG_PROP_NOEDITOR
= 0x0010,
351 /** Property is collapsed, ie. it's children are hidden.
353 wxPG_PROP_COLLAPSED
= 0x0020,
356 If property is selected, then indicates that validation failed for pending
359 If property is not selected, then indicates that the the actual property
360 value has failed validation (NB: this behavior is not currently supported,
361 but may be used in future).
363 wxPG_PROP_INVALID_VALUE
= 0x0040,
367 /** Switched via SetWasModified(). Temporary flag - only used when
368 setting/changing property value.
370 wxPG_PROP_WAS_MODIFIED
= 0x0200,
373 If set, then child properties (if any) are private, and should be
374 "invisible" to the application.
376 wxPG_PROP_AGGREGATE
= 0x0400,
378 /** If set, then child properties (if any) are copies and should not
381 wxPG_PROP_CHILDREN_ARE_COPIES
= 0x0800,
384 Classifies this item as a non-category.
386 Used for faster item type identification.
388 wxPG_PROP_PROPERTY
= 0x1000,
391 Classifies this item as a category.
393 Used for faster item type identification.
395 wxPG_PROP_CATEGORY
= 0x2000,
397 /** Classifies this item as a property that has children, but is not aggregate
398 (ie children are not private).
400 wxPG_PROP_MISC_PARENT
= 0x4000,
402 /** Property is read-only. Editor is still created.
404 wxPG_PROP_READONLY
= 0x8000,
407 // NB: FLAGS ABOVE 0x8000 CANNOT BE USED WITH PROPERTY ITERATORS
410 /** Property's value is composed from values of child properties.
412 This flag cannot be used with property iterators.
414 wxPG_PROP_COMPOSED_VALUE
= 0x00010000,
416 /** Common value of property is selectable in editor.
418 This flag cannot be used with property iterators.
420 wxPG_PROP_USES_COMMON_VALUE
= 0x00020000,
422 /** Property can be set to unspecified value via editor.
423 Currently, this applies to following properties:
424 - wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty:
428 This flag cannot be used with property iterators.
430 wxPG_PROP_AUTO_UNSPECIFIED
= 0x00040000,
432 /** Indicates the bit useable by derived properties.
434 wxPG_PROP_CLASS_SPECIFIC_1
= 0x00080000,
436 /** Indicates the bit useable by derived properties.
438 wxPG_PROP_CLASS_SPECIFIC_2
= 0x00100000,
440 /** Indicates that the property is being deleted and should be ignored.
442 wxPG_PROP_BEING_DELETED
= 0x00200000
448 #define wxPG_PROP_MAX wxPG_PROP_AUTO_UNSPECIFIED
450 /** Property with children must have one of these set, otherwise iterators
451 will not work correctly.
452 Code should automatically take care of this, however.
454 #define wxPG_PROP_PARENTAL_FLAGS \
455 (wxPG_PROP_AGGREGATE|wxPG_PROP_CATEGORY|wxPG_PROP_MISC_PARENT)
460 // Combination of flags that can be stored by GetFlagsAsString
461 #define wxPG_STRING_STORED_FLAGS \
462 (wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED)
464 // -----------------------------------------------------------------------
469 @section propgrid_property_attributes wxPropertyGrid Property Attribute
472 wxPGProperty::SetAttribute() and
473 wxPropertyGridInterface::SetPropertyAttribute() accept one of these as
474 attribute name argument.
476 You can use strings instead of constants. However, some of these
477 constants are redefined to use cached strings which may reduce
478 your binary size by some amount.
483 /** Set default value for property.
485 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
487 /** Universal, int or double. Minimum value for numeric properties.
489 #define wxPG_ATTR_MIN wxS("Min")
491 /** Universal, int or double. Maximum value for numeric properties.
493 #define wxPG_ATTR_MAX wxS("Max")
495 /** Universal, string. When set, will be shown as text after the displayed
496 text value. Alternatively, if third column is enabled, text will be shown
497 there (for any type of property).
499 #define wxPG_ATTR_UNITS wxS("Units")
501 /** Universal, string. When set, will be shown in property's value cell
502 when displayed value string is empty, or value is unspecified.
504 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
506 /** Universal, wxArrayString. Set to enable auto-completion in any
507 wxTextCtrl-based property editor.
509 #define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
511 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
512 Default value is False.
514 When set to True, bool property will use check box instead of a
515 combo box as its editor control. If you set this attribute
516 for a wxFlagsProperty, it is automatically applied to child
519 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
521 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
522 Default value is False.
524 Set to True for the bool property to cycle value on double click
525 (instead of showing the popup listbox). If you set this attribute
526 for a wxFlagsProperty, it is automatically applied to child
529 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
532 wxFloatProperty (and similar) specific, int, default -1.
534 Sets the (max) precision used when floating point value is rendered as
535 text. The default -1 means infinite precision.
537 #define wxPG_FLOAT_PRECISION wxS("Precision")
540 The text will be echoed as asterisks (wxTE_PASSWORD will be passed to
543 #define wxPG_STRING_PASSWORD wxS("Password")
545 /** Define base used by a wxUIntProperty. Valid constants are
546 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
547 (lowercase characters).
549 #define wxPG_UINT_BASE wxS("Base")
551 /** Define prefix rendered to wxUIntProperty. Accepted constants
552 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
553 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
556 #define wxPG_UINT_PREFIX wxS("Prefix")
559 wxFileProperty/wxImageFileProperty specific, wxChar*, default is
561 Sets the wildcard used in the triggered wxFileDialog. Format is the same.
563 #define wxPG_FILE_WILDCARD wxS("Wildcard")
565 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
566 When 0, only the file name is shown (i.e. drive and directory are hidden).
568 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
570 /** Specific to wxFileProperty and derived properties, wxString, default empty.
571 If set, then the filename is shown relative to the given path string.
573 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
576 Specific to wxFileProperty and derived properties, wxString, default is
579 Sets the initial path of where to look for files.
581 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
583 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
584 Sets a specific title for the dir dialog.
586 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
588 /** Specific to wxDirProperty, wxString, default is empty.
589 Sets a specific message for the dir dialog.
591 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
593 /** Sets displayed date format for wxDateProperty.
595 #define wxPG_DATE_FORMAT wxS("DateFormat")
597 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
598 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
600 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
602 /** SpinCtrl editor, int or double. How much number changes when button is
603 pressed (or up/down on keybard).
605 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
607 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
609 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
612 wxMultiChoiceProperty, int.
613 If 0, no user strings allowed. If 1, user strings appear before list
614 strings. If 2, user strings appear after list string.
616 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
619 wxColourProperty and its kind, int, default 1.
621 Setting this attribute to 0 hides custom colour from property's list of
624 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
629 // Redefine attribute macros to use cached strings
630 #undef wxPG_ATTR_DEFAULT_VALUE
631 #define wxPG_ATTR_DEFAULT_VALUE wxPGGlobalVars->m_strDefaultValue
633 #define wxPG_ATTR_MIN wxPGGlobalVars->m_strMin
635 #define wxPG_ATTR_MAX wxPGGlobalVars->m_strMax
636 #undef wxPG_ATTR_UNITS
637 #define wxPG_ATTR_UNITS wxPGGlobalVars->m_strUnits
638 #undef wxPG_ATTR_INLINE_HELP
639 #define wxPG_ATTR_INLINE_HELP wxPGGlobalVars->m_strInlineHelp
643 // -----------------------------------------------------------------------
647 /** @class wxPGChoiceEntry
648 Data of a single wxPGChoices choice.
650 class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry
: public wxPGCell
654 wxPGChoiceEntry(const wxPGChoiceEntry
& other
)
657 m_value
= other
.m_value
;
659 wxPGChoiceEntry( const wxString
& label
,
660 int value
= wxPG_INVALID_VALUE
)
661 : wxPGCell(), m_value(value
)
666 virtual ~wxPGChoiceEntry() { }
668 void SetValue( int value
) { m_value
= value
; }
669 int GetValue() const { return m_value
; }
671 wxPGChoiceEntry
& operator=( const wxPGChoiceEntry
& other
)
673 if ( this != &other
)
677 m_value
= other
.m_value
;
686 typedef void* wxPGChoicesId
;
688 class WXDLLIMPEXP_PROPGRID wxPGChoicesData
: public wxObjectRefData
690 friend class wxPGChoices
;
692 // Constructor sets m_refCount to 1.
695 void CopyDataFrom( wxPGChoicesData
* data
);
697 wxPGChoiceEntry
& Insert( int index
, const wxPGChoiceEntry
& item
);
699 // Delete all entries
702 unsigned int GetCount() const
704 return (unsigned int) m_items
.size();
707 const wxPGChoiceEntry
& Item( unsigned int i
) const
709 wxASSERT_MSG( i
< GetCount(), "invalid index" );
713 wxPGChoiceEntry
& Item( unsigned int i
)
715 wxASSERT_MSG( i
< GetCount(), "invalid index" );
720 wxVector
<wxPGChoiceEntry
> m_items
;
722 virtual ~wxPGChoicesData();
725 #define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL)
729 /** @class wxPGChoices
731 Helper class for managing choices of wxPropertyGrid properties.
732 Each entry can have label, value, bitmap, text colour, and background
735 wxPGChoices uses reference counting, similar to other wxWidgets classes.
736 This means that assignment operator and copy constructor only copy the
737 reference and not the actual data. Use Copy() member function to create a
740 @remarks If you do not specify value for entry, index is used.
745 class WXDLLIMPEXP_PROPGRID wxPGChoices
748 typedef long ValArrItem
;
750 /** Default constructor. */
757 Copy constructor, uses reference counting. To create a real copy,
758 use Copy() member function instead.
760 wxPGChoices( const wxPGChoices
& a
)
762 if ( a
.m_data
!= wxPGChoicesEmptyData
)
776 Values for choices. If NULL, indexes are used.
778 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
)
791 Values for choices. If empty, indexes are used.
793 wxPGChoices( const wxArrayString
& labels
,
794 const wxArrayInt
& values
= wxArrayInt() )
800 /** Simple interface constructor. */
801 wxPGChoices( wxPGChoicesData
* data
)
817 If did not have own copies, creates them now. If was empty, identical
818 to set except that creates copies.
821 Labels for added choices.
824 Values for added choices. If empty, relevant entry indexes are used.
826 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
828 /** Version that works with wxArrayString and wxArrayInt. */
829 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
= wxArrayInt() );
832 Adds a single choice.
835 Label for added choice.
838 Value for added choice. If unspecified, index is used.
840 wxPGChoiceEntry
& Add( const wxString
& label
,
841 int value
= wxPG_INVALID_VALUE
);
843 /** Adds a single item, with bitmap. */
844 wxPGChoiceEntry
& Add( const wxString
& label
,
845 const wxBitmap
& bitmap
,
846 int value
= wxPG_INVALID_VALUE
);
848 /** Adds a single item with full entry information. */
849 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
851 return Insert(entry
, -1);
854 /** Adds single item. */
855 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
,
856 int value
= wxPG_INVALID_VALUE
);
859 Assigns choices data, using reference counting. To create a real copy,
860 use Copy() member function instead.
862 void Assign( const wxPGChoices
& a
)
864 AssignData(a
.m_data
);
867 void AssignData( wxPGChoicesData
* data
);
869 /** Delete all choices. */
873 Returns a real copy of the choices.
875 wxPGChoices
Copy() const
879 dst
.m_data
->CopyDataFrom(m_data
);
885 if ( m_data
== wxPGChoicesEmptyData
)
886 m_data
= new wxPGChoicesData();
889 /** Gets a unsigned number identifying this list. */
890 wxPGChoicesId
GetId() const { return (wxPGChoicesId
) m_data
; };
892 const wxString
& GetLabel( unsigned int ind
) const
894 return Item(ind
).GetText();
897 unsigned int GetCount () const
902 return m_data
->GetCount();
905 int GetValue( unsigned int ind
) const { return Item(ind
).GetValue(); }
907 /** Returns array of values matching the given strings. Unmatching strings
908 result in wxPG_INVALID_VALUE entry in array.
910 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
912 /** Returns array of indices matching given strings. Unmatching strings
913 are added to 'unmatched', if not NULL.
915 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
916 wxArrayString
* unmatched
= NULL
) const;
918 int Index( const wxString
& str
) const;
919 int Index( int val
) const;
921 /** Inserts single item. */
922 wxPGChoiceEntry
& Insert( const wxString
& label
,
924 int value
= wxPG_INVALID_VALUE
);
926 /** Inserts a single item with full entry information. */
927 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
929 /** Returns false if this is a constant empty set of choices,
930 which should not be modified.
934 return ( m_data
!= wxPGChoicesEmptyData
);
937 const wxPGChoiceEntry
& Item( unsigned int i
) const
940 return m_data
->Item(i
);
943 wxPGChoiceEntry
& Item( unsigned int i
)
946 return m_data
->Item(i
);
949 /** Removes count items starting at position nIndex. */
950 void RemoveAt(size_t nIndex
, size_t count
= 1);
953 /** Does not create copies for itself. */
954 void Set( const wxChar
** labels
, const long* values
= NULL
)
961 /** Version that works with wxArrayString and wxArrayInt. */
962 void Set( const wxArrayString
& labels
,
963 const wxArrayInt
& values
= wxArrayInt() )
972 // Creates exclusive copy of current choices
973 void AllocExclusive();
975 // Returns data, increases refcount.
976 wxPGChoicesData
* GetData()
978 wxASSERT( m_data
->GetRefCount() != -1 );
983 // Returns plain data ptr - no refcounting stuff is done.
984 wxPGChoicesData
* GetDataPtr() const { return m_data
; }
986 // Changes ownership of data to you.
987 wxPGChoicesData
* ExtractData()
989 wxPGChoicesData
* data
= m_data
;
990 m_data
= wxPGChoicesEmptyData
;
994 wxArrayString
GetLabels() const;
997 void operator= (const wxPGChoices
& a
)
1000 AssignData(a
.m_data
);
1003 wxPGChoiceEntry
& operator[](unsigned int i
)
1008 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1014 wxPGChoicesData
* m_data
;
1021 // -----------------------------------------------------------------------
1023 /** @class wxPGProperty
1025 wxPGProperty is base class for all wxPropertyGrid properties.
1027 NB: Full class overview is now only present in
1028 interface/wx/propgrid/property.h.
1030 @library{wxpropgrid}
1033 class WXDLLIMPEXP_PROPGRID wxPGProperty
: public wxObject
1035 friend class wxPropertyGrid
;
1036 friend class wxPropertyGridInterface
;
1037 friend class wxPropertyGridPageState
;
1038 friend class wxPropertyGridPopulator
;
1039 friend class wxStringProperty
; // Proper "<composed>" support requires this
1041 DECLARE_ABSTRACT_CLASS(wxPGProperty
)
1043 typedef wxUint32 FlagType
;
1046 Default constructor.
1053 All non-abstract property classes should have a constructor with
1054 the same first two arguments as this one.
1056 wxPGProperty( const wxString
& label
, const wxString
& name
);
1060 It is customary for derived properties to implement this.
1062 virtual ~wxPGProperty();
1064 /** This virtual function is called after m_value has been set.
1067 - If m_value was set to Null variant (ie. unspecified value),
1068 OnSetValue() will not be called.
1069 - m_value may be of any variant type. Typically properties internally
1070 support only one variant type, and as such OnSetValue() provides a
1071 good opportunity to convert
1072 supported values into internal type.
1073 - Default implementation does nothing.
1075 virtual void OnSetValue();
1077 /** Override this to return something else than m_value as the value.
1079 virtual wxVariant
DoGetValue() const { return m_value
; }
1081 #if !defined(SWIG) || defined(CREATE_VCW)
1082 /** Implement this function in derived class to check the value.
1083 Return true if it is ok. Returning false prevents property change events
1087 - Default implementation always returns true.
1089 virtual bool ValidateValue( wxVariant
& value
,
1090 wxPGValidationInfo
& validationInfo
) const;
1093 Converts text into wxVariant value appropriate for this property.
1096 On function entry this is the old value (should not be wxNullVariant
1097 in normal cases). Translated value must be assigned back to it.
1100 Text to be translated into variant.
1103 If wxPG_FULL_VALUE is set, returns complete, storable value instead
1104 of displayable one (they may be different).
1105 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
1106 composite property string value (as generated by ValueToString()
1107 called with this same flag).
1109 @return Returns @true if resulting wxVariant value was different.
1111 @remarks Default implementation converts semicolon delimited tokens into
1112 child values. Only works for properties with children.
1114 You might want to take into account that m_value is Null variant
1115 if property value is unspecified (which is usually only case if
1116 you explicitly enabled that sort behavior).
1118 virtual bool StringToValue( wxVariant
& variant
,
1119 const wxString
& text
,
1120 int argFlags
= 0 ) const;
1123 Converts integer (possibly a choice selection) into wxVariant value
1124 appropriate for this property.
1127 On function entry this is the old value (should not be wxNullVariant
1128 in normal cases). Translated value must be assigned back to it.
1131 Integer to be translated into variant.
1134 If wxPG_FULL_VALUE is set, returns complete, storable value instead
1137 @return Returns @true if resulting wxVariant value was different.
1140 - If property is not supposed to use choice or spinctrl or other editor
1141 with int-based value, it is not necessary to implement this method.
1142 - Default implementation simply assign given int to m_value.
1143 - If property uses choice control, and displays a dialog on some choice
1144 items, then it is preferred to display that dialog in IntToValue
1146 - You might want to take into account that m_value is Null variant if
1147 property value is unspecified (which is usually only case if you
1148 explicitly enabled that sort behavior).
1150 virtual bool IntToValue( wxVariant
& value
,
1152 int argFlags
= 0 ) const;
1153 #endif // !defined(SWIG) || defined(CREATE_VCW)
1155 Converts property value into a text representation.
1158 Value to be converted.
1161 If 0 (default value), then displayed string is returned.
1162 If wxPG_FULL_VALUE is set, returns complete, storable string value
1163 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1164 string value that must be editable in textctrl. If
1165 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1166 display as a part of string property's composite text
1169 @remarks Default implementation calls GenerateComposedValue().
1171 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
= 0 ) const;
1173 /** Converts string to a value, and if successful, calls SetValue() on it.
1174 Default behavior is to do nothing.
1176 String to get the value from.
1178 true if value was changed.
1180 bool SetValueFromString( const wxString
& text
, int flags
= wxPG_PROGRAMMATIC_VALUE
);
1182 /** Converts integer to a value, and if succesful, calls SetValue() on it.
1183 Default behavior is to do nothing.
1185 Int to get the value from.
1187 If has wxPG_FULL_VALUE, then the value given is a actual value and
1190 True if value was changed.
1192 bool SetValueFromInt( long value
, int flags
= 0 );
1195 Returns size of the custom painted image in front of property.
1197 This method must be overridden to return non-default value if
1198 OnCustomPaint is to be called.
1200 Normally -1, but can be an index to the property's list of items.
1202 - Default behavior is to return wxSize(0,0), which means no image.
1203 - Default image width or height is indicated with dimension -1.
1204 - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1).
1206 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
1209 Events received by editor widgets are processed here.
1211 Note that editor class usually processes most events. Some, such as
1212 button press events of TextCtrlAndButton class, can be handled here.
1213 Also, if custom handling for regular events is desired, then that can
1214 also be done (for example, wxSystemColourProperty custom handles
1215 wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
1216 'custom' selection is made).
1218 If the event causes value to be changed, SetValueInEvent()
1219 should be called to set the new value.
1224 Should return true if any changes in value should be reported.
1226 If property uses choice control, and displays a dialog on some choice
1227 items, then it is preferred to display that dialog in IntToValue
1230 virtual bool OnEvent( wxPropertyGrid
* propgrid
,
1231 wxWindow
* wnd_primary
,
1235 Called after value of a child property has been altered. Must return
1236 new value of the whole property (after any alterations warrented by
1239 Note that this function is usually called at the time that value of
1240 this property, or given child property, is still pending for change,
1241 and as such, result of GetValue() or m_value should not be relied
1244 Sample pseudo-code implementation:
1247 wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
1249 wxVariant& childValue ) const
1251 // Acquire reference to actual type of data stored in variant
1252 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
1253 // were used to create the variant class).
1254 T& data = TFromVariant(thisValue);
1256 // Copy childValue into data.
1257 switch ( childIndex )
1260 data.SetSubProp1( childvalue.GetLong() );
1263 data.SetSubProp2( childvalue.GetString() );
1268 // Return altered data
1274 Value of this property. Changed value should be returned (in
1275 previous versions of wxPropertyGrid it was only necessary to
1276 write value back to this argument).
1278 Index of child changed (you can use Item(childIndex) to get
1281 (Pending) value of the child property.
1284 Modified value of the whole property.
1286 virtual wxVariant
ChildChanged( wxVariant
& thisValue
,
1288 wxVariant
& childValue
) const;
1290 /** Returns pointer to an instance of used editor.
1292 virtual const wxPGEditor
* DoGetEditorClass() const;
1294 /** Returns pointer to the wxValidator that should be used
1295 with the editor of this property (NULL for no validator).
1296 Setting validator explicitly via SetPropertyValidator
1299 In most situations, code like this should work well
1300 (macros are used to maintain one actual validator instance,
1301 so on the second call the function exits within the first
1306 wxValidator* wxMyPropertyClass::DoGetValidator () const
1308 WX_PG_DOGETVALIDATOR_ENTRY()
1310 wxMyValidator* validator = new wxMyValidator(...);
1312 ... prepare validator...
1314 WX_PG_DOGETVALIDATOR_EXIT(validator)
1320 You can get common filename validator by returning
1321 wxFileProperty::GetClassValidator(). wxDirProperty,
1322 for example, uses it.
1324 virtual wxValidator
* DoGetValidator () const;
1327 Override to paint an image in front of the property value text or
1328 drop-down list item (but only if wxPGProperty::OnMeasureImage is
1329 overridden as well).
1331 If property's OnMeasureImage() returns size that has height != 0 but
1332 less than row height ( < 0 has special meanings), wxPropertyGrid calls
1333 this method to draw a custom image in a limited area in front of the
1334 editor control or value text/graphics, and if control has drop-down
1335 list, then the image is drawn there as well (even in the case
1336 OnMeasureImage() returned higher height than row height).
1338 NOTE: Following applies when OnMeasureImage() returns a "flexible"
1339 height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
1340 height items: If rect.x is < 0, then this is a measure item call, which
1341 means that dc is invalid and only thing that should be done is to set
1342 paintdata.m_drawnHeight to the height of the image of item at index
1343 paintdata.m_choiceItem. This call may be done even as often as once
1344 every drop-down popup show.
1349 Box reserved for custom graphics. Includes surrounding rectangle,
1350 if any. If x is < 0, then this is a measure item call (see above).
1352 wxPGPaintData structure with much useful data.
1355 - You can actually exceed rect width, but if you do so then
1356 paintdata.m_drawnWidth must be set to the full width drawn in
1358 - Due to technical reasons, rect's height will be default even if
1359 custom height was reported during measure call.
1360 - Brush is guaranteed to be default background colour. It has been
1361 already used to clear the background of area being painted. It
1363 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper
1364 colour) pen for drawing framing rectangle. It can be changed as
1367 @see ValueToString()
1369 virtual void OnCustomPaint( wxDC
& dc
,
1371 wxPGPaintData
& paintdata
);
1374 Returns used wxPGCellRenderer instance for given property column
1377 Default implementation returns editor's renderer for all columns.
1379 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
1381 /** Returns which choice is currently selected. Only applies to properties
1384 Needs to reimplemented in derived class if property value does not
1385 map directly to a choice. Integer as index, bool, and string usually do.
1387 virtual int GetChoiceSelection() const;
1390 Refresh values of child properties.
1392 Automatically called after value is set.
1394 virtual void RefreshChildren();
1396 /** Special handling for attributes of this property.
1398 If returns false, then the attribute will be automatically stored in
1401 Default implementation simply returns false.
1403 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
1405 /** Returns value of an attribute.
1407 Override if custom handling of attributes is needed.
1409 Default implementation simply return NULL variant.
1411 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
1413 /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
1414 used when user presses the (optional) button next to the editor control;
1416 Default implementation returns NULL (ie. no action is generated when
1419 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
1422 Called whenever validation has failed with given pending value.
1424 @remarks If you implement this in your custom property class, please
1425 remember to call the baser implementation as well, since they
1426 may use it to revert property into pre-change state.
1428 virtual void OnValidationFailure( wxVariant
& pendingValue
);
1430 /** Append a new choice to property's list of choices.
1432 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
)
1434 return InsertChoice(label
, wxNOT_FOUND
, value
);
1438 Returns true if children of this property are component values (for
1439 instance, points size, face name, and is_underlined are component
1442 bool AreChildrenComponents() const
1444 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
1451 Deletes children of the property.
1453 void DeleteChildren();
1456 Removes entry from property's wxPGChoices and editor control (if it is
1459 If selected item is deleted, then the value is set to unspecified.
1461 void DeleteChoice( int index
);
1464 Call to enable or disable usage of common value (integer value that can
1465 be selected for properties instead of their normal values) for this
1468 Common values are disabled by the default for all properties.
1470 void EnableCommonValue( bool enable
= true )
1472 if ( enable
) SetFlag( wxPG_PROP_USES_COMMON_VALUE
);
1473 else ClearFlag( wxPG_PROP_USES_COMMON_VALUE
);
1477 Composes text from values of child properties.
1479 wxString
GenerateComposedValue() const
1482 DoGenerateComposedValue(s
);
1486 /** Returns property's label. */
1487 const wxString
& GetLabel() const { return m_label
; }
1489 /** Returns property's name with all (non-category, non-root) parents. */
1490 wxString
GetName() const;
1493 Returns property's base name (ie parent's name is not added in any
1496 const wxString
& GetBaseName() const { return m_name
; }
1498 /** Returns read-only reference to property's list of choices.
1500 const wxPGChoices
& GetChoices() const
1505 /** Returns coordinate to the top y of the property. Note that the
1506 position of scrollbars is not taken into account.
1510 wxVariant
GetValue() const
1512 return DoGetValue();
1515 /** Returns reference to the internal stored value. GetValue is preferred
1516 way to get the actual value, since GetValueRef ignores DoGetValue,
1517 which may override stored value.
1519 wxVariant
& GetValueRef()
1524 const wxVariant
& GetValueRef() const
1529 // Helper function (for wxPython bindings and such) for settings protected
1531 wxVariant
GetValuePlain() const
1536 /** Returns text representation of property's value.
1539 If 0 (default value), then displayed string is returned.
1540 If wxPG_FULL_VALUE is set, returns complete, storable string value
1541 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1542 string value that must be editable in textctrl. If
1543 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1544 display as a part of string property's composite text
1547 @remarks In older versions, this function used to be overridden to convert
1548 property's value into a string representation. This function is
1549 now handled by ValueToString(), and overriding this function now
1550 will result in run-time assertion failure.
1552 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
1554 /** Synonymous to GetValueAsString().
1556 @deprecated Use GetValueAsString() instead.
1558 @see GetValueAsString()
1560 wxDEPRECATED( wxString
GetValueString( int argFlags
= 0 ) const );
1563 Returns wxPGCell of given column.
1565 const wxPGCell
& GetCell( unsigned int column
) const;
1567 wxPGCell
& GetCell( unsigned int column
);
1569 /** Return number of displayed common values for this property.
1571 int GetDisplayedCommonValueCount() const;
1573 wxString
GetDisplayedString() const
1575 return GetValueAsString(0);
1578 /** Returns property grid where property lies. */
1579 wxPropertyGrid
* GetGrid() const;
1581 /** Returns owner wxPropertyGrid, but only if one is currently on a page
1582 displaying this property. */
1583 wxPropertyGrid
* GetGridIfDisplayed() const;
1585 /** Returns highest level non-category, non-root parent. Useful when you
1586 have nested wxCustomProperties/wxParentProperties.
1588 Thus, if immediate parent is root or category, this will return the
1591 wxPGProperty
* GetMainParent() const;
1593 /** Return parent of property */
1594 wxPGProperty
* GetParent() const { return m_parent
; }
1596 /** Returns true if property has editable wxTextCtrl when selected.
1599 Altough disabled properties do not displayed editor, they still
1600 return True here as being disabled is considered a temporary
1601 condition (unlike being read-only or having limited editing enabled).
1603 bool IsTextEditable() const;
1605 bool IsValueUnspecified() const
1607 return m_value
.IsNull();
1610 FlagType
HasFlag( FlagType flag
) const
1612 return ( m_flags
& flag
);
1615 /** Returns comma-delimited string of property attributes.
1617 const wxPGAttributeStorage
& GetAttributes() const
1619 return m_attributes
;
1622 /** Returns m_attributes as list wxVariant.
1624 wxVariant
GetAttributesAsList() const;
1626 FlagType
GetFlags() const
1631 const wxPGEditor
* GetEditorClass() const;
1633 wxString
GetValueType() const
1635 return m_value
.GetType();
1638 /** Returns editor used for given column. NULL for no editor.
1640 const wxPGEditor
* GetColumnEditor( int column
) const
1643 return GetEditorClass();
1648 /** Returns common value selected for this property. -1 for none.
1650 int GetCommonValue() const
1652 return m_commonValue
;
1655 /** Returns true if property has even one visible child.
1657 bool HasVisibleChildren() const;
1660 Use this member function to add independent (ie. regular) children to
1663 @return Inserted childProperty.
1665 @remarks wxPropertyGrid is not automatically refreshed by this
1668 @see AddPrivateChild()
1670 wxPGProperty
* InsertChild( int index
, wxPGProperty
* childProperty
);
1672 /** Inserts a new choice to property's list of choices.
1674 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1677 Returns true if this property is actually a wxPropertyCategory.
1679 bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY
)?true:false; }
1681 /** Returns true if this property is actually a wxRootProperty.
1683 bool IsRoot() const { return (m_parent
== NULL
); }
1685 /** Returns true if this is a sub-property. */
1686 bool IsSubProperty() const
1688 wxPGProperty
* parent
= (wxPGProperty
*)m_parent
;
1689 if ( parent
&& !parent
->IsCategory() )
1694 /** Returns last visible sub-property, recursively.
1696 const wxPGProperty
* GetLastVisibleSubItem() const;
1698 wxVariant
GetDefaultValue() const;
1700 int GetMaxLength() const
1702 return (int) m_maxLen
;
1706 Determines, recursively, if all children are not unspecified.
1709 Assumes members in this wxVariant list as pending
1712 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
1714 /** Updates composed values of parent non-category properties, recursively.
1715 Returns topmost property updated.
1718 - Must not call SetValue() (as can be called in it).
1720 wxPGProperty
* UpdateParentValues();
1722 /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1724 bool UsesAutoUnspecified() const
1726 return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED
)?true:false;
1729 wxBitmap
* GetValueImage() const
1731 return m_valueBitmap
;
1734 wxVariant
GetAttribute( const wxString
& name
) const;
1737 Returns named attribute, as string, if found.
1739 Otherwise defVal is returned.
1741 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1744 Returns named attribute, as long, if found.
1746 Otherwise defVal is returned.
1748 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1751 Returns named attribute, as double, if found.
1753 Otherwise defVal is returned.
1755 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1757 unsigned int GetDepth() const { return (unsigned int)m_depth
; }
1759 /** Gets flags as a'|' delimited string. Note that flag names are not
1760 prepended with 'wxPG_PROP_'.
1762 String will only be made to include flags combined by this parameter.
1764 wxString
GetFlagsAsString( FlagType flagsMask
) const;
1766 /** Returns position in parent's array. */
1767 unsigned int GetIndexInParent() const
1769 return (unsigned int)m_arrIndex
;
1772 /** Hides or reveals the property.
1774 true for hide, false for reveal.
1776 By default changes are applied recursively. Set this paramter
1777 wxPG_DONT_RECURSE to prevent this.
1779 inline bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1781 bool IsExpanded() const
1782 { return (!(m_flags
& wxPG_PROP_COLLAPSED
) && GetChildCount()); }
1784 /** Returns true if all parents expanded.
1786 bool IsVisible() const;
1788 bool IsEnabled() const { return !(m_flags
& wxPG_PROP_DISABLED
); }
1790 /** If property's editor is created this forces its recreation.
1791 Useful in SetAttribute etc. Returns true if actually did anything.
1793 bool RecreateEditor();
1795 /** If property's editor is active, then update it's value.
1797 void RefreshEditor();
1799 /** Sets an attribute for this property.
1801 Text identifier of attribute. See @ref propgrid_property_attributes.
1805 void SetAttribute( const wxString
& name
, wxVariant value
);
1807 void SetAttributes( const wxPGAttributeStorage
& attributes
);
1810 Sets property's background colour.
1813 Background colour to use.
1816 If @true, children are affected recursively, and any categories
1819 void SetBackgroundColour( const wxColour
& colour
,
1820 bool recursively
= false );
1823 Sets property's text colour.
1829 If @true, children are affected recursively, and any categories
1832 void SetTextColour( const wxColour
& colour
,
1833 bool recursively
= false );
1835 /** Set default value of a property. Synonymous to
1838 SetAttribute("DefaultValue", value);
1841 void SetDefaultValue( wxVariant
& value
);
1844 /** Sets editor for a property.
1847 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1848 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
1851 For custom editors, use pointer you received from
1852 wxPropertyGrid::RegisterEditorClass().
1854 void SetEditor( const wxPGEditor
* editor
)
1856 m_customEditor
= editor
;
1860 /** Sets editor for a property.
1862 inline void SetEditor( const wxString
& editorName
);
1865 Sets cell information for given column.
1867 void SetCell( int column
, const wxPGCell
& cell
);
1869 /** Sets common value selected for this property. -1 for none.
1871 void SetCommonValue( int commonValue
)
1873 m_commonValue
= commonValue
;
1876 /** Sets flags from a '|' delimited string. Note that flag names are not
1877 prepended with 'wxPG_PROP_'.
1879 void SetFlagsFromString( const wxString
& str
);
1881 /** Sets property's "is it modified?" flag. Affects children recursively.
1883 void SetModifiedStatus( bool modified
)
1885 SetFlagRecursively(wxPG_PROP_MODIFIED
, modified
);
1888 /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1889 based on user input.
1892 This method is const since it doesn't actually modify value, but posts
1893 given variant as pending value, stored in wxPropertyGrid.
1895 void SetValueInEvent( wxVariant value
) const;
1898 Call this to set value of the property.
1900 Unlike methods in wxPropertyGrid, this does not automatically update
1904 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
1905 through validation process and send property change event.
1907 If you need to change property value in event, based on user input, use
1908 SetValueInEvent() instead.
1911 Pointer to list variant that contains child values. Used to
1912 indicate which children should be marked as modified.
1915 Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR, which is
1916 enabled by default).
1918 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
,
1919 int flags
= wxPG_SETVAL_REFRESH_EDITOR
);
1921 /** Set wxBitmap in front of the value. This bitmap may be ignored
1922 by custom cell renderers.
1924 void SetValueImage( wxBitmap
& bmp
);
1926 /** Sets selected choice and changes property value.
1928 Tries to retain value type, although currently if it is not string,
1929 then it is forced to integer.
1931 void SetChoiceSelection( int newValue
);
1933 void SetExpanded( bool expanded
)
1935 if ( !expanded
) m_flags
|= wxPG_PROP_COLLAPSED
;
1936 else m_flags
&= ~wxPG_PROP_COLLAPSED
;
1940 Sets given property flag(s).
1942 void SetFlag( FlagType flag
) { m_flags
|= flag
; }
1945 Sets or clears given property flag(s).
1947 void ChangeFlag( FlagType flag
, bool set
)
1955 void SetFlagRecursively( FlagType flag
, bool set
);
1957 void SetHelpString( const wxString
& helpString
)
1959 m_helpString
= helpString
;
1962 void SetLabel( const wxString
& label
) { m_label
= label
; }
1964 void SetName( const wxString
& newName
);
1967 Changes what sort of parent this property is for its children.
1970 Use one of the following values: wxPG_PROP_MISC_PARENT (for
1971 generic parents), wxPG_PROP_CATEGORY (for categories), or
1972 wxPG_PROP_AGGREGATE (for derived property classes with private
1975 @remarks You generally do not need to call this function.
1977 void SetParentalType( int flag
)
1979 m_flags
&= ~(wxPG_PROP_PROPERTY
|wxPG_PROP_PARENTAL_FLAGS
);
1983 void SetValueToUnspecified()
1985 wxVariant val
; // Create NULL variant
1989 // Helper function (for wxPython bindings and such) for settings protected
1991 void SetValuePlain( wxVariant value
)
1996 #if wxUSE_VALIDATORS
1997 /** Sets wxValidator for a property*/
1998 void SetValidator( const wxValidator
& validator
)
2000 m_validator
= wxDynamicCast(validator
.Clone(),wxValidator
);
2003 /** Gets assignable version of property's validator. */
2004 wxValidator
* GetValidator() const
2008 return DoGetValidator();
2010 #endif // #if wxUSE_VALIDATORS
2013 /** Returns client data (void*) of a property.
2015 void* GetClientData() const
2017 return m_clientData
;
2020 /** Sets client data (void*) of a property.
2022 This untyped client data has to be deleted manually.
2024 void SetClientData( void* clientData
)
2026 m_clientData
= clientData
;
2029 /** Returns client object of a property.
2031 void SetClientObject(wxClientData
* clientObject
)
2033 delete m_clientObject
;
2034 m_clientObject
= clientObject
;
2037 /** Sets managed client object of a property.
2039 wxClientData
*GetClientObject() const { return m_clientObject
; }
2042 /** Sets new set of choices for property.
2045 This operation clears the property value.
2047 bool SetChoices( wxPGChoices
& choices
);
2049 /** Set max length of text in text editor.
2051 inline bool SetMaxLength( int maxLen
);
2053 /** Call with 'false' in OnSetValue to cancel value changes after all
2054 (ie. cancel 'true' returned by StringToValue() or IntToValue()).
2056 void SetWasModified( bool set
= true )
2058 if ( set
) m_flags
|= wxPG_PROP_WAS_MODIFIED
;
2059 else m_flags
&= ~wxPG_PROP_WAS_MODIFIED
;
2062 const wxString
& GetHelpString() const
2064 return m_helpString
;
2067 void ClearFlag( FlagType flag
) { m_flags
&= ~(flag
); }
2069 // Use, for example, to detect if item is inside collapsed section.
2070 bool IsSomeParent( wxPGProperty
* candidate_parent
) const;
2073 Adapts list variant into proper value using consecutive
2076 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
2078 #if wxPG_COMPATIBILITY_1_4
2080 Adds a private child property.
2082 @deprecated Use AddPrivateChild() instead.
2084 @see AddPrivateChild()
2086 wxDEPRECATED( void AddChild( wxPGProperty
* prop
) );
2090 Adds a private child property. If you use this instead of
2091 wxPropertyGridInterface::Insert() or
2092 wxPropertyGridInterface::AppendIn(), then property's parental
2093 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
2094 words, all properties of this property will become private.
2096 void AddPrivateChild( wxPGProperty
* prop
);
2099 Appends a new child property.
2101 wxPGProperty
* AppendChild( wxPGProperty
* prop
)
2103 return InsertChild(-1, prop
);
2106 /** Returns height of children, recursively, and
2107 by taking expanded/collapsed status into account.
2109 iMax is used when finding property y-positions.
2111 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
2113 /** Returns number of child properties */
2114 unsigned int GetChildCount() const
2116 return (unsigned int) m_children
.size();
2119 /** Returns sub-property at index i. */
2120 wxPGProperty
* Item( unsigned int i
) const
2121 { return m_children
[i
]; }
2123 /** Returns last sub-property.
2125 wxPGProperty
* Last() const { return m_children
.back(); }
2127 /** Returns index of given child property. */
2128 int Index( const wxPGProperty
* p
) const;
2130 // Puts correct indexes to children
2131 void FixIndicesOfChildren( unsigned int starthere
= 0 );
2134 Converts image width into full image offset, with margins.
2136 int GetImageOffset( int imageWidth
) const;
2139 // Returns wxPropertyGridPageState in which this property resides.
2140 wxPropertyGridPageState
* GetParentState() const { return m_parentState
; }
2144 wxPGProperty
* GetItemAtY( unsigned int y
,
2146 unsigned int* nextItemY
) const;
2149 /** Returns property at given virtual y coordinate.
2151 wxPGProperty
* GetItemAtY( unsigned int y
) const;
2153 /** Returns (direct) child property with given name (or NULL if not found).
2155 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
2159 // Returns various display-related information for given column
2160 void GetDisplayInfo( unsigned int column
,
2164 const wxPGCell
** pCell
);
2166 static wxString
* sm_wxPG_LABEL
;
2168 /** This member is public so scripting language bindings
2169 wrapper code can access it freely.
2176 Sets property cell in fashion that reduces number of exclusive
2177 copies of cell data. Used when setting, for instance, same
2178 background colour for a number of properties.
2181 First column to affect.
2184 Last column to affect.
2187 Pre-prepared cell that is used for those which cell data
2188 before this matched unmodCellData.
2191 If unmodCellData did not match, valid cell data from this
2192 is merged into cell (usually generating new exclusive copy
2195 @param unmodCellData
2196 If cell's cell data matches this, its cell is now set to
2199 @param ignoreWithFlags
2200 Properties with any one of these flags are skipped.
2203 If @true, apply this operation recursively in child properties.
2205 void AdaptiveSetCell( unsigned int firstCol
,
2206 unsigned int lastCol
,
2207 const wxPGCell
& preparedCell
,
2208 const wxPGCell
& srcData
,
2209 wxPGCellData
* unmodCellData
,
2210 FlagType ignoreWithFlags
,
2214 Makes sure m_cells has size of column+1 (or more).
2216 void EnsureCells( unsigned int column
);
2218 /** Returns (direct) child property with given name (or NULL if not found),
2222 Start looking for the child at this index.
2225 Does not support scope (ie. Parent.Child notation).
2227 wxPGProperty
* GetPropertyByNameWH( const wxString
& name
,
2228 unsigned int hintIndex
) const;
2230 /** This is used by Insert etc. */
2231 void DoAddChild( wxPGProperty
* prop
,
2233 bool correct_mode
= true );
2235 void DoGenerateComposedValue( wxString
& text
,
2236 int argFlags
= wxPG_VALUE_IS_CURRENT
,
2237 const wxVariantList
* valueOverrides
= NULL
,
2238 wxPGHashMapS2S
* childResults
= NULL
) const;
2240 void DoSetName(const wxString
& str
) { m_name
= str
; }
2242 /** Deletes all sub-properties. */
2245 void InitAfterAdded( wxPropertyGridPageState
* pageState
,
2246 wxPropertyGrid
* propgrid
);
2248 // Removes child property with given pointer. Does not delete it.
2249 void RemoveChild( wxPGProperty
* p
);
2251 void DoPreAddChild( int index
, wxPGProperty
* prop
);
2253 void SetParentState( wxPropertyGridPageState
* pstate
)
2254 { m_parentState
= pstate
; }
2256 // Call after fixed sub-properties added/removed after creation.
2257 // if oldSelInd >= 0 and < new max items, then selection is
2259 void SubPropsChanged( int oldSelInd
= -1 );
2261 int GetY2( int lh
) const;
2265 wxPGProperty
* m_parent
;
2266 wxPropertyGridPageState
* m_parentState
;
2268 wxClientData
* m_clientObject
;
2270 // Overrides editor returned by property class
2271 const wxPGEditor
* m_customEditor
;
2272 #if wxUSE_VALIDATORS
2273 // Editor is going to get this validator
2274 wxValidator
* m_validator
;
2276 // Show this in front of the value
2278 // TODO: Can bitmap be implemented with wxPGCell?
2279 wxBitmap
* m_valueBitmap
;
2282 wxPGAttributeStorage m_attributes
;
2283 wxArrayPGProperty m_children
;
2285 // Extended cell information
2286 wxVector
<wxPGCell
> m_cells
;
2288 // Choices shown in drop-down list of editor control.
2289 wxPGChoices m_choices
;
2291 // Help shown in statusbar or help box.
2292 wxString m_helpString
;
2294 // Index in parent's property array.
2295 unsigned int m_arrIndex
;
2297 // If not -1, then overrides m_value
2302 // Maximum length (mainly for string properties). Could be in some sort of
2303 // wxBaseStringProperty, but currently, for maximum flexibility and
2304 // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
2305 // so short int will fit in just fine.
2308 // Root has 0, categories etc. at that level 1, etc.
2309 unsigned char m_depth
;
2311 // m_depthBgCol indicates width of background colour between margin and item
2312 // (essentially this is category's depth, if none then equals m_depth).
2313 unsigned char m_depthBgCol
;
2316 // Called in constructors.
2318 void Init( const wxString
& label
, const wxString
& name
);
2319 #endif // #ifndef SWIG
2322 // -----------------------------------------------------------------------
2325 // Property class declaration helper macros
2326 // (wxPGRootPropertyClass and wxPropertyCategory require this).
2329 #define WX_PG_DECLARE_DOGETEDITORCLASS \
2330 virtual const wxPGEditor* DoGetEditorClass() const;
2333 #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
2335 DECLARE_DYNAMIC_CLASS(CLASSNAME) \
2336 WX_PG_DECLARE_DOGETEDITORCLASS \
2339 #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME)
2342 // Implements sans constructor function. Also, first arg is class name, not
2344 #define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
2345 const wxPGEditor* PROPNAME::DoGetEditorClass() const \
2347 return wxPGEditor_##EDITOR; \
2350 // -----------------------------------------------------------------------
2354 /** @class wxPGRootProperty
2356 Root parent property.
2358 class WXDLLIMPEXP_PROPGRID wxPGRootProperty
: public wxPGProperty
2361 WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty
)
2365 wxPGRootProperty( const wxString
& name
= wxS("<Root>") );
2366 virtual ~wxPGRootProperty();
2368 virtual bool StringToValue( wxVariant
&, const wxString
&, int ) const
2376 // -----------------------------------------------------------------------
2378 /** @class wxPropertyCategory
2380 Category (caption) property.
2382 class WXDLLIMPEXP_PROPGRID wxPropertyCategory
: public wxPGProperty
2384 friend class wxPropertyGrid
;
2385 friend class wxPropertyGridPageState
;
2386 WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory
)
2389 /** Default constructor is only used in special cases. */
2390 wxPropertyCategory();
2392 wxPropertyCategory( const wxString
& label
,
2393 const wxString
& name
= wxPG_LABEL
);
2394 ~wxPropertyCategory();
2396 int GetTextExtent( const wxWindow
* wnd
, const wxFont
& font
) const;
2398 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
) const;
2401 void SetTextColIndex( unsigned int colInd
)
2402 { m_capFgColIndex
= (wxByte
) colInd
; }
2403 unsigned int GetTextColIndex() const
2404 { return (unsigned int) m_capFgColIndex
; }
2406 void CalculateTextExtent( wxWindow
* wnd
, const wxFont
& font
);
2408 int m_textExtent
; // pre-calculated length of text
2409 wxByte m_capFgColIndex
; // caption text colour index
2417 // -----------------------------------------------------------------------
2419 #endif // wxUSE_PROPGRID
2421 #endif // _WX_PROPGRID_PROPERTY_H_