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
50 // space between vertical sides of a custom image
51 #define wxPG_CUSTOM_IMAGE_SPACINGY 1
53 // space between caption and selection rectangle,
54 #define wxPG_CAPRECTXMARGIN 2
56 // horizontally and vertically
57 #define wxPG_CAPRECTYMARGIN 1
60 /** @class wxPGCellRenderer
62 Base class for wxPropertyGrid cell renderers.
64 class WXDLLIMPEXP_PROPGRID wxPGCellRenderer
: public wxObjectRefData
69 : wxObjectRefData() { }
70 virtual ~wxPGCellRenderer() { }
75 // We are painting selected item
76 Selected
= 0x00010000,
78 // We are painting item in choice popup
79 ChoicePopup
= 0x00020000,
81 // We are rendering wxOwnerDrawnComboBox control
82 // (or other owner drawn control, but that is only
83 // officially supported one ATM).
86 // We are painting a disable property
87 Disabled
= 0x00080000,
89 // We are painting selected, disabled, or similar
90 // item that dictates fore- and background colours,
91 // overriding any cell values.
92 DontUseCellFgCol
= 0x00100000,
93 DontUseCellBgCol
= 0x00200000,
94 DontUseCellColours
= DontUseCellFgCol
|
99 Returns @true if rendered something in the foreground (text or
102 virtual bool Render( wxDC
& dc
,
104 const wxPropertyGrid
* propertyGrid
,
105 wxPGProperty
* property
,
108 int flags
) const = 0;
110 /** Returns size of the image in front of the editable area.
112 If property is NULL, then this call is for a custom value. In that case
113 the item is index to wxPropertyGrid's custom values.
115 virtual wxSize
GetImageSize( const wxPGProperty
* property
,
119 /** Paints property category selection rectangle.
121 virtual void DrawCaptionSelectionRect( wxDC
& dc
,
123 int w
, int h
) const;
125 /** Utility to draw vertically centered text.
127 void DrawText( wxDC
& dc
,
130 const wxString
& text
) const;
133 Utility to draw editor's value, or vertically aligned text if editor is
136 void DrawEditorValue( wxDC
& dc
, const wxRect
& rect
,
137 int xOffset
, const wxString
& text
,
138 wxPGProperty
* property
,
139 const wxPGEditor
* editor
) const;
141 /** Utility to render cell bitmap and set text colour plus bg brush
144 @return Returns image width, which, for instance, can be passed to
147 int PreDrawCell( wxDC
& dc
,
149 const wxPGCell
& cell
,
153 Utility to be called after drawing is done, to revert whatever
154 changes PreDrawCell() did.
157 Same as those passed to PreDrawCell().
159 void PostDrawCell( wxDC
& dc
,
160 const wxPropertyGrid
* propGrid
,
161 const wxPGCell
& cell
,
167 @class wxPGDefaultRenderer
169 Default cell renderer, that can handles the common
172 class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer
: public wxPGCellRenderer
175 virtual bool Render( wxDC
& dc
,
177 const wxPropertyGrid
* propertyGrid
,
178 wxPGProperty
* property
,
183 virtual wxSize
GetImageSize( const wxPGProperty
* property
,
191 class WXDLLIMPEXP_PROPGRID wxPGCellData
: public wxObjectRefData
193 friend class wxPGCell
;
197 void SetText( const wxString
& text
)
200 m_hasValidText
= true;
202 void SetBitmap( const wxBitmap
& bitmap
) { m_bitmap
= bitmap
; }
203 void SetFgCol( const wxColour
& col
) { m_fgCol
= col
; }
204 void SetBgCol( const wxColour
& col
) { m_bgCol
= col
; }
205 void SetFont( const wxFont
& font
) { m_font
= font
; }
208 virtual ~wxPGCellData() { }
216 // True if m_text is valid and specified
224 Base class for wxPropertyGrid cell information.
226 class WXDLLIMPEXP_PROPGRID wxPGCell
: public wxObject
230 wxPGCell(const wxPGCell
& other
)
235 wxPGCell( const wxString
& text
,
236 const wxBitmap
& bitmap
= wxNullBitmap
,
237 const wxColour
& fgCol
= wxNullColour
,
238 const wxColour
& bgCol
= wxNullColour
);
240 virtual ~wxPGCell() { }
242 wxPGCellData
* GetData()
244 return (wxPGCellData
*) m_refData
;
247 const wxPGCellData
* GetData() const
249 return (const wxPGCellData
*) m_refData
;
254 return (m_refData
&& GetData()->m_hasValidText
);
258 Sets empty but valid data to this cell object.
263 Merges valid data from srcCell into this.
265 void MergeFrom( const wxPGCell
& srcCell
);
267 void SetText( const wxString
& text
);
268 void SetBitmap( const wxBitmap
& bitmap
);
269 void SetFgCol( const wxColour
& col
);
272 Sets font of the cell.
274 @remarks Because wxPropertyGrid does not support rows of
275 different height, it makes little sense to change
276 size of the font. Therefore it is recommended
277 to use return value of wxPropertyGrid::GetFont()
278 or wxPropertyGrid::GetCaptionFont() as a basis
279 for the font that, after modifications, is passed
280 to this member function.
282 void SetFont( const wxFont
& font
);
284 void SetBgCol( const wxColour
& col
);
286 const wxString
& GetText() const { return GetData()->m_text
; }
287 const wxBitmap
& GetBitmap() const { return GetData()->m_bitmap
; }
288 const wxColour
& GetFgCol() const { return GetData()->m_fgCol
; }
291 Returns font of the cell. If no specific font is set for this
292 cell, then the font will be invalid.
294 const wxFont
& GetFont() const { return GetData()->m_font
; }
296 const wxColour
& GetBgCol() const { return GetData()->m_bgCol
; }
298 wxPGCell
& operator=( const wxPGCell
& other
)
300 if ( this != &other
)
308 virtual wxObjectRefData
*CreateRefData() const
309 { return new wxPGCellData(); }
311 virtual wxObjectRefData
*CloneRefData(const wxObjectRefData
*data
) const;
314 // -----------------------------------------------------------------------
316 /** @class wxPGAttributeStorage
318 wxPGAttributeStorage is somewhat optimized storage for
319 key=variant pairs (ie. a map).
321 class WXDLLIMPEXP_PROPGRID wxPGAttributeStorage
324 wxPGAttributeStorage();
325 ~wxPGAttributeStorage();
327 void Set( const wxString
& name
, const wxVariant
& value
);
328 unsigned int GetCount() const { return (unsigned int) m_map
.size(); }
329 wxVariant
FindValue( const wxString
& name
) const
331 wxPGHashMapS2P::const_iterator it
= m_map
.find(name
);
332 if ( it
!= m_map
.end() )
334 wxVariantData
* data
= (wxVariantData
*) it
->second
;
336 return wxVariant(data
, it
->first
);
341 typedef wxPGHashMapS2P::const_iterator const_iterator
;
342 const_iterator
StartIteration() const
344 return m_map
.begin();
346 bool GetNext( const_iterator
& it
, wxVariant
& variant
) const
348 if ( it
== m_map
.end() )
351 wxVariantData
* data
= (wxVariantData
*) it
->second
;
353 variant
.SetData(data
);
354 variant
.SetName(it
->first
);
360 wxPGHashMapS2P m_map
;
364 // -----------------------------------------------------------------------
366 /** @section propgrid_propflags wxPGProperty Flags
370 enum wxPG_PROPERTY_FLAGS
373 /** Indicates bold font.
375 wxPG_PROP_MODIFIED
= 0x0001,
377 /** Disables ('greyed' text and editor does not activate) property.
379 wxPG_PROP_DISABLED
= 0x0002,
381 /** Hider button will hide this property.
383 wxPG_PROP_HIDDEN
= 0x0004,
385 /** This property has custom paint image just in front of its value.
386 If property only draws custom images into a popup list, then this
387 flag should not be set.
389 wxPG_PROP_CUSTOMIMAGE
= 0x0008,
391 /** Do not create text based editor for this property (but button-triggered
392 dialog and choice are ok).
394 wxPG_PROP_NOEDITOR
= 0x0010,
396 /** Property is collapsed, ie. it's children are hidden.
398 wxPG_PROP_COLLAPSED
= 0x0020,
401 If property is selected, then indicates that validation failed for pending
404 If property is not selected, then indicates that the the actual property
405 value has failed validation (NB: this behavior is not currently supported,
406 but may be used in future).
408 wxPG_PROP_INVALID_VALUE
= 0x0040,
412 /** Switched via SetWasModified(). Temporary flag - only used when
413 setting/changing property value.
415 wxPG_PROP_WAS_MODIFIED
= 0x0200,
418 If set, then child properties (if any) are private, and should be
419 "invisible" to the application.
421 wxPG_PROP_AGGREGATE
= 0x0400,
423 /** If set, then child properties (if any) are copies and should not
426 wxPG_PROP_CHILDREN_ARE_COPIES
= 0x0800,
429 Classifies this item as a non-category.
431 Used for faster item type identification.
433 wxPG_PROP_PROPERTY
= 0x1000,
436 Classifies this item as a category.
438 Used for faster item type identification.
440 wxPG_PROP_CATEGORY
= 0x2000,
442 /** Classifies this item as a property that has children, but is not aggregate
443 (ie children are not private).
445 wxPG_PROP_MISC_PARENT
= 0x4000,
447 /** Property is read-only. Editor is still created for wxTextCtrl-based
448 property editors. For others, editor is not usually created because
449 they do implement wxTE_READONLY style or equivalent.
451 wxPG_PROP_READONLY
= 0x8000,
454 // NB: FLAGS ABOVE 0x8000 CANNOT BE USED WITH PROPERTY ITERATORS
457 /** Property's value is composed from values of child properties.
459 This flag cannot be used with property iterators.
461 wxPG_PROP_COMPOSED_VALUE
= 0x00010000,
463 /** Common value of property is selectable in editor.
465 This flag cannot be used with property iterators.
467 wxPG_PROP_USES_COMMON_VALUE
= 0x00020000,
469 /** Property can be set to unspecified value via editor.
470 Currently, this applies to following properties:
471 - wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty:
475 This flag cannot be used with property iterators.
477 wxPG_PROP_AUTO_UNSPECIFIED
= 0x00040000,
479 /** Indicates the bit useable by derived properties.
481 wxPG_PROP_CLASS_SPECIFIC_1
= 0x00080000,
483 /** Indicates the bit useable by derived properties.
485 wxPG_PROP_CLASS_SPECIFIC_2
= 0x00100000,
487 /** Indicates that the property is being deleted and should be ignored.
489 wxPG_PROP_BEING_DELETED
= 0x00200000
495 #define wxPG_PROP_MAX wxPG_PROP_AUTO_UNSPECIFIED
497 /** Property with children must have one of these set, otherwise iterators
498 will not work correctly.
499 Code should automatically take care of this, however.
501 #define wxPG_PROP_PARENTAL_FLAGS \
502 (wxPG_PROP_AGGREGATE|wxPG_PROP_CATEGORY|wxPG_PROP_MISC_PARENT)
507 // Combination of flags that can be stored by GetFlagsAsString
508 #define wxPG_STRING_STORED_FLAGS \
509 (wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED)
511 // -----------------------------------------------------------------------
514 @section propgrid_property_attributes wxPropertyGrid Property Attribute
517 wxPGProperty::SetAttribute() and
518 wxPropertyGridInterface::SetPropertyAttribute() accept one of these as
519 attribute name argument.
521 You can use strings instead of constants. However, some of these
522 constants are redefined to use cached strings which may reduce
523 your binary size by some amount.
528 /** Set default value for property.
530 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
532 /** Universal, int or double. Minimum value for numeric properties.
534 #define wxPG_ATTR_MIN wxS("Min")
536 /** Universal, int or double. Maximum value for numeric properties.
538 #define wxPG_ATTR_MAX wxS("Max")
540 /** Universal, string. When set, will be shown as text after the displayed
541 text value. Alternatively, if third column is enabled, text will be shown
542 there (for any type of property).
544 #define wxPG_ATTR_UNITS wxS("Units")
546 /** When set, will be shown as 'greyed' text in property's value cell when
547 the actual displayed value is blank.
549 #define wxPG_ATTR_HINT wxS("Hint")
551 #if wxPG_COMPATIBILITY_1_4
553 @deprecated Use "Hint" (wxPG_ATTR_HINT) instead.
555 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
558 /** Universal, wxArrayString. Set to enable auto-completion in any
559 wxTextCtrl-based property editor.
561 #define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
563 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
564 Default value is False.
566 When set to True, bool property will use check box instead of a
567 combo box as its editor control. If you set this attribute
568 for a wxFlagsProperty, it is automatically applied to child
571 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
573 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
574 Default value is False.
576 Set to True for the bool property to cycle value on double click
577 (instead of showing the popup listbox). If you set this attribute
578 for a wxFlagsProperty, it is automatically applied to child
581 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
584 wxFloatProperty (and similar) specific, int, default -1.
586 Sets the (max) precision used when floating point value is rendered as
587 text. The default -1 means infinite precision.
589 #define wxPG_FLOAT_PRECISION wxS("Precision")
592 The text will be echoed as asterisks (wxTE_PASSWORD will be passed to
595 #define wxPG_STRING_PASSWORD wxS("Password")
597 /** Define base used by a wxUIntProperty. Valid constants are
598 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
599 (lowercase characters).
601 #define wxPG_UINT_BASE wxS("Base")
603 /** Define prefix rendered to wxUIntProperty. Accepted constants
604 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
605 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
608 #define wxPG_UINT_PREFIX wxS("Prefix")
611 wxFileProperty/wxImageFileProperty specific, wxChar*, default is
613 Sets the wildcard used in the triggered wxFileDialog. Format is the same.
615 #define wxPG_FILE_WILDCARD wxS("Wildcard")
617 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
618 When 0, only the file name is shown (i.e. drive and directory are hidden).
620 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
622 /** Specific to wxFileProperty and derived properties, wxString, default empty.
623 If set, then the filename is shown relative to the given path string.
625 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
628 Specific to wxFileProperty and derived properties, wxString, default is
631 Sets the initial path of where to look for files.
633 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
635 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
636 Sets a specific title for the dir dialog.
638 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
640 /** Specific to wxDirProperty, wxString, default is empty.
641 Sets a specific message for the dir dialog.
643 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
645 /** Sets displayed date format for wxDateProperty.
647 #define wxPG_DATE_FORMAT wxS("DateFormat")
649 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
650 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
652 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
654 /** SpinCtrl editor, int or double. How much number changes when button is
655 pressed (or up/down on keybard).
657 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
659 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
661 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
664 wxMultiChoiceProperty, int.
665 If 0, no user strings allowed. If 1, user strings appear before list
666 strings. If 2, user strings appear after list string.
668 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
671 wxColourProperty and its kind, int, default 1.
673 Setting this attribute to 0 hides custom colour from property's list of
676 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
681 // Redefine attribute macros to use cached strings
682 #undef wxPG_ATTR_DEFAULT_VALUE
683 #define wxPG_ATTR_DEFAULT_VALUE wxPGGlobalVars->m_strDefaultValue
685 #define wxPG_ATTR_MIN wxPGGlobalVars->m_strMin
687 #define wxPG_ATTR_MAX wxPGGlobalVars->m_strMax
688 #undef wxPG_ATTR_UNITS
689 #define wxPG_ATTR_UNITS wxPGGlobalVars->m_strUnits
690 #undef wxPG_ATTR_HINT
691 #define wxPG_ATTR_HINT wxPGGlobalVars->m_strHint
692 #if wxPG_COMPATIBILITY_1_4
693 #undef wxPG_ATTR_INLINE_HELP
694 #define wxPG_ATTR_INLINE_HELP wxPGGlobalVars->m_strInlineHelp
697 // -----------------------------------------------------------------------
699 /** @class wxPGChoiceEntry
700 Data of a single wxPGChoices choice.
702 class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry
: public wxPGCell
706 wxPGChoiceEntry(const wxPGChoiceEntry
& other
)
709 m_value
= other
.m_value
;
711 wxPGChoiceEntry( const wxString
& label
,
712 int value
= wxPG_INVALID_VALUE
)
713 : wxPGCell(), m_value(value
)
718 virtual ~wxPGChoiceEntry() { }
720 void SetValue( int value
) { m_value
= value
; }
721 int GetValue() const { return m_value
; }
723 wxPGChoiceEntry
& operator=( const wxPGChoiceEntry
& other
)
725 if ( this != &other
)
729 m_value
= other
.m_value
;
738 typedef void* wxPGChoicesId
;
740 class WXDLLIMPEXP_PROPGRID wxPGChoicesData
: public wxObjectRefData
742 friend class wxPGChoices
;
744 // Constructor sets m_refCount to 1.
747 void CopyDataFrom( wxPGChoicesData
* data
);
749 wxPGChoiceEntry
& Insert( int index
, const wxPGChoiceEntry
& item
);
751 // Delete all entries
754 unsigned int GetCount() const
756 return (unsigned int) m_items
.size();
759 const wxPGChoiceEntry
& Item( unsigned int i
) const
761 wxASSERT_MSG( i
< GetCount(), "invalid index" );
765 wxPGChoiceEntry
& Item( unsigned int i
)
767 wxASSERT_MSG( i
< GetCount(), "invalid index" );
772 wxVector
<wxPGChoiceEntry
> m_items
;
774 virtual ~wxPGChoicesData();
777 #define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL)
780 /** @class wxPGChoices
782 Helper class for managing choices of wxPropertyGrid properties.
783 Each entry can have label, value, bitmap, text colour, and background
786 wxPGChoices uses reference counting, similar to other wxWidgets classes.
787 This means that assignment operator and copy constructor only copy the
788 reference and not the actual data. Use Copy() member function to create a
791 @remarks If you do not specify value for entry, index is used.
796 class WXDLLIMPEXP_PROPGRID wxPGChoices
799 typedef long ValArrItem
;
801 /** Default constructor. */
808 Copy constructor, uses reference counting. To create a real copy,
809 use Copy() member function instead.
811 wxPGChoices( const wxPGChoices
& a
)
813 if ( a
.m_data
!= wxPGChoicesEmptyData
)
827 Values for choices. If NULL, indexes are used.
829 wxPGChoices( const wxChar
* const* labels
, const long* values
= NULL
)
842 Values for choices. If empty, indexes are used.
844 wxPGChoices( const wxArrayString
& labels
,
845 const wxArrayInt
& values
= wxArrayInt() )
851 /** Simple interface constructor. */
852 wxPGChoices( wxPGChoicesData
* data
)
868 If did not have own copies, creates them now. If was empty, identical
869 to set except that creates copies.
872 Labels for added choices.
875 Values for added choices. If empty, relevant entry indexes are used.
877 void Add( const wxChar
* const* labels
, const ValArrItem
* values
= NULL
);
879 /** Version that works with wxArrayString and wxArrayInt. */
880 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
= wxArrayInt() );
883 Adds a single choice.
886 Label for added choice.
889 Value for added choice. If unspecified, index is used.
891 wxPGChoiceEntry
& Add( const wxString
& label
,
892 int value
= wxPG_INVALID_VALUE
);
894 /** Adds a single item, with bitmap. */
895 wxPGChoiceEntry
& Add( const wxString
& label
,
896 const wxBitmap
& bitmap
,
897 int value
= wxPG_INVALID_VALUE
);
899 /** Adds a single item with full entry information. */
900 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
902 return Insert(entry
, -1);
905 /** Adds single item. */
906 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
,
907 int value
= wxPG_INVALID_VALUE
);
910 Assigns choices data, using reference counting. To create a real copy,
911 use Copy() member function instead.
913 void Assign( const wxPGChoices
& a
)
915 AssignData(a
.m_data
);
918 void AssignData( wxPGChoicesData
* data
);
920 /** Delete all choices. */
924 Returns a real copy of the choices.
926 wxPGChoices
Copy() const
930 dst
.m_data
->CopyDataFrom(m_data
);
936 if ( m_data
== wxPGChoicesEmptyData
)
937 m_data
= new wxPGChoicesData();
940 /** Gets a unsigned number identifying this list. */
941 wxPGChoicesId
GetId() const { return (wxPGChoicesId
) m_data
; };
943 const wxString
& GetLabel( unsigned int ind
) const
945 return Item(ind
).GetText();
948 unsigned int GetCount () const
953 return m_data
->GetCount();
956 int GetValue( unsigned int ind
) const { return Item(ind
).GetValue(); }
958 /** Returns array of values matching the given strings. Unmatching strings
959 result in wxPG_INVALID_VALUE entry in array.
961 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
963 /** Returns array of indices matching given strings. Unmatching strings
964 are added to 'unmatched', if not NULL.
966 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
967 wxArrayString
* unmatched
= NULL
) const;
969 int Index( const wxString
& str
) const;
970 int Index( int val
) const;
972 /** Inserts single item. */
973 wxPGChoiceEntry
& Insert( const wxString
& label
,
975 int value
= wxPG_INVALID_VALUE
);
977 /** Inserts a single item with full entry information. */
978 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
980 /** Returns false if this is a constant empty set of choices,
981 which should not be modified.
985 return ( m_data
!= wxPGChoicesEmptyData
);
988 const wxPGChoiceEntry
& Item( unsigned int i
) const
991 return m_data
->Item(i
);
994 wxPGChoiceEntry
& Item( unsigned int i
)
997 return m_data
->Item(i
);
1000 /** Removes count items starting at position nIndex. */
1001 void RemoveAt(size_t nIndex
, size_t count
= 1);
1003 /** Does not create copies for itself.
1006 void Set( const wxChar
* const* labels
, const long* values
= NULL
)
1012 /** Version that works with wxArrayString and wxArrayInt. */
1013 void Set( const wxArrayString
& labels
,
1014 const wxArrayInt
& values
= wxArrayInt() )
1023 // Creates exclusive copy of current choices
1024 void AllocExclusive();
1026 // Returns data, increases refcount.
1027 wxPGChoicesData
* GetData()
1029 wxASSERT( m_data
->GetRefCount() != -1 );
1034 // Returns plain data ptr - no refcounting stuff is done.
1035 wxPGChoicesData
* GetDataPtr() const { return m_data
; }
1037 // Changes ownership of data to you.
1038 wxPGChoicesData
* ExtractData()
1040 wxPGChoicesData
* data
= m_data
;
1041 m_data
= wxPGChoicesEmptyData
;
1045 wxArrayString
GetLabels() const;
1047 void operator= (const wxPGChoices
& a
)
1050 AssignData(a
.m_data
);
1053 wxPGChoiceEntry
& operator[](unsigned int i
)
1058 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1064 wxPGChoicesData
* m_data
;
1070 // -----------------------------------------------------------------------
1072 /** @class wxPGProperty
1074 wxPGProperty is base class for all wxPropertyGrid properties.
1076 NB: Full class overview is now only present in
1077 interface/wx/propgrid/property.h.
1079 @library{wxpropgrid}
1082 class WXDLLIMPEXP_PROPGRID wxPGProperty
: public wxObject
1084 friend class wxPropertyGrid
;
1085 friend class wxPropertyGridInterface
;
1086 friend class wxPropertyGridPageState
;
1087 friend class wxPropertyGridPopulator
;
1088 friend class wxStringProperty
; // Proper "<composed>" support requires this
1090 DECLARE_ABSTRACT_CLASS(wxPGProperty
)
1092 typedef wxUint32 FlagType
;
1095 Default constructor.
1102 All non-abstract property classes should have a constructor with
1103 the same first two arguments as this one.
1105 wxPGProperty( const wxString
& label
, const wxString
& name
);
1109 It is customary for derived properties to implement this.
1111 virtual ~wxPGProperty();
1113 /** This virtual function is called after m_value has been set.
1116 - If m_value was set to Null variant (ie. unspecified value),
1117 OnSetValue() will not be called.
1118 - m_value may be of any variant type. Typically properties internally
1119 support only one variant type, and as such OnSetValue() provides a
1120 good opportunity to convert
1121 supported values into internal type.
1122 - Default implementation does nothing.
1124 virtual void OnSetValue();
1126 /** Override this to return something else than m_value as the value.
1128 virtual wxVariant
DoGetValue() const { return m_value
; }
1130 /** Implement this function in derived class to check the value.
1131 Return true if it is ok. Returning false prevents property change events
1135 - Default implementation always returns true.
1137 virtual bool ValidateValue( wxVariant
& value
,
1138 wxPGValidationInfo
& validationInfo
) const;
1141 Converts text into wxVariant value appropriate for this property.
1144 On function entry this is the old value (should not be wxNullVariant
1145 in normal cases). Translated value must be assigned back to it.
1148 Text to be translated into variant.
1151 If wxPG_FULL_VALUE is set, returns complete, storable value instead
1152 of displayable one (they may be different).
1153 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
1154 composite property string value (as generated by ValueToString()
1155 called with this same flag).
1157 @return Returns @true if resulting wxVariant value was different.
1159 @remarks Default implementation converts semicolon delimited tokens into
1160 child values. Only works for properties with children.
1162 You might want to take into account that m_value is Null variant
1163 if property value is unspecified (which is usually only case if
1164 you explicitly enabled that sort behavior).
1166 virtual bool StringToValue( wxVariant
& variant
,
1167 const wxString
& text
,
1168 int argFlags
= 0 ) const;
1171 Converts integer (possibly a choice selection) into wxVariant value
1172 appropriate for this property.
1175 On function entry this is the old value (should not be wxNullVariant
1176 in normal cases). Translated value must be assigned back to it.
1179 Integer to be translated into variant.
1182 If wxPG_FULL_VALUE is set, returns complete, storable value instead
1185 @return Returns @true if resulting wxVariant value was different.
1188 - If property is not supposed to use choice or spinctrl or other editor
1189 with int-based value, it is not necessary to implement this method.
1190 - Default implementation simply assign given int to m_value.
1191 - If property uses choice control, and displays a dialog on some choice
1192 items, then it is preferred to display that dialog in IntToValue
1194 - You might want to take into account that m_value is Null variant if
1195 property value is unspecified (which is usually only case if you
1196 explicitly enabled that sort behavior).
1198 virtual bool IntToValue( wxVariant
& value
,
1200 int argFlags
= 0 ) const;
1203 Converts property value into a text representation.
1206 Value to be converted.
1209 If 0 (default value), then displayed string is returned.
1210 If wxPG_FULL_VALUE is set, returns complete, storable string value
1211 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1212 string value that must be editable in textctrl. If
1213 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1214 display as a part of string property's composite text
1217 @remarks Default implementation calls GenerateComposedValue().
1219 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
= 0 ) const;
1221 /** Converts string to a value, and if successful, calls SetValue() on it.
1222 Default behavior is to do nothing.
1224 String to get the value from.
1226 true if value was changed.
1228 bool SetValueFromString( const wxString
& text
, int flags
= wxPG_PROGRAMMATIC_VALUE
);
1230 /** Converts integer to a value, and if succesful, calls SetValue() on it.
1231 Default behavior is to do nothing.
1233 Int to get the value from.
1235 If has wxPG_FULL_VALUE, then the value given is a actual value and
1238 True if value was changed.
1240 bool SetValueFromInt( long value
, int flags
= 0 );
1243 Returns size of the custom painted image in front of property.
1245 This method must be overridden to return non-default value if
1246 OnCustomPaint is to be called.
1248 Normally -1, but can be an index to the property's list of items.
1250 - Default behavior is to return wxSize(0,0), which means no image.
1251 - Default image width or height is indicated with dimension -1.
1252 - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1).
1254 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
1257 Events received by editor widgets are processed here.
1259 Note that editor class usually processes most events. Some, such as
1260 button press events of TextCtrlAndButton class, can be handled here.
1261 Also, if custom handling for regular events is desired, then that can
1262 also be done (for example, wxSystemColourProperty custom handles
1263 wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
1264 'custom' selection is made).
1266 If the event causes value to be changed, SetValueInEvent()
1267 should be called to set the new value.
1272 Should return true if any changes in value should be reported.
1274 If property uses choice control, and displays a dialog on some choice
1275 items, then it is preferred to display that dialog in IntToValue
1278 virtual bool OnEvent( wxPropertyGrid
* propgrid
,
1279 wxWindow
* wnd_primary
,
1283 Called after value of a child property has been altered. Must return
1284 new value of the whole property (after any alterations warrented by
1287 Note that this function is usually called at the time that value of
1288 this property, or given child property, is still pending for change,
1289 and as such, result of GetValue() or m_value should not be relied
1292 Sample pseudo-code implementation:
1295 wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
1297 wxVariant& childValue ) const
1299 // Acquire reference to actual type of data stored in variant
1300 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
1301 // were used to create the variant class).
1302 T& data = TFromVariant(thisValue);
1304 // Copy childValue into data.
1305 switch ( childIndex )
1308 data.SetSubProp1( childvalue.GetLong() );
1311 data.SetSubProp2( childvalue.GetString() );
1316 // Return altered data
1322 Value of this property. Changed value should be returned (in
1323 previous versions of wxPropertyGrid it was only necessary to
1324 write value back to this argument).
1326 Index of child changed (you can use Item(childIndex) to get
1329 (Pending) value of the child property.
1332 Modified value of the whole property.
1334 virtual wxVariant
ChildChanged( wxVariant
& thisValue
,
1336 wxVariant
& childValue
) const;
1338 /** Returns pointer to an instance of used editor.
1340 virtual const wxPGEditor
* DoGetEditorClass() const;
1342 /** Returns pointer to the wxValidator that should be used
1343 with the editor of this property (NULL for no validator).
1344 Setting validator explicitly via SetPropertyValidator
1347 In most situations, code like this should work well
1348 (macros are used to maintain one actual validator instance,
1349 so on the second call the function exits within the first
1354 wxValidator* wxMyPropertyClass::DoGetValidator () const
1356 WX_PG_DOGETVALIDATOR_ENTRY()
1358 wxMyValidator* validator = new wxMyValidator(...);
1360 ... prepare validator...
1362 WX_PG_DOGETVALIDATOR_EXIT(validator)
1368 You can get common filename validator by returning
1369 wxFileProperty::GetClassValidator(). wxDirProperty,
1370 for example, uses it.
1372 virtual wxValidator
* DoGetValidator () const;
1375 Override to paint an image in front of the property value text or
1376 drop-down list item (but only if wxPGProperty::OnMeasureImage is
1377 overridden as well).
1379 If property's OnMeasureImage() returns size that has height != 0 but
1380 less than row height ( < 0 has special meanings), wxPropertyGrid calls
1381 this method to draw a custom image in a limited area in front of the
1382 editor control or value text/graphics, and if control has drop-down
1383 list, then the image is drawn there as well (even in the case
1384 OnMeasureImage() returned higher height than row height).
1386 NOTE: Following applies when OnMeasureImage() returns a "flexible"
1387 height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
1388 height items: If rect.x is < 0, then this is a measure item call, which
1389 means that dc is invalid and only thing that should be done is to set
1390 paintdata.m_drawnHeight to the height of the image of item at index
1391 paintdata.m_choiceItem. This call may be done even as often as once
1392 every drop-down popup show.
1397 Box reserved for custom graphics. Includes surrounding rectangle,
1398 if any. If x is < 0, then this is a measure item call (see above).
1400 wxPGPaintData structure with much useful data.
1403 - You can actually exceed rect width, but if you do so then
1404 paintdata.m_drawnWidth must be set to the full width drawn in
1406 - Due to technical reasons, rect's height will be default even if
1407 custom height was reported during measure call.
1408 - Brush is guaranteed to be default background colour. It has been
1409 already used to clear the background of area being painted. It
1411 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper
1412 colour) pen for drawing framing rectangle. It can be changed as
1415 @see ValueToString()
1417 virtual void OnCustomPaint( wxDC
& dc
,
1419 wxPGPaintData
& paintdata
);
1422 Returns used wxPGCellRenderer instance for given property column
1425 Default implementation returns editor's renderer for all columns.
1427 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
1429 /** Returns which choice is currently selected. Only applies to properties
1432 Needs to reimplemented in derived class if property value does not
1433 map directly to a choice. Integer as index, bool, and string usually do.
1435 virtual int GetChoiceSelection() const;
1438 Refresh values of child properties.
1440 Automatically called after value is set.
1442 virtual void RefreshChildren();
1445 Reimplement this member function to add special handling for
1446 attributes of this property.
1448 @return Return @false to have the attribute automatically stored in
1449 m_attributes. Default implementation simply does that and
1452 @remarks To actually set property attribute values from the
1453 application, use wxPGProperty::SetAttribute() instead.
1455 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
1457 /** Returns value of an attribute.
1459 Override if custom handling of attributes is needed.
1461 Default implementation simply return NULL variant.
1463 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
1465 /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
1466 used when user presses the (optional) button next to the editor control;
1468 Default implementation returns NULL (ie. no action is generated when
1471 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
1474 Called whenever validation has failed with given pending value.
1476 @remarks If you implement this in your custom property class, please
1477 remember to call the baser implementation as well, since they
1478 may use it to revert property into pre-change state.
1480 virtual void OnValidationFailure( wxVariant
& pendingValue
);
1482 /** Append a new choice to property's list of choices.
1484 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
)
1486 return InsertChoice(label
, wxNOT_FOUND
, value
);
1490 Returns true if children of this property are component values (for
1491 instance, points size, face name, and is_underlined are component
1494 bool AreChildrenComponents() const
1496 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
1503 Deletes children of the property.
1505 void DeleteChildren();
1508 Removes entry from property's wxPGChoices and editor control (if it is
1511 If selected item is deleted, then the value is set to unspecified.
1513 void DeleteChoice( int index
);
1516 Call to enable or disable usage of common value (integer value that can
1517 be selected for properties instead of their normal values) for this
1520 Common values are disabled by the default for all properties.
1522 void EnableCommonValue( bool enable
= true )
1524 if ( enable
) SetFlag( wxPG_PROP_USES_COMMON_VALUE
);
1525 else ClearFlag( wxPG_PROP_USES_COMMON_VALUE
);
1529 Composes text from values of child properties.
1531 wxString
GenerateComposedValue() const
1534 DoGenerateComposedValue(s
);
1538 /** Returns property's label. */
1539 const wxString
& GetLabel() const { return m_label
; }
1541 /** Returns property's name with all (non-category, non-root) parents. */
1542 wxString
GetName() const;
1545 Returns property's base name (ie parent's name is not added in any
1548 const wxString
& GetBaseName() const { return m_name
; }
1550 /** Returns read-only reference to property's list of choices.
1552 const wxPGChoices
& GetChoices() const
1557 /** Returns coordinate to the top y of the property. Note that the
1558 position of scrollbars is not taken into account.
1562 wxVariant
GetValue() const
1564 return DoGetValue();
1567 /** Returns reference to the internal stored value. GetValue is preferred
1568 way to get the actual value, since GetValueRef ignores DoGetValue,
1569 which may override stored value.
1571 wxVariant
& GetValueRef()
1576 const wxVariant
& GetValueRef() const
1581 // Helper function (for wxPython bindings and such) for settings protected
1583 wxVariant
GetValuePlain() const
1588 /** Returns text representation of property's value.
1591 If 0 (default value), then displayed string is returned.
1592 If wxPG_FULL_VALUE is set, returns complete, storable string value
1593 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1594 string value that must be editable in textctrl. If
1595 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1596 display as a part of string property's composite text
1599 @remarks In older versions, this function used to be overridden to convert
1600 property's value into a string representation. This function is
1601 now handled by ValueToString(), and overriding this function now
1602 will result in run-time assertion failure.
1604 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
1606 /** Synonymous to GetValueAsString().
1608 @deprecated Use GetValueAsString() instead.
1610 @see GetValueAsString()
1612 wxDEPRECATED( wxString
GetValueString( int argFlags
= 0 ) const );
1615 Returns wxPGCell of given column.
1617 @remarks const version of this member function returns 'default'
1618 wxPGCell object if the property itself didn't hold
1621 const wxPGCell
& GetCell( unsigned int column
) const;
1624 Returns wxPGCell of given column, creating one if necessary.
1626 wxPGCell
& GetCell( unsigned int column
)
1628 return GetOrCreateCell(column
);
1632 Returns wxPGCell of given column, creating one if necessary.
1634 wxPGCell
& GetOrCreateCell( unsigned int column
);
1636 /** Return number of displayed common values for this property.
1638 int GetDisplayedCommonValueCount() const;
1640 wxString
GetDisplayedString() const
1642 return GetValueAsString(0);
1646 Returns property's hint text (shown in empty value cell).
1648 inline wxString
GetHintText() const;
1650 /** Returns property grid where property lies. */
1651 wxPropertyGrid
* GetGrid() const;
1653 /** Returns owner wxPropertyGrid, but only if one is currently on a page
1654 displaying this property. */
1655 wxPropertyGrid
* GetGridIfDisplayed() const;
1657 /** Returns highest level non-category, non-root parent. Useful when you
1658 have nested wxCustomProperties/wxParentProperties.
1660 Thus, if immediate parent is root or category, this will return the
1663 wxPGProperty
* GetMainParent() const;
1665 /** Return parent of property */
1666 wxPGProperty
* GetParent() const { return m_parent
; }
1668 /** Returns true if property has editable wxTextCtrl when selected.
1671 Altough disabled properties do not displayed editor, they still
1672 return True here as being disabled is considered a temporary
1673 condition (unlike being read-only or having limited editing enabled).
1675 bool IsTextEditable() const;
1677 bool IsValueUnspecified() const
1679 return m_value
.IsNull();
1682 FlagType
HasFlag( FlagType flag
) const
1684 return ( m_flags
& flag
);
1687 /** Returns comma-delimited string of property attributes.
1689 const wxPGAttributeStorage
& GetAttributes() const
1691 return m_attributes
;
1694 /** Returns m_attributes as list wxVariant.
1696 wxVariant
GetAttributesAsList() const;
1698 FlagType
GetFlags() const
1703 const wxPGEditor
* GetEditorClass() const;
1705 wxString
GetValueType() const
1707 return m_value
.GetType();
1710 /** Returns editor used for given column. NULL for no editor.
1712 const wxPGEditor
* GetColumnEditor( int column
) const
1715 return GetEditorClass();
1720 /** Returns common value selected for this property. -1 for none.
1722 int GetCommonValue() const
1724 return m_commonValue
;
1727 /** Returns true if property has even one visible child.
1729 bool HasVisibleChildren() const;
1732 Use this member function to add independent (ie. regular) children to
1735 @return Inserted childProperty.
1737 @remarks wxPropertyGrid is not automatically refreshed by this
1740 @see AddPrivateChild()
1742 wxPGProperty
* InsertChild( int index
, wxPGProperty
* childProperty
);
1744 /** Inserts a new choice to property's list of choices.
1746 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1749 Returns true if this property is actually a wxPropertyCategory.
1751 bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY
)?true:false; }
1753 /** Returns true if this property is actually a wxRootProperty.
1755 bool IsRoot() const { return (m_parent
== NULL
); }
1757 /** Returns true if this is a sub-property. */
1758 bool IsSubProperty() const
1760 wxPGProperty
* parent
= (wxPGProperty
*)m_parent
;
1761 if ( parent
&& !parent
->IsCategory() )
1766 /** Returns last visible sub-property, recursively.
1768 const wxPGProperty
* GetLastVisibleSubItem() const;
1770 wxVariant
GetDefaultValue() const;
1772 int GetMaxLength() const
1774 return (int) m_maxLen
;
1778 Determines, recursively, if all children are not unspecified.
1781 Assumes members in this wxVariant list as pending
1784 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
1786 /** Updates composed values of parent non-category properties, recursively.
1787 Returns topmost property updated.
1790 - Must not call SetValue() (as can be called in it).
1792 wxPGProperty
* UpdateParentValues();
1794 /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1796 bool UsesAutoUnspecified() const
1798 return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED
)?true:false;
1801 wxBitmap
* GetValueImage() const
1803 return m_valueBitmap
;
1806 wxVariant
GetAttribute( const wxString
& name
) const;
1809 Returns named attribute, as string, if found.
1811 Otherwise defVal is returned.
1813 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1816 Returns named attribute, as long, if found.
1818 Otherwise defVal is returned.
1820 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1823 Returns named attribute, as double, if found.
1825 Otherwise defVal is returned.
1827 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1829 unsigned int GetDepth() const { return (unsigned int)m_depth
; }
1831 /** Gets flags as a'|' delimited string. Note that flag names are not
1832 prepended with 'wxPG_PROP_'.
1834 String will only be made to include flags combined by this parameter.
1836 wxString
GetFlagsAsString( FlagType flagsMask
) const;
1838 /** Returns position in parent's array. */
1839 unsigned int GetIndexInParent() const
1841 return (unsigned int)m_arrIndex
;
1844 /** Hides or reveals the property.
1846 true for hide, false for reveal.
1848 By default changes are applied recursively. Set this paramter
1849 wxPG_DONT_RECURSE to prevent this.
1851 inline bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1853 bool IsExpanded() const
1854 { return (!(m_flags
& wxPG_PROP_COLLAPSED
) && GetChildCount()); }
1856 /** Returns true if all parents expanded.
1858 bool IsVisible() const;
1860 bool IsEnabled() const { return !(m_flags
& wxPG_PROP_DISABLED
); }
1862 /** If property's editor is created this forces its recreation.
1863 Useful in SetAttribute etc. Returns true if actually did anything.
1865 bool RecreateEditor();
1867 /** If property's editor is active, then update it's value.
1869 void RefreshEditor();
1871 /** Sets an attribute for this property.
1873 Text identifier of attribute. See @ref propgrid_property_attributes.
1877 void SetAttribute( const wxString
& name
, wxVariant value
);
1879 void SetAttributes( const wxPGAttributeStorage
& attributes
);
1882 Sets property's background colour.
1885 Background colour to use.
1888 Default is wxPG_RECURSE which causes colour to be set recursively.
1889 Omit this flag to only set colour for the property in question
1890 and not any of its children.
1892 void SetBackgroundColour( const wxColour
& colour
,
1893 int flags
= wxPG_RECURSE
);
1896 Sets property's text colour.
1902 Default is wxPG_RECURSE which causes colour to be set recursively.
1903 Omit this flag to only set colour for the property in question
1904 and not any of its children.
1906 void SetTextColour( const wxColour
& colour
,
1907 int flags
= wxPG_RECURSE
);
1909 /** Set default value of a property. Synonymous to
1912 SetAttribute("DefaultValue", value);
1915 void SetDefaultValue( wxVariant
& value
);
1917 /** Sets editor for a property.
1920 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1921 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
1924 For custom editors, use pointer you received from
1925 wxPropertyGrid::RegisterEditorClass().
1927 void SetEditor( const wxPGEditor
* editor
)
1929 m_customEditor
= editor
;
1932 /** Sets editor for a property.
1934 inline void SetEditor( const wxString
& editorName
);
1937 Sets cell information for given column.
1939 void SetCell( int column
, const wxPGCell
& cell
);
1941 /** Sets common value selected for this property. -1 for none.
1943 void SetCommonValue( int commonValue
)
1945 m_commonValue
= commonValue
;
1948 /** Sets flags from a '|' delimited string. Note that flag names are not
1949 prepended with 'wxPG_PROP_'.
1951 void SetFlagsFromString( const wxString
& str
);
1953 /** Sets property's "is it modified?" flag. Affects children recursively.
1955 void SetModifiedStatus( bool modified
)
1957 SetFlagRecursively(wxPG_PROP_MODIFIED
, modified
);
1960 /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1961 based on user input.
1964 This method is const since it doesn't actually modify value, but posts
1965 given variant as pending value, stored in wxPropertyGrid.
1967 void SetValueInEvent( wxVariant value
) const;
1970 Call this to set value of the property.
1972 Unlike methods in wxPropertyGrid, this does not automatically update
1976 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
1977 through validation process and send property change event.
1979 If you need to change property value in event, based on user input, use
1980 SetValueInEvent() instead.
1983 Pointer to list variant that contains child values. Used to
1984 indicate which children should be marked as modified.
1987 Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR, which is
1988 enabled by default).
1990 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
,
1991 int flags
= wxPG_SETVAL_REFRESH_EDITOR
);
1993 /** Set wxBitmap in front of the value. This bitmap may be ignored
1994 by custom cell renderers.
1996 void SetValueImage( wxBitmap
& bmp
);
1998 /** Sets selected choice and changes property value.
2000 Tries to retain value type, although currently if it is not string,
2001 then it is forced to integer.
2003 void SetChoiceSelection( int newValue
);
2005 void SetExpanded( bool expanded
)
2007 if ( !expanded
) m_flags
|= wxPG_PROP_COLLAPSED
;
2008 else m_flags
&= ~wxPG_PROP_COLLAPSED
;
2012 Sets given property flag(s).
2014 void SetFlag( FlagType flag
) { m_flags
|= flag
; }
2017 Sets or clears given property flag(s).
2019 void ChangeFlag( FlagType flag
, bool set
)
2027 void SetFlagRecursively( FlagType flag
, bool set
);
2029 void SetHelpString( const wxString
& helpString
)
2031 m_helpString
= helpString
;
2034 void SetLabel( const wxString
& label
) { m_label
= label
; }
2036 void SetName( const wxString
& newName
);
2039 Changes what sort of parent this property is for its children.
2042 Use one of the following values: wxPG_PROP_MISC_PARENT (for
2043 generic parents), wxPG_PROP_CATEGORY (for categories), or
2044 wxPG_PROP_AGGREGATE (for derived property classes with private
2047 @remarks You generally do not need to call this function.
2049 void SetParentalType( int flag
)
2051 m_flags
&= ~(wxPG_PROP_PROPERTY
|wxPG_PROP_PARENTAL_FLAGS
);
2055 void SetValueToUnspecified()
2057 wxVariant val
; // Create NULL variant
2058 SetValue(val
, NULL
, wxPG_SETVAL_REFRESH_EDITOR
);
2061 // Helper function (for wxPython bindings and such) for settings protected
2063 void SetValuePlain( wxVariant value
)
2068 #if wxUSE_VALIDATORS
2069 /** Sets wxValidator for a property*/
2070 void SetValidator( const wxValidator
& validator
)
2072 m_validator
= wxDynamicCast(validator
.Clone(),wxValidator
);
2075 /** Gets assignable version of property's validator. */
2076 wxValidator
* GetValidator() const
2080 return DoGetValidator();
2082 #endif // wxUSE_VALIDATORS
2084 /** Returns client data (void*) of a property.
2086 void* GetClientData() const
2088 return m_clientData
;
2091 /** Sets client data (void*) of a property.
2093 This untyped client data has to be deleted manually.
2095 void SetClientData( void* clientData
)
2097 m_clientData
= clientData
;
2100 /** Returns client object of a property.
2102 void SetClientObject(wxClientData
* clientObject
)
2104 delete m_clientObject
;
2105 m_clientObject
= clientObject
;
2108 /** Sets managed client object of a property.
2110 wxClientData
*GetClientObject() const { return m_clientObject
; }
2113 Sets new set of choices for the property.
2115 @remarks This operation deselects the property and clears its
2118 bool SetChoices( wxPGChoices
& choices
);
2120 /** Set max length of text in text editor.
2122 inline bool SetMaxLength( int maxLen
);
2124 /** Call with 'false' in OnSetValue to cancel value changes after all
2125 (ie. cancel 'true' returned by StringToValue() or IntToValue()).
2127 void SetWasModified( bool set
= true )
2129 if ( set
) m_flags
|= wxPG_PROP_WAS_MODIFIED
;
2130 else m_flags
&= ~wxPG_PROP_WAS_MODIFIED
;
2133 const wxString
& GetHelpString() const
2135 return m_helpString
;
2138 void ClearFlag( FlagType flag
) { m_flags
&= ~(flag
); }
2140 // Use, for example, to detect if item is inside collapsed section.
2141 bool IsSomeParent( wxPGProperty
* candidate_parent
) const;
2144 Adapts list variant into proper value using consecutive
2147 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
2149 #if wxPG_COMPATIBILITY_1_4
2151 Adds a private child property.
2153 @deprecated Use AddPrivateChild() instead.
2155 @see AddPrivateChild()
2157 wxDEPRECATED( void AddChild( wxPGProperty
* prop
) );
2161 Adds a private child property. If you use this instead of
2162 wxPropertyGridInterface::Insert() or
2163 wxPropertyGridInterface::AppendIn(), then property's parental
2164 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
2165 words, all properties of this property will become private.
2167 void AddPrivateChild( wxPGProperty
* prop
);
2170 Appends a new child property.
2172 wxPGProperty
* AppendChild( wxPGProperty
* prop
)
2174 return InsertChild(-1, prop
);
2177 /** Returns height of children, recursively, and
2178 by taking expanded/collapsed status into account.
2180 iMax is used when finding property y-positions.
2182 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
2184 /** Returns number of child properties */
2185 unsigned int GetChildCount() const
2187 return (unsigned int) m_children
.size();
2190 /** Returns sub-property at index i. */
2191 wxPGProperty
* Item( unsigned int i
) const
2192 { return m_children
[i
]; }
2194 /** Returns last sub-property.
2196 wxPGProperty
* Last() const { return m_children
.back(); }
2198 /** Returns index of given child property. */
2199 int Index( const wxPGProperty
* p
) const;
2201 // Puts correct indexes to children
2202 void FixIndicesOfChildren( unsigned int starthere
= 0 );
2205 Converts image width into full image offset, with margins.
2207 int GetImageOffset( int imageWidth
) const;
2209 // Returns wxPropertyGridPageState in which this property resides.
2210 wxPropertyGridPageState
* GetParentState() const { return m_parentState
; }
2212 wxPGProperty
* GetItemAtY( unsigned int y
,
2214 unsigned int* nextItemY
) const;
2216 /** Returns property at given virtual y coordinate.
2218 wxPGProperty
* GetItemAtY( unsigned int y
) const;
2220 /** Returns (direct) child property with given name (or NULL if not found).
2222 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
2224 // Returns various display-related information for given column
2225 void GetDisplayInfo( unsigned int column
,
2229 const wxPGCell
** pCell
);
2231 static wxString
* sm_wxPG_LABEL
;
2233 /** This member is public so scripting language bindings
2234 wrapper code can access it freely.
2241 Sets property cell in fashion that reduces number of exclusive
2242 copies of cell data. Used when setting, for instance, same
2243 background colour for a number of properties.
2246 First column to affect.
2249 Last column to affect.
2252 Pre-prepared cell that is used for those which cell data
2253 before this matched unmodCellData.
2256 If unmodCellData did not match, valid cell data from this
2257 is merged into cell (usually generating new exclusive copy
2260 @param unmodCellData
2261 If cell's cell data matches this, its cell is now set to
2264 @param ignoreWithFlags
2265 Properties with any one of these flags are skipped.
2268 If @true, apply this operation recursively in child properties.
2270 void AdaptiveSetCell( unsigned int firstCol
,
2271 unsigned int lastCol
,
2272 const wxPGCell
& preparedCell
,
2273 const wxPGCell
& srcData
,
2274 wxPGCellData
* unmodCellData
,
2275 FlagType ignoreWithFlags
,
2279 Makes sure m_cells has size of column+1 (or more).
2281 void EnsureCells( unsigned int column
);
2283 /** Returns (direct) child property with given name (or NULL if not found),
2287 Start looking for the child at this index.
2290 Does not support scope (ie. Parent.Child notation).
2292 wxPGProperty
* GetPropertyByNameWH( const wxString
& name
,
2293 unsigned int hintIndex
) const;
2295 /** This is used by Insert etc. */
2296 void DoAddChild( wxPGProperty
* prop
,
2298 bool correct_mode
= true );
2300 void DoGenerateComposedValue( wxString
& text
,
2301 int argFlags
= wxPG_VALUE_IS_CURRENT
,
2302 const wxVariantList
* valueOverrides
= NULL
,
2303 wxPGHashMapS2S
* childResults
= NULL
) const;
2305 void DoSetName(const wxString
& str
) { m_name
= str
; }
2307 /** Deletes all sub-properties. */
2310 bool HasCell( unsigned int column
) const
2312 if ( m_cells
.size() > column
)
2317 void InitAfterAdded( wxPropertyGridPageState
* pageState
,
2318 wxPropertyGrid
* propgrid
);
2320 // Removes child property with given pointer. Does not delete it.
2321 void RemoveChild( wxPGProperty
* p
);
2323 void DoPreAddChild( int index
, wxPGProperty
* prop
);
2325 void SetParentState( wxPropertyGridPageState
* pstate
)
2326 { m_parentState
= pstate
; }
2328 // Call after fixed sub-properties added/removed after creation.
2329 // if oldSelInd >= 0 and < new max items, then selection is
2331 void SubPropsChanged( int oldSelInd
= -1 );
2333 int GetY2( int lh
) const;
2337 wxPGProperty
* m_parent
;
2338 wxPropertyGridPageState
* m_parentState
;
2340 wxClientData
* m_clientObject
;
2342 // Overrides editor returned by property class
2343 const wxPGEditor
* m_customEditor
;
2344 #if wxUSE_VALIDATORS
2345 // Editor is going to get this validator
2346 wxValidator
* m_validator
;
2348 // Show this in front of the value
2350 // TODO: Can bitmap be implemented with wxPGCell?
2351 wxBitmap
* m_valueBitmap
;
2354 wxPGAttributeStorage m_attributes
;
2355 wxArrayPGProperty m_children
;
2357 // Extended cell information
2358 wxVector
<wxPGCell
> m_cells
;
2360 // Choices shown in drop-down list of editor control.
2361 wxPGChoices m_choices
;
2363 // Help shown in statusbar or help box.
2364 wxString m_helpString
;
2366 // Index in parent's property array.
2367 unsigned int m_arrIndex
;
2369 // If not -1, then overrides m_value
2374 // Maximum length (mainly for string properties). Could be in some sort of
2375 // wxBaseStringProperty, but currently, for maximum flexibility and
2376 // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
2377 // so short int will fit in just fine.
2380 // Root has 0, categories etc. at that level 1, etc.
2381 unsigned char m_depth
;
2383 // m_depthBgCol indicates width of background colour between margin and item
2384 // (essentially this is category's depth, if none then equals m_depth).
2385 unsigned char m_depthBgCol
;
2388 // Called in constructors.
2390 void Init( const wxString
& label
, const wxString
& name
);
2393 // -----------------------------------------------------------------------
2396 // Property class declaration helper macros
2397 // (wxPGRootPropertyClass and wxPropertyCategory require this).
2400 #define WX_PG_DECLARE_DOGETEDITORCLASS \
2401 virtual const wxPGEditor* DoGetEditorClass() const;
2403 #ifndef WX_PG_DECLARE_PROPERTY_CLASS
2404 #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
2406 DECLARE_DYNAMIC_CLASS(CLASSNAME) \
2407 WX_PG_DECLARE_DOGETEDITORCLASS \
2411 // Implements sans constructor function. Also, first arg is class name, not
2413 #define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
2414 const wxPGEditor* PROPNAME::DoGetEditorClass() const \
2416 return wxPGEditor_##EDITOR; \
2419 // -----------------------------------------------------------------------
2421 /** @class wxPGRootProperty
2423 Root parent property.
2425 class WXDLLIMPEXP_PROPGRID wxPGRootProperty
: public wxPGProperty
2428 WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty
)
2432 wxPGRootProperty( const wxString
& name
= wxS("<Root>") );
2433 virtual ~wxPGRootProperty();
2435 virtual bool StringToValue( wxVariant
&, const wxString
&, int ) const
2443 // -----------------------------------------------------------------------
2445 /** @class wxPropertyCategory
2447 Category (caption) property.
2449 class WXDLLIMPEXP_PROPGRID wxPropertyCategory
: public wxPGProperty
2451 friend class wxPropertyGrid
;
2452 friend class wxPropertyGridPageState
;
2453 WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory
)
2456 /** Default constructor is only used in special cases. */
2457 wxPropertyCategory();
2459 wxPropertyCategory( const wxString
& label
,
2460 const wxString
& name
= wxPG_LABEL
);
2461 ~wxPropertyCategory();
2463 int GetTextExtent( const wxWindow
* wnd
, const wxFont
& font
) const;
2465 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
) const;
2466 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
2469 void SetTextColIndex( unsigned int colInd
)
2470 { m_capFgColIndex
= (wxByte
) colInd
; }
2471 unsigned int GetTextColIndex() const
2472 { return (unsigned int) m_capFgColIndex
; }
2474 void CalculateTextExtent( wxWindow
* wnd
, const wxFont
& font
);
2476 int m_textExtent
; // pre-calculated length of text
2477 wxByte m_capFgColIndex
; // caption text colour index
2483 // -----------------------------------------------------------------------
2485 #endif // wxUSE_PROPGRID
2487 #endif // _WX_PROPGRID_PROPERTY_H_