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 licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_PROPGRID_PROPERTY_H_
13 #define _WX_PROPGRID_PROPERTY_H_
19 #include "wx/propgrid/propgriddefs.h"
21 // -----------------------------------------------------------------------
23 #define wxNullProperty ((wxPGProperty*)NULL)
26 /** @class wxPGPaintData
28 Contains information relayed to property's OnCustomPaint.
32 /** wxPropertyGrid. */
33 const wxPropertyGrid
* m_parent
;
36 Normally -1, otherwise index to drop-down list item that has to be
41 /** Set to drawn width in OnCustomPaint (optional). */
45 In a measure item call, set this to the height of item at m_choiceItem
52 // space between vertical sides of a custom image
53 #define wxPG_CUSTOM_IMAGE_SPACINGY 1
55 // space between caption and selection rectangle,
56 #define wxPG_CAPRECTXMARGIN 2
58 // horizontally and vertically
59 #define wxPG_CAPRECTYMARGIN 1
62 /** @class wxPGCellRenderer
64 Base class for wxPropertyGrid cell renderers.
66 class WXDLLIMPEXP_PROPGRID wxPGCellRenderer
: public wxObjectRefData
71 : wxObjectRefData() { }
72 virtual ~wxPGCellRenderer() { }
77 // We are painting selected item
78 Selected
= 0x00010000,
80 // We are painting item in choice popup
81 ChoicePopup
= 0x00020000,
83 // We are rendering wxOwnerDrawnComboBox control
84 // (or other owner drawn control, but that is only
85 // officially supported one ATM).
88 // We are painting a disable property
89 Disabled
= 0x00080000,
91 // We are painting selected, disabled, or similar
92 // item that dictates fore- and background colours,
93 // overriding any cell values.
94 DontUseCellFgCol
= 0x00100000,
95 DontUseCellBgCol
= 0x00200000,
96 DontUseCellColours
= DontUseCellFgCol
|
101 Returns @true if rendered something in the foreground (text or
104 virtual bool Render( wxDC
& dc
,
106 const wxPropertyGrid
* propertyGrid
,
107 wxPGProperty
* property
,
110 int flags
) const = 0;
112 /** Returns size of the image in front of the editable area.
114 If property is NULL, then this call is for a custom value. In that case
115 the item is index to wxPropertyGrid's custom values.
117 virtual wxSize
GetImageSize( const wxPGProperty
* property
,
121 /** Paints property category selection rectangle.
123 virtual void DrawCaptionSelectionRect( wxDC
& dc
,
125 int w
, int h
) const;
127 /** Utility to draw vertically centered text.
129 void DrawText( wxDC
& dc
,
132 const wxString
& text
) const;
135 Utility to draw editor's value, or vertically aligned text if editor is
138 void DrawEditorValue( wxDC
& dc
, const wxRect
& rect
,
139 int xOffset
, const wxString
& text
,
140 wxPGProperty
* property
,
141 const wxPGEditor
* editor
) const;
143 /** Utility to render cell bitmap and set text colour plus bg brush
146 @return Returns image width, which, for instance, can be passed to
149 int PreDrawCell( wxDC
& dc
,
151 const wxPGCell
& cell
,
155 Utility to be called after drawing is done, to revert whatever
156 changes PreDrawCell() did.
159 Same as those passed to PreDrawCell().
161 void PostDrawCell( wxDC
& dc
,
162 const wxPropertyGrid
* propGrid
,
163 const wxPGCell
& cell
,
169 @class wxPGDefaultRenderer
171 Default cell renderer, that can handles the common
174 class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer
: public wxPGCellRenderer
177 virtual bool Render( wxDC
& dc
,
179 const wxPropertyGrid
* propertyGrid
,
180 wxPGProperty
* property
,
185 virtual wxSize
GetImageSize( const wxPGProperty
* property
,
193 class WXDLLIMPEXP_PROPGRID wxPGCellData
: public wxObjectRefData
195 friend class wxPGCell
;
199 void SetText( const wxString
& text
)
202 m_hasValidText
= true;
204 void SetBitmap( const wxBitmap
& bitmap
) { m_bitmap
= bitmap
; }
205 void SetFgCol( const wxColour
& col
) { m_fgCol
= col
; }
206 void SetBgCol( const wxColour
& col
) { m_bgCol
= col
; }
207 void SetFont( const wxFont
& font
) { m_font
= font
; }
210 virtual ~wxPGCellData() { }
218 // True if m_text is valid and specified
226 Base class for wxPropertyGrid cell information.
228 class WXDLLIMPEXP_PROPGRID wxPGCell
: public wxObject
232 wxPGCell(const wxPGCell
& other
)
237 wxPGCell( const wxString
& text
,
238 const wxBitmap
& bitmap
= wxNullBitmap
,
239 const wxColour
& fgCol
= wxNullColour
,
240 const wxColour
& bgCol
= wxNullColour
);
242 virtual ~wxPGCell() { }
244 wxPGCellData
* GetData()
246 return (wxPGCellData
*) m_refData
;
249 const wxPGCellData
* GetData() const
251 return (const wxPGCellData
*) m_refData
;
256 return (m_refData
&& GetData()->m_hasValidText
);
260 Sets empty but valid data to this cell object.
265 Merges valid data from srcCell into this.
267 void MergeFrom( const wxPGCell
& srcCell
);
269 void SetText( const wxString
& text
);
270 void SetBitmap( const wxBitmap
& bitmap
);
271 void SetFgCol( const wxColour
& col
);
274 Sets font of the cell.
276 @remarks Because wxPropertyGrid does not support rows of
277 different height, it makes little sense to change
278 size of the font. Therefore it is recommended
279 to use return value of wxPropertyGrid::GetFont()
280 or wxPropertyGrid::GetCaptionFont() as a basis
281 for the font that, after modifications, is passed
282 to this member function.
284 void SetFont( const wxFont
& font
);
286 void SetBgCol( const wxColour
& col
);
288 const wxString
& GetText() const { return GetData()->m_text
; }
289 const wxBitmap
& GetBitmap() const { return GetData()->m_bitmap
; }
290 const wxColour
& GetFgCol() const { return GetData()->m_fgCol
; }
293 Returns font of the cell. If no specific font is set for this
294 cell, then the font will be invalid.
296 const wxFont
& GetFont() const { return GetData()->m_font
; }
298 const wxColour
& GetBgCol() const { return GetData()->m_bgCol
; }
300 wxPGCell
& operator=( const wxPGCell
& other
)
302 if ( this != &other
)
309 // Used mostly internally to figure out if this cell is supposed
310 // to have default values when attached to a grid.
311 bool IsInvalid() const
313 return ( m_refData
== NULL
);
317 virtual wxObjectRefData
*CreateRefData() const
318 { return new wxPGCellData(); }
320 virtual wxObjectRefData
*CloneRefData(const wxObjectRefData
*data
) const;
323 // -----------------------------------------------------------------------
325 /** @class wxPGAttributeStorage
327 wxPGAttributeStorage is somewhat optimized storage for
328 key=variant pairs (ie. a map).
330 class WXDLLIMPEXP_PROPGRID wxPGAttributeStorage
333 wxPGAttributeStorage();
334 ~wxPGAttributeStorage();
336 void Set( const wxString
& name
, const wxVariant
& value
);
337 unsigned int GetCount() const { return (unsigned int) m_map
.size(); }
338 wxVariant
FindValue( const wxString
& name
) const
340 wxPGHashMapS2P::const_iterator it
= m_map
.find(name
);
341 if ( it
!= m_map
.end() )
343 wxVariantData
* data
= (wxVariantData
*) it
->second
;
345 return wxVariant(data
, it
->first
);
350 typedef wxPGHashMapS2P::const_iterator const_iterator
;
351 const_iterator
StartIteration() const
353 return m_map
.begin();
355 bool GetNext( const_iterator
& it
, wxVariant
& variant
) const
357 if ( it
== m_map
.end() )
360 wxVariantData
* data
= (wxVariantData
*) it
->second
;
362 variant
.SetData(data
);
363 variant
.SetName(it
->first
);
369 wxPGHashMapS2P m_map
;
373 // -----------------------------------------------------------------------
375 /** @section propgrid_propflags wxPGProperty Flags
379 enum wxPGPropertyFlags
382 /** Indicates bold font.
384 wxPG_PROP_MODIFIED
= 0x0001,
386 /** Disables ('greyed' text and editor does not activate) property.
388 wxPG_PROP_DISABLED
= 0x0002,
390 /** Hider button will hide this property.
392 wxPG_PROP_HIDDEN
= 0x0004,
394 /** This property has custom paint image just in front of its value.
395 If property only draws custom images into a popup list, then this
396 flag should not be set.
398 wxPG_PROP_CUSTOMIMAGE
= 0x0008,
400 /** Do not create text based editor for this property (but button-triggered
401 dialog and choice are ok).
403 wxPG_PROP_NOEDITOR
= 0x0010,
405 /** Property is collapsed, ie. it's children are hidden.
407 wxPG_PROP_COLLAPSED
= 0x0020,
410 If property is selected, then indicates that validation failed for pending
413 If property is not selected, then indicates that the the actual property
414 value has failed validation (NB: this behavior is not currently supported,
415 but may be used in future).
417 wxPG_PROP_INVALID_VALUE
= 0x0040,
421 /** Switched via SetWasModified(). Temporary flag - only used when
422 setting/changing property value.
424 wxPG_PROP_WAS_MODIFIED
= 0x0200,
427 If set, then child properties (if any) are private, and should be
428 "invisible" to the application.
430 wxPG_PROP_AGGREGATE
= 0x0400,
432 /** If set, then child properties (if any) are copies and should not
435 wxPG_PROP_CHILDREN_ARE_COPIES
= 0x0800,
438 Classifies this item as a non-category.
440 Used for faster item type identification.
442 wxPG_PROP_PROPERTY
= 0x1000,
445 Classifies this item as a category.
447 Used for faster item type identification.
449 wxPG_PROP_CATEGORY
= 0x2000,
451 /** Classifies this item as a property that has children, but is not aggregate
452 (ie children are not private).
454 wxPG_PROP_MISC_PARENT
= 0x4000,
456 /** Property is read-only. Editor is still created for wxTextCtrl-based
457 property editors. For others, editor is not usually created because
458 they do implement wxTE_READONLY style or equivalent.
460 wxPG_PROP_READONLY
= 0x8000,
463 // NB: FLAGS ABOVE 0x8000 CANNOT BE USED WITH PROPERTY ITERATORS
466 /** Property's value is composed from values of child properties.
468 This flag cannot be used with property iterators.
470 wxPG_PROP_COMPOSED_VALUE
= 0x00010000,
472 /** Common value of property is selectable in editor.
474 This flag cannot be used with property iterators.
476 wxPG_PROP_USES_COMMON_VALUE
= 0x00020000,
478 /** Property can be set to unspecified value via editor.
479 Currently, this applies to following properties:
480 - wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty:
484 This flag cannot be used with property iterators.
486 @see wxPGProperty::SetAutoUnspecified()
488 wxPG_PROP_AUTO_UNSPECIFIED
= 0x00040000,
490 /** Indicates the bit useable by derived properties.
492 wxPG_PROP_CLASS_SPECIFIC_1
= 0x00080000,
494 /** Indicates the bit useable by derived properties.
496 wxPG_PROP_CLASS_SPECIFIC_2
= 0x00100000,
498 /** Indicates that the property is being deleted and should be ignored.
500 wxPG_PROP_BEING_DELETED
= 0x00200000
506 #define wxPG_PROP_MAX wxPG_PROP_AUTO_UNSPECIFIED
508 /** Property with children must have one of these set, otherwise iterators
509 will not work correctly.
510 Code should automatically take care of this, however.
512 #define wxPG_PROP_PARENTAL_FLAGS \
513 ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \
514 wxPG_PROP_CATEGORY | \
515 wxPG_PROP_MISC_PARENT))
520 // Combination of flags that can be stored by GetFlagsAsString
521 #define wxPG_STRING_STORED_FLAGS \
522 (wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED)
524 // -----------------------------------------------------------------------
527 @section propgrid_property_attributes wxPropertyGrid Property Attribute
530 wxPGProperty::SetAttribute() and
531 wxPropertyGridInterface::SetPropertyAttribute() accept one of these as
532 attribute name argument.
534 You can use strings instead of constants. However, some of these
535 constants are redefined to use cached strings which may reduce
536 your binary size by some amount.
541 /** Set default value for property.
543 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
545 /** Universal, int or double. Minimum value for numeric properties.
547 #define wxPG_ATTR_MIN wxS("Min")
549 /** Universal, int or double. Maximum value for numeric properties.
551 #define wxPG_ATTR_MAX wxS("Max")
553 /** Universal, string. When set, will be shown as text after the displayed
554 text value. Alternatively, if third column is enabled, text will be shown
555 there (for any type of property).
557 #define wxPG_ATTR_UNITS wxS("Units")
559 /** When set, will be shown as 'greyed' text in property's value cell when
560 the actual displayed value is blank.
562 #define wxPG_ATTR_HINT wxS("Hint")
564 #if wxPG_COMPATIBILITY_1_4
566 @deprecated Use "Hint" (wxPG_ATTR_HINT) instead.
568 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
571 /** Universal, wxArrayString. Set to enable auto-completion in any
572 wxTextCtrl-based property editor.
574 #define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
576 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
577 Default value is False.
579 When set to True, bool property will use check box instead of a
580 combo box as its editor control. If you set this attribute
581 for a wxFlagsProperty, it is automatically applied to child
584 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
586 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
587 Default value is False.
589 Set to True for the bool property to cycle value on double click
590 (instead of showing the popup listbox). If you set this attribute
591 for a wxFlagsProperty, it is automatically applied to child
594 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
597 wxFloatProperty (and similar) specific, int, default -1.
599 Sets the (max) precision used when floating point value is rendered as
600 text. The default -1 means infinite precision.
602 #define wxPG_FLOAT_PRECISION wxS("Precision")
605 The text will be echoed as asterisks (wxTE_PASSWORD will be passed to
608 #define wxPG_STRING_PASSWORD wxS("Password")
610 /** Define base used by a wxUIntProperty. Valid constants are
611 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
612 (lowercase characters).
614 #define wxPG_UINT_BASE wxS("Base")
616 /** Define prefix rendered to wxUIntProperty. Accepted constants
617 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
618 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
621 #define wxPG_UINT_PREFIX wxS("Prefix")
624 wxFileProperty/wxImageFileProperty specific, wxChar*, default is
626 Sets the wildcard used in the triggered wxFileDialog. Format is the same.
628 #define wxPG_FILE_WILDCARD wxS("Wildcard")
630 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
631 When 0, only the file name is shown (i.e. drive and directory are hidden).
633 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
635 /** Specific to wxFileProperty and derived properties, wxString, default empty.
636 If set, then the filename is shown relative to the given path string.
638 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
641 Specific to wxFileProperty and derived properties, wxString, default is
644 Sets the initial path of where to look for files.
646 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
648 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
649 Sets a specific title for the dir dialog.
651 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
653 /** Specific to wxDirProperty, wxString, default is empty.
654 Sets a specific message for the dir dialog.
656 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
659 wxArrayStringProperty's string delimiter character. If this is aquotation
660 mark or hyphen, then strings will be quoted instead (with given
663 Default delimiter is quotation mark.
665 #define wxPG_ARRAY_DELIMITER wxS("Delimiter")
667 /** Sets displayed date format for wxDateProperty.
669 #define wxPG_DATE_FORMAT wxS("DateFormat")
671 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
672 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
674 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
676 /** SpinCtrl editor, int or double. How much number changes when button is
677 pressed (or up/down on keybard).
679 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
681 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
683 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
686 wxMultiChoiceProperty, int.
687 If 0, no user strings allowed. If 1, user strings appear before list
688 strings. If 2, user strings appear after list string.
690 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
693 wxColourProperty and its kind, int, default 1.
695 Setting this attribute to 0 hides custom colour from property's list of
698 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
701 wxColourProperty and its kind: Set to True in order to support editing
702 alpha colour component.
704 #define wxPG_COLOUR_HAS_ALPHA wxS("HasAlpha")
709 // Redefine attribute macros to use cached strings
710 #undef wxPG_ATTR_DEFAULT_VALUE
711 #define wxPG_ATTR_DEFAULT_VALUE wxPGGlobalVars->m_strDefaultValue
713 #define wxPG_ATTR_MIN wxPGGlobalVars->m_strMin
715 #define wxPG_ATTR_MAX wxPGGlobalVars->m_strMax
716 #undef wxPG_ATTR_UNITS
717 #define wxPG_ATTR_UNITS wxPGGlobalVars->m_strUnits
718 #undef wxPG_ATTR_HINT
719 #define wxPG_ATTR_HINT wxPGGlobalVars->m_strHint
720 #if wxPG_COMPATIBILITY_1_4
721 #undef wxPG_ATTR_INLINE_HELP
722 #define wxPG_ATTR_INLINE_HELP wxPGGlobalVars->m_strInlineHelp
725 // -----------------------------------------------------------------------
727 /** @class wxPGChoiceEntry
728 Data of a single wxPGChoices choice.
730 class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry
: public wxPGCell
734 wxPGChoiceEntry(const wxPGChoiceEntry
& other
)
737 m_value
= other
.m_value
;
739 wxPGChoiceEntry( const wxString
& label
,
740 int value
= wxPG_INVALID_VALUE
)
741 : wxPGCell(), m_value(value
)
746 virtual ~wxPGChoiceEntry() { }
748 void SetValue( int value
) { m_value
= value
; }
749 int GetValue() const { return m_value
; }
751 wxPGChoiceEntry
& operator=( const wxPGChoiceEntry
& other
)
753 if ( this != &other
)
757 m_value
= other
.m_value
;
766 typedef void* wxPGChoicesId
;
768 class WXDLLIMPEXP_PROPGRID wxPGChoicesData
: public wxObjectRefData
770 friend class wxPGChoices
;
772 // Constructor sets m_refCount to 1.
775 void CopyDataFrom( wxPGChoicesData
* data
);
777 wxPGChoiceEntry
& Insert( int index
, const wxPGChoiceEntry
& item
);
779 // Delete all entries
782 unsigned int GetCount() const
784 return (unsigned int) m_items
.size();
787 const wxPGChoiceEntry
& Item( unsigned int i
) const
789 wxASSERT_MSG( i
< GetCount(), "invalid index" );
793 wxPGChoiceEntry
& Item( unsigned int i
)
795 wxASSERT_MSG( i
< GetCount(), "invalid index" );
800 wxVector
<wxPGChoiceEntry
> m_items
;
802 virtual ~wxPGChoicesData();
805 #define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL)
808 /** @class wxPGChoices
810 Helper class for managing choices of wxPropertyGrid properties.
811 Each entry can have label, value, bitmap, text colour, and background
814 wxPGChoices uses reference counting, similar to other wxWidgets classes.
815 This means that assignment operator and copy constructor only copy the
816 reference and not the actual data. Use Copy() member function to create a
819 @remarks If you do not specify value for entry, index is used.
824 class WXDLLIMPEXP_PROPGRID wxPGChoices
827 typedef long ValArrItem
;
829 /** Default constructor. */
836 Copy constructor, uses reference counting. To create a real copy,
837 use Copy() member function instead.
839 wxPGChoices( const wxPGChoices
& a
)
841 if ( a
.m_data
!= wxPGChoicesEmptyData
)
855 Values for choices. If NULL, indexes are used.
857 wxPGChoices( const wxChar
* const* labels
, const long* values
= NULL
)
870 Values for choices. If empty, indexes are used.
872 wxPGChoices( const wxArrayString
& labels
,
873 const wxArrayInt
& values
= wxArrayInt() )
879 /** Simple interface constructor. */
880 wxPGChoices( wxPGChoicesData
* data
)
896 If did not have own copies, creates them now. If was empty, identical
897 to set except that creates copies.
900 Labels for added choices.
903 Values for added choices. If empty, relevant entry indexes are used.
905 void Add( const wxChar
* const* labels
, const ValArrItem
* values
= NULL
);
907 /** Version that works with wxArrayString and wxArrayInt. */
908 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
= wxArrayInt() );
911 Adds a single choice.
914 Label for added choice.
917 Value for added choice. If unspecified, index is used.
919 wxPGChoiceEntry
& Add( const wxString
& label
,
920 int value
= wxPG_INVALID_VALUE
);
922 /** Adds a single item, with bitmap. */
923 wxPGChoiceEntry
& Add( const wxString
& label
,
924 const wxBitmap
& bitmap
,
925 int value
= wxPG_INVALID_VALUE
);
927 /** Adds a single item with full entry information. */
928 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
930 return Insert(entry
, -1);
933 /** Adds single item. */
934 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
,
935 int value
= wxPG_INVALID_VALUE
);
938 Assigns choices data, using reference counting. To create a real copy,
939 use Copy() member function instead.
941 void Assign( const wxPGChoices
& a
)
943 AssignData(a
.m_data
);
946 void AssignData( wxPGChoicesData
* data
);
948 /** Delete all choices. */
952 Returns a real copy of the choices.
954 wxPGChoices
Copy() const
958 dst
.m_data
->CopyDataFrom(m_data
);
964 if ( m_data
== wxPGChoicesEmptyData
)
965 m_data
= new wxPGChoicesData();
968 /** Gets a unsigned number identifying this list. */
969 wxPGChoicesId
GetId() const { return (wxPGChoicesId
) m_data
; };
971 const wxString
& GetLabel( unsigned int ind
) const
973 return Item(ind
).GetText();
976 unsigned int GetCount () const
981 return m_data
->GetCount();
984 int GetValue( unsigned int ind
) const { return Item(ind
).GetValue(); }
986 /** Returns array of values matching the given strings. Unmatching strings
987 result in wxPG_INVALID_VALUE entry in array.
989 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
991 /** Returns array of indices matching given strings. Unmatching strings
992 are added to 'unmatched', if not NULL.
994 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
995 wxArrayString
* unmatched
= NULL
) const;
997 int Index( const wxString
& str
) const;
998 int Index( int val
) const;
1000 /** Inserts single item. */
1001 wxPGChoiceEntry
& Insert( const wxString
& label
,
1003 int value
= wxPG_INVALID_VALUE
);
1005 /** Inserts a single item with full entry information. */
1006 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1008 /** Returns false if this is a constant empty set of choices,
1009 which should not be modified.
1013 return ( m_data
!= wxPGChoicesEmptyData
);
1016 const wxPGChoiceEntry
& Item( unsigned int i
) const
1019 return m_data
->Item(i
);
1022 wxPGChoiceEntry
& Item( unsigned int i
)
1025 return m_data
->Item(i
);
1028 /** Removes count items starting at position nIndex. */
1029 void RemoveAt(size_t nIndex
, size_t count
= 1);
1031 /** Does not create copies for itself.
1034 void Set( const wxChar
* const* labels
, const long* values
= NULL
)
1040 /** Version that works with wxArrayString and wxArrayInt. */
1041 void Set( const wxArrayString
& labels
,
1042 const wxArrayInt
& values
= wxArrayInt() )
1051 // Creates exclusive copy of current choices
1052 void AllocExclusive();
1054 // Returns data, increases refcount.
1055 wxPGChoicesData
* GetData()
1057 wxASSERT( m_data
->GetRefCount() != -1 );
1062 // Returns plain data ptr - no refcounting stuff is done.
1063 wxPGChoicesData
* GetDataPtr() const { return m_data
; }
1065 // Changes ownership of data to you.
1066 wxPGChoicesData
* ExtractData()
1068 wxPGChoicesData
* data
= m_data
;
1069 m_data
= wxPGChoicesEmptyData
;
1073 wxArrayString
GetLabels() const;
1075 void operator= (const wxPGChoices
& a
)
1078 AssignData(a
.m_data
);
1081 wxPGChoiceEntry
& operator[](unsigned int i
)
1086 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1092 wxPGChoicesData
* m_data
;
1098 // -----------------------------------------------------------------------
1100 /** @class wxPGProperty
1102 wxPGProperty is base class for all wxPropertyGrid properties.
1104 NB: Full class overview is now only present in
1105 interface/wx/propgrid/property.h.
1107 @library{wxpropgrid}
1110 class WXDLLIMPEXP_PROPGRID wxPGProperty
: public wxObject
1112 friend class wxPropertyGrid
;
1113 friend class wxPropertyGridInterface
;
1114 friend class wxPropertyGridPageState
;
1115 friend class wxPropertyGridPopulator
;
1116 friend class wxStringProperty
; // Proper "<composed>" support requires this
1118 DECLARE_ABSTRACT_CLASS(wxPGProperty
)
1120 typedef wxUint32 FlagType
;
1123 Default constructor.
1130 All non-abstract property classes should have a constructor with
1131 the same first two arguments as this one.
1133 wxPGProperty( const wxString
& label
, const wxString
& name
);
1137 It is customary for derived properties to implement this.
1139 virtual ~wxPGProperty();
1141 /** This virtual function is called after m_value has been set.
1144 - If m_value was set to Null variant (ie. unspecified value),
1145 OnSetValue() will not be called.
1146 - m_value may be of any variant type. Typically properties internally
1147 support only one variant type, and as such OnSetValue() provides a
1148 good opportunity to convert
1149 supported values into internal type.
1150 - Default implementation does nothing.
1152 virtual void OnSetValue();
1154 /** Override this to return something else than m_value as the value.
1156 virtual wxVariant
DoGetValue() const { return m_value
; }
1158 /** Implement this function in derived class to check the value.
1159 Return true if it is ok. Returning false prevents property change events
1163 - Default implementation always returns true.
1165 virtual bool ValidateValue( wxVariant
& value
,
1166 wxPGValidationInfo
& validationInfo
) const;
1169 Converts text into wxVariant value appropriate for this property.
1172 On function entry this is the old value (should not be wxNullVariant
1173 in normal cases). Translated value must be assigned back to it.
1176 Text to be translated into variant.
1179 If wxPG_FULL_VALUE is set, returns complete, storable value instead
1180 of displayable one (they may be different).
1181 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
1182 composite property string value (as generated by ValueToString()
1183 called with this same flag).
1185 @return Returns @true if resulting wxVariant value was different.
1187 @remarks Default implementation converts semicolon delimited tokens into
1188 child values. Only works for properties with children.
1190 You might want to take into account that m_value is Null variant
1191 if property value is unspecified (which is usually only case if
1192 you explicitly enabled that sort behavior).
1194 virtual bool StringToValue( wxVariant
& variant
,
1195 const wxString
& text
,
1196 int argFlags
= 0 ) const;
1199 Converts integer (possibly a choice selection) into wxVariant value
1200 appropriate for this property.
1203 On function entry this is the old value (should not be wxNullVariant
1204 in normal cases). Translated value must be assigned back to it.
1207 Integer to be translated into variant.
1210 If wxPG_FULL_VALUE is set, returns complete, storable value instead
1213 @return Returns @true if resulting wxVariant value was different.
1216 - If property is not supposed to use choice or spinctrl or other editor
1217 with int-based value, it is not necessary to implement this method.
1218 - Default implementation simply assign given int to m_value.
1219 - If property uses choice control, and displays a dialog on some choice
1220 items, then it is preferred to display that dialog in IntToValue
1222 - You might want to take into account that m_value is Null variant if
1223 property value is unspecified (which is usually only case if you
1224 explicitly enabled that sort behavior).
1226 virtual bool IntToValue( wxVariant
& value
,
1228 int argFlags
= 0 ) const;
1231 Converts property value into a text representation.
1234 Value to be converted.
1237 If 0 (default value), then displayed string is returned.
1238 If wxPG_FULL_VALUE is set, returns complete, storable string value
1239 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1240 string value that must be editable in textctrl. If
1241 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1242 display as a part of string property's composite text
1245 @remarks Default implementation calls GenerateComposedValue().
1247 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
= 0 ) const;
1249 /** Converts string to a value, and if successful, calls SetValue() on it.
1250 Default behavior is to do nothing.
1252 String to get the value from.
1254 true if value was changed.
1256 bool SetValueFromString( const wxString
& text
, int flags
= wxPG_PROGRAMMATIC_VALUE
);
1258 /** Converts integer to a value, and if succesful, calls SetValue() on it.
1259 Default behavior is to do nothing.
1261 Int to get the value from.
1263 If has wxPG_FULL_VALUE, then the value given is a actual value and
1266 True if value was changed.
1268 bool SetValueFromInt( long value
, int flags
= 0 );
1271 Returns size of the custom painted image in front of property.
1273 This method must be overridden to return non-default value if
1274 OnCustomPaint is to be called.
1276 Normally -1, but can be an index to the property's list of items.
1278 - Default behavior is to return wxSize(0,0), which means no image.
1279 - Default image width or height is indicated with dimension -1.
1280 - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1).
1282 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
1285 Events received by editor widgets are processed here.
1287 Note that editor class usually processes most events. Some, such as
1288 button press events of TextCtrlAndButton class, can be handled here.
1289 Also, if custom handling for regular events is desired, then that can
1290 also be done (for example, wxSystemColourProperty custom handles
1291 wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
1292 'custom' selection is made).
1294 If the event causes value to be changed, SetValueInEvent()
1295 should be called to set the new value.
1300 Should return true if any changes in value should be reported.
1302 If property uses choice control, and displays a dialog on some choice
1303 items, then it is preferred to display that dialog in IntToValue
1306 virtual bool OnEvent( wxPropertyGrid
* propgrid
,
1307 wxWindow
* wnd_primary
,
1311 Called after value of a child property has been altered. Must return
1312 new value of the whole property (after any alterations warrented by
1315 Note that this function is usually called at the time that value of
1316 this property, or given child property, is still pending for change,
1317 and as such, result of GetValue() or m_value should not be relied
1320 Sample pseudo-code implementation:
1323 wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
1325 wxVariant& childValue ) const
1327 // Acquire reference to actual type of data stored in variant
1328 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
1329 // were used to create the variant class).
1330 T& data = TFromVariant(thisValue);
1332 // Copy childValue into data.
1333 switch ( childIndex )
1336 data.SetSubProp1( childvalue.GetLong() );
1339 data.SetSubProp2( childvalue.GetString() );
1344 // Return altered data
1350 Value of this property. Changed value should be returned (in
1351 previous versions of wxPropertyGrid it was only necessary to
1352 write value back to this argument).
1354 Index of child changed (you can use Item(childIndex) to get
1357 (Pending) value of the child property.
1360 Modified value of the whole property.
1362 virtual wxVariant
ChildChanged( wxVariant
& thisValue
,
1364 wxVariant
& childValue
) const;
1366 /** Returns pointer to an instance of used editor.
1368 virtual const wxPGEditor
* DoGetEditorClass() const;
1370 /** Returns pointer to the wxValidator that should be used
1371 with the editor of this property (NULL for no validator).
1372 Setting validator explicitly via SetPropertyValidator
1375 In most situations, code like this should work well
1376 (macros are used to maintain one actual validator instance,
1377 so on the second call the function exits within the first
1382 wxValidator* wxMyPropertyClass::DoGetValidator () const
1384 WX_PG_DOGETVALIDATOR_ENTRY()
1386 wxMyValidator* validator = new wxMyValidator(...);
1388 ... prepare validator...
1390 WX_PG_DOGETVALIDATOR_EXIT(validator)
1396 You can get common filename validator by returning
1397 wxFileProperty::GetClassValidator(). wxDirProperty,
1398 for example, uses it.
1400 virtual wxValidator
* DoGetValidator () const;
1403 Override to paint an image in front of the property value text or
1404 drop-down list item (but only if wxPGProperty::OnMeasureImage is
1405 overridden as well).
1407 If property's OnMeasureImage() returns size that has height != 0 but
1408 less than row height ( < 0 has special meanings), wxPropertyGrid calls
1409 this method to draw a custom image in a limited area in front of the
1410 editor control or value text/graphics, and if control has drop-down
1411 list, then the image is drawn there as well (even in the case
1412 OnMeasureImage() returned higher height than row height).
1414 NOTE: Following applies when OnMeasureImage() returns a "flexible"
1415 height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
1416 height items: If rect.x is < 0, then this is a measure item call, which
1417 means that dc is invalid and only thing that should be done is to set
1418 paintdata.m_drawnHeight to the height of the image of item at index
1419 paintdata.m_choiceItem. This call may be done even as often as once
1420 every drop-down popup show.
1425 Box reserved for custom graphics. Includes surrounding rectangle,
1426 if any. If x is < 0, then this is a measure item call (see above).
1428 wxPGPaintData structure with much useful data.
1431 - You can actually exceed rect width, but if you do so then
1432 paintdata.m_drawnWidth must be set to the full width drawn in
1434 - Due to technical reasons, rect's height will be default even if
1435 custom height was reported during measure call.
1436 - Brush is guaranteed to be default background colour. It has been
1437 already used to clear the background of area being painted. It
1439 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper
1440 colour) pen for drawing framing rectangle. It can be changed as
1443 @see ValueToString()
1445 virtual void OnCustomPaint( wxDC
& dc
,
1447 wxPGPaintData
& paintdata
);
1450 Returns used wxPGCellRenderer instance for given property column
1453 Default implementation returns editor's renderer for all columns.
1455 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
1457 /** Returns which choice is currently selected. Only applies to properties
1460 Needs to reimplemented in derived class if property value does not
1461 map directly to a choice. Integer as index, bool, and string usually do.
1463 virtual int GetChoiceSelection() const;
1466 Refresh values of child properties.
1468 Automatically called after value is set.
1470 virtual void RefreshChildren();
1473 Reimplement this member function to add special handling for
1474 attributes of this property.
1476 @return Return @false to have the attribute automatically stored in
1477 m_attributes. Default implementation simply does that and
1480 @remarks To actually set property attribute values from the
1481 application, use wxPGProperty::SetAttribute() instead.
1483 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
1485 /** Returns value of an attribute.
1487 Override if custom handling of attributes is needed.
1489 Default implementation simply return NULL variant.
1491 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
1493 /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
1494 used when user presses the (optional) button next to the editor control;
1496 Default implementation returns NULL (ie. no action is generated when
1499 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
1502 Called whenever validation has failed with given pending value.
1504 @remarks If you implement this in your custom property class, please
1505 remember to call the baser implementation as well, since they
1506 may use it to revert property into pre-change state.
1508 virtual void OnValidationFailure( wxVariant
& pendingValue
);
1510 /** Append a new choice to property's list of choices.
1512 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
)
1514 return InsertChoice(label
, wxNOT_FOUND
, value
);
1518 Returns true if children of this property are component values (for
1519 instance, points size, face name, and is_underlined are component
1522 bool AreChildrenComponents() const
1524 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
1531 Deletes children of the property.
1533 void DeleteChildren();
1536 Removes entry from property's wxPGChoices and editor control (if it is
1539 If selected item is deleted, then the value is set to unspecified.
1541 void DeleteChoice( int index
);
1544 Enables or disables the property. Disabled property usually appears
1545 as having grey text.
1548 If @false, property is disabled instead.
1550 @see wxPropertyGridInterface::EnableProperty()
1552 void Enable( bool enable
= true );
1555 Call to enable or disable usage of common value (integer value that can
1556 be selected for properties instead of their normal values) for this
1559 Common values are disabled by the default for all properties.
1561 void EnableCommonValue( bool enable
= true )
1563 if ( enable
) SetFlag( wxPG_PROP_USES_COMMON_VALUE
);
1564 else ClearFlag( wxPG_PROP_USES_COMMON_VALUE
);
1568 Composes text from values of child properties.
1570 wxString
GenerateComposedValue() const
1573 DoGenerateComposedValue(s
);
1577 /** Returns property's label. */
1578 const wxString
& GetLabel() const { return m_label
; }
1580 /** Returns property's name with all (non-category, non-root) parents. */
1581 wxString
GetName() const;
1584 Returns property's base name (ie parent's name is not added in any
1587 const wxString
& GetBaseName() const { return m_name
; }
1589 /** Returns read-only reference to property's list of choices.
1591 const wxPGChoices
& GetChoices() const
1596 /** Returns coordinate to the top y of the property. Note that the
1597 position of scrollbars is not taken into account.
1601 wxVariant
GetValue() const
1603 return DoGetValue();
1606 /** Returns reference to the internal stored value. GetValue is preferred
1607 way to get the actual value, since GetValueRef ignores DoGetValue,
1608 which may override stored value.
1610 wxVariant
& GetValueRef()
1615 const wxVariant
& GetValueRef() const
1620 // Helper function (for wxPython bindings and such) for settings protected
1622 wxVariant
GetValuePlain() const
1627 /** Returns text representation of property's value.
1630 If 0 (default value), then displayed string is returned.
1631 If wxPG_FULL_VALUE is set, returns complete, storable string value
1632 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1633 string value that must be editable in textctrl. If
1634 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1635 display as a part of string property's composite text
1638 @remarks In older versions, this function used to be overridden to convert
1639 property's value into a string representation. This function is
1640 now handled by ValueToString(), and overriding this function now
1641 will result in run-time assertion failure.
1643 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
1645 /** Synonymous to GetValueAsString().
1647 @deprecated Use GetValueAsString() instead.
1649 @see GetValueAsString()
1651 wxDEPRECATED( wxString
GetValueString( int argFlags
= 0 ) const );
1654 Returns wxPGCell of given column.
1656 @remarks const version of this member function returns 'default'
1657 wxPGCell object if the property itself didn't hold
1660 const wxPGCell
& GetCell( unsigned int column
) const;
1663 Returns wxPGCell of given column, creating one if necessary.
1665 wxPGCell
& GetCell( unsigned int column
)
1667 return GetOrCreateCell(column
);
1671 Returns wxPGCell of given column, creating one if necessary.
1673 wxPGCell
& GetOrCreateCell( unsigned int column
);
1675 /** Return number of displayed common values for this property.
1677 int GetDisplayedCommonValueCount() const;
1679 wxString
GetDisplayedString() const
1681 return GetValueAsString(0);
1685 Returns property's hint text (shown in empty value cell).
1687 inline wxString
GetHintText() const;
1689 /** Returns property grid where property lies. */
1690 wxPropertyGrid
* GetGrid() const;
1692 /** Returns owner wxPropertyGrid, but only if one is currently on a page
1693 displaying this property. */
1694 wxPropertyGrid
* GetGridIfDisplayed() const;
1696 /** Returns highest level non-category, non-root parent. Useful when you
1697 have nested wxCustomProperties/wxParentProperties.
1699 Thus, if immediate parent is root or category, this will return the
1702 wxPGProperty
* GetMainParent() const;
1704 /** Return parent of property */
1705 wxPGProperty
* GetParent() const { return m_parent
; }
1707 /** Returns true if property has editable wxTextCtrl when selected.
1710 Altough disabled properties do not displayed editor, they still
1711 return True here as being disabled is considered a temporary
1712 condition (unlike being read-only or having limited editing enabled).
1714 bool IsTextEditable() const;
1716 bool IsValueUnspecified() const
1718 return m_value
.IsNull();
1722 Returns non-zero if property has given flag set.
1724 @see propgrid_propflags
1726 FlagType
HasFlag( wxPGPropertyFlags flag
) const
1728 return ( m_flags
& flag
);
1731 /** Returns comma-delimited string of property attributes.
1733 const wxPGAttributeStorage
& GetAttributes() const
1735 return m_attributes
;
1738 /** Returns m_attributes as list wxVariant.
1740 wxVariant
GetAttributesAsList() const;
1743 Returns property flags.
1745 FlagType
GetFlags() const
1750 const wxPGEditor
* GetEditorClass() const;
1752 wxString
GetValueType() const
1754 return m_value
.GetType();
1757 /** Returns editor used for given column. NULL for no editor.
1759 const wxPGEditor
* GetColumnEditor( int column
) const
1762 return GetEditorClass();
1767 /** Returns common value selected for this property. -1 for none.
1769 int GetCommonValue() const
1771 return m_commonValue
;
1774 /** Returns true if property has even one visible child.
1776 bool HasVisibleChildren() const;
1779 Use this member function to add independent (ie. regular) children to
1782 @return Inserted childProperty.
1784 @remarks wxPropertyGrid is not automatically refreshed by this
1787 @see AddPrivateChild()
1789 wxPGProperty
* InsertChild( int index
, wxPGProperty
* childProperty
);
1791 /** Inserts a new choice to property's list of choices.
1793 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1796 Returns true if this property is actually a wxPropertyCategory.
1798 bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY
)?true:false; }
1800 /** Returns true if this property is actually a wxRootProperty.
1802 bool IsRoot() const { return (m_parent
== NULL
); }
1804 /** Returns true if this is a sub-property. */
1805 bool IsSubProperty() const
1807 wxPGProperty
* parent
= (wxPGProperty
*)m_parent
;
1808 if ( parent
&& !parent
->IsCategory() )
1813 /** Returns last visible sub-property, recursively.
1815 const wxPGProperty
* GetLastVisibleSubItem() const;
1817 wxVariant
GetDefaultValue() const;
1819 int GetMaxLength() const
1821 return (int) m_maxLen
;
1825 Determines, recursively, if all children are not unspecified.
1828 Assumes members in this wxVariant list as pending
1831 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
1833 /** Updates composed values of parent non-category properties, recursively.
1834 Returns topmost property updated.
1837 - Must not call SetValue() (as can be called in it).
1839 wxPGProperty
* UpdateParentValues();
1841 /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1843 bool UsesAutoUnspecified() const
1845 return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED
)?true:false;
1848 wxBitmap
* GetValueImage() const
1850 return m_valueBitmap
;
1853 wxVariant
GetAttribute( const wxString
& name
) const;
1856 Returns named attribute, as string, if found.
1858 Otherwise defVal is returned.
1860 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1863 Returns named attribute, as long, if found.
1865 Otherwise defVal is returned.
1867 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1870 Returns named attribute, as double, if found.
1872 Otherwise defVal is returned.
1874 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1876 unsigned int GetDepth() const { return (unsigned int)m_depth
; }
1878 /** Gets flags as a'|' delimited string. Note that flag names are not
1879 prepended with 'wxPG_PROP_'.
1881 String will only be made to include flags combined by this parameter.
1883 wxString
GetFlagsAsString( FlagType flagsMask
) const;
1885 /** Returns position in parent's array. */
1886 unsigned int GetIndexInParent() const
1888 return (unsigned int)m_arrIndex
;
1891 /** Hides or reveals the property.
1893 true for hide, false for reveal.
1895 By default changes are applied recursively. Set this paramter
1896 wxPG_DONT_RECURSE to prevent this.
1898 bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1900 bool IsExpanded() const
1901 { return (!(m_flags
& wxPG_PROP_COLLAPSED
) && GetChildCount()); }
1903 /** Returns true if all parents expanded.
1905 bool IsVisible() const;
1907 bool IsEnabled() const { return !(m_flags
& wxPG_PROP_DISABLED
); }
1909 /** If property's editor is created this forces its recreation.
1910 Useful in SetAttribute etc. Returns true if actually did anything.
1912 bool RecreateEditor();
1914 /** If property's editor is active, then update it's value.
1916 void RefreshEditor();
1918 /** Sets an attribute for this property.
1920 Text identifier of attribute. See @ref propgrid_property_attributes.
1924 void SetAttribute( const wxString
& name
, wxVariant value
);
1926 void SetAttributes( const wxPGAttributeStorage
& attributes
);
1929 Set if user can change the property's value to unspecified by
1930 modifying the value of the editor control (usually by clearing
1931 it). Currently, this can work with following properties:
1932 wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty.
1935 Whether to enable or disable this behavior (it is disabled by
1938 void SetAutoUnspecified( bool enable
= true )
1940 ChangeFlag(wxPG_PROP_AUTO_UNSPECIFIED
, enable
);
1944 Sets property's background colour.
1947 Background colour to use.
1950 Default is wxPG_RECURSE which causes colour to be set recursively.
1951 Omit this flag to only set colour for the property in question
1952 and not any of its children.
1954 void SetBackgroundColour( const wxColour
& colour
,
1955 int flags
= wxPG_RECURSE
);
1958 Sets property's text colour.
1964 Default is wxPG_RECURSE which causes colour to be set recursively.
1965 Omit this flag to only set colour for the property in question
1966 and not any of its children.
1968 void SetTextColour( const wxColour
& colour
,
1969 int flags
= wxPG_RECURSE
);
1971 /** Set default value of a property. Synonymous to
1974 SetAttribute("DefaultValue", value);
1977 void SetDefaultValue( wxVariant
& value
);
1979 /** Sets editor for a property.
1982 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1983 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
1986 For custom editors, use pointer you received from
1987 wxPropertyGrid::RegisterEditorClass().
1989 void SetEditor( const wxPGEditor
* editor
)
1991 m_customEditor
= editor
;
1994 /** Sets editor for a property.
1996 inline void SetEditor( const wxString
& editorName
);
1999 Sets cell information for given column.
2001 void SetCell( int column
, const wxPGCell
& cell
);
2003 /** Sets common value selected for this property. -1 for none.
2005 void SetCommonValue( int commonValue
)
2007 m_commonValue
= commonValue
;
2010 /** Sets flags from a '|' delimited string. Note that flag names are not
2011 prepended with 'wxPG_PROP_'.
2013 void SetFlagsFromString( const wxString
& str
);
2015 /** Sets property's "is it modified?" flag. Affects children recursively.
2017 void SetModifiedStatus( bool modified
)
2019 SetFlagRecursively(wxPG_PROP_MODIFIED
, modified
);
2022 /** Call in OnEvent(), OnButtonClick() etc. to change the property value
2023 based on user input.
2026 This method is const since it doesn't actually modify value, but posts
2027 given variant as pending value, stored in wxPropertyGrid.
2029 void SetValueInEvent( wxVariant value
) const;
2032 Call this to set value of the property.
2034 Unlike methods in wxPropertyGrid, this does not automatically update
2038 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
2039 through validation process and send property change event.
2041 If you need to change property value in event, based on user input, use
2042 SetValueInEvent() instead.
2045 Pointer to list variant that contains child values. Used to
2046 indicate which children should be marked as modified.
2049 Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR, which is
2050 enabled by default).
2052 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
,
2053 int flags
= wxPG_SETVAL_REFRESH_EDITOR
);
2055 /** Set wxBitmap in front of the value. This bitmap may be ignored
2056 by custom cell renderers.
2058 void SetValueImage( wxBitmap
& bmp
);
2060 /** Sets selected choice and changes property value.
2062 Tries to retain value type, although currently if it is not string,
2063 then it is forced to integer.
2065 void SetChoiceSelection( int newValue
);
2067 void SetExpanded( bool expanded
)
2069 if ( !expanded
) m_flags
|= wxPG_PROP_COLLAPSED
;
2070 else m_flags
&= ~wxPG_PROP_COLLAPSED
;
2074 Sets or clears given property flag. Mainly for internal use.
2076 @remarks Setting a property flag never has any side-effect, and is
2077 intended almost exclusively for internal use. So, for
2078 example, if you want to disable a property, call
2079 Enable(false) instead of setting wxPG_PROP_DISABLED flag.
2081 @see HasFlag(), GetFlags()
2083 void ChangeFlag( wxPGPropertyFlags flag
, bool set
)
2092 Sets or clears given property flag, recursively. This function is
2093 primarily intended for internal use.
2097 void SetFlagRecursively( wxPGPropertyFlags flag
, bool set
);
2099 void SetHelpString( const wxString
& helpString
)
2101 m_helpString
= helpString
;
2104 void SetLabel( const wxString
& label
) { m_label
= label
; }
2106 void SetName( const wxString
& newName
);
2109 Changes what sort of parent this property is for its children.
2112 Use one of the following values: wxPG_PROP_MISC_PARENT (for
2113 generic parents), wxPG_PROP_CATEGORY (for categories), or
2114 wxPG_PROP_AGGREGATE (for derived property classes with private
2117 @remarks You generally do not need to call this function.
2119 void SetParentalType( int flag
)
2121 m_flags
&= ~(wxPG_PROP_PROPERTY
|wxPG_PROP_PARENTAL_FLAGS
);
2125 void SetValueToUnspecified()
2127 wxVariant val
; // Create NULL variant
2128 SetValue(val
, NULL
, wxPG_SETVAL_REFRESH_EDITOR
);
2131 // Helper function (for wxPython bindings and such) for settings protected
2133 void SetValuePlain( wxVariant value
)
2138 #if wxUSE_VALIDATORS
2139 /** Sets wxValidator for a property*/
2140 void SetValidator( const wxValidator
& validator
)
2142 m_validator
= wxDynamicCast(validator
.Clone(),wxValidator
);
2145 /** Gets assignable version of property's validator. */
2146 wxValidator
* GetValidator() const
2150 return DoGetValidator();
2152 #endif // wxUSE_VALIDATORS
2154 /** Returns client data (void*) of a property.
2156 void* GetClientData() const
2158 return m_clientData
;
2161 /** Sets client data (void*) of a property.
2163 This untyped client data has to be deleted manually.
2165 void SetClientData( void* clientData
)
2167 m_clientData
= clientData
;
2170 /** Returns client object of a property.
2172 void SetClientObject(wxClientData
* clientObject
)
2174 delete m_clientObject
;
2175 m_clientObject
= clientObject
;
2178 /** Sets managed client object of a property.
2180 wxClientData
*GetClientObject() const { return m_clientObject
; }
2183 Sets new set of choices for the property.
2185 @remarks This operation deselects the property and clears its
2188 bool SetChoices( const wxPGChoices
& choices
);
2190 /** Set max length of text in text editor.
2192 inline bool SetMaxLength( int maxLen
);
2194 /** Call with 'false' in OnSetValue to cancel value changes after all
2195 (ie. cancel 'true' returned by StringToValue() or IntToValue()).
2197 void SetWasModified( bool set
= true )
2199 if ( set
) m_flags
|= wxPG_PROP_WAS_MODIFIED
;
2200 else m_flags
&= ~wxPG_PROP_WAS_MODIFIED
;
2203 const wxString
& GetHelpString() const
2205 return m_helpString
;
2208 // Use, for example, to detect if item is inside collapsed section.
2209 bool IsSomeParent( wxPGProperty
* candidate_parent
) const;
2212 Adapts list variant into proper value using consecutive
2215 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
2217 #if wxPG_COMPATIBILITY_1_4
2219 Adds a private child property.
2221 @deprecated Use AddPrivateChild() instead.
2223 @see AddPrivateChild()
2225 wxDEPRECATED( void AddChild( wxPGProperty
* prop
) );
2229 Adds a private child property. If you use this instead of
2230 wxPropertyGridInterface::Insert() or
2231 wxPropertyGridInterface::AppendIn(), then property's parental
2232 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
2233 words, all properties of this property will become private.
2235 void AddPrivateChild( wxPGProperty
* prop
);
2238 Appends a new child property.
2240 wxPGProperty
* AppendChild( wxPGProperty
* prop
)
2242 return InsertChild(-1, prop
);
2245 /** Returns height of children, recursively, and
2246 by taking expanded/collapsed status into account.
2248 iMax is used when finding property y-positions.
2250 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
2252 /** Returns number of child properties */
2253 unsigned int GetChildCount() const
2255 return (unsigned int) m_children
.size();
2258 /** Returns sub-property at index i. */
2259 wxPGProperty
* Item( unsigned int i
) const
2260 { return m_children
[i
]; }
2262 /** Returns last sub-property.
2264 wxPGProperty
* Last() const { return m_children
.back(); }
2266 /** Returns index of given child property. */
2267 int Index( const wxPGProperty
* p
) const;
2269 // Puts correct indexes to children
2270 void FixIndicesOfChildren( unsigned int starthere
= 0 );
2273 Converts image width into full image offset, with margins.
2275 int GetImageOffset( int imageWidth
) const;
2277 // Returns wxPropertyGridPageState in which this property resides.
2278 wxPropertyGridPageState
* GetParentState() const { return m_parentState
; }
2280 wxPGProperty
* GetItemAtY( unsigned int y
,
2282 unsigned int* nextItemY
) const;
2284 /** Returns property at given virtual y coordinate.
2286 wxPGProperty
* GetItemAtY( unsigned int y
) const;
2288 /** Returns (direct) child property with given name (or NULL if not found).
2290 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
2292 // Returns various display-related information for given column
2293 void GetDisplayInfo( unsigned int column
,
2297 const wxPGCell
** pCell
);
2299 static wxString
* sm_wxPG_LABEL
;
2301 /** This member is public so scripting language bindings
2302 wrapper code can access it freely.
2309 Sets property cell in fashion that reduces number of exclusive
2310 copies of cell data. Used when setting, for instance, same
2311 background colour for a number of properties.
2314 First column to affect.
2317 Last column to affect.
2320 Pre-prepared cell that is used for those which cell data
2321 before this matched unmodCellData.
2324 If unmodCellData did not match, valid cell data from this
2325 is merged into cell (usually generating new exclusive copy
2328 @param unmodCellData
2329 If cell's cell data matches this, its cell is now set to
2332 @param ignoreWithFlags
2333 Properties with any one of these flags are skipped.
2336 If @true, apply this operation recursively in child properties.
2338 void AdaptiveSetCell( unsigned int firstCol
,
2339 unsigned int lastCol
,
2340 const wxPGCell
& preparedCell
,
2341 const wxPGCell
& srcData
,
2342 wxPGCellData
* unmodCellData
,
2343 FlagType ignoreWithFlags
,
2347 Makes sure m_cells has size of column+1 (or more).
2349 void EnsureCells( unsigned int column
);
2351 /** Returns (direct) child property with given name (or NULL if not found),
2355 Start looking for the child at this index.
2358 Does not support scope (ie. Parent.Child notation).
2360 wxPGProperty
* GetPropertyByNameWH( const wxString
& name
,
2361 unsigned int hintIndex
) const;
2363 /** This is used by Insert etc. */
2364 void DoAddChild( wxPGProperty
* prop
,
2366 bool correct_mode
= true );
2368 void DoGenerateComposedValue( wxString
& text
,
2369 int argFlags
= wxPG_VALUE_IS_CURRENT
,
2370 const wxVariantList
* valueOverrides
= NULL
,
2371 wxPGHashMapS2S
* childResults
= NULL
) const;
2373 bool DoHide( bool hide
, int flags
);
2375 void DoSetName(const wxString
& str
) { m_name
= str
; }
2377 /** Deletes all sub-properties. */
2380 bool HasCell( unsigned int column
) const
2382 if ( m_cells
.size() > column
)
2387 void InitAfterAdded( wxPropertyGridPageState
* pageState
,
2388 wxPropertyGrid
* propgrid
);
2390 // Removes child property with given pointer. Does not delete it.
2391 void RemoveChild( wxPGProperty
* p
);
2393 void DoEnable( bool enable
);
2395 void DoPreAddChild( int index
, wxPGProperty
* prop
);
2397 void SetParentState( wxPropertyGridPageState
* pstate
)
2398 { m_parentState
= pstate
; }
2400 void SetFlag( wxPGPropertyFlags flag
)
2403 // NB: While using wxPGPropertyFlags here makes it difficult to
2404 // combine different flags, it usefully prevents user from
2405 // using incorrect flags (say, wxWindow styles).
2409 void ClearFlag( FlagType flag
) { m_flags
&= ~(flag
); }
2411 // Called when the property is being removed from the grid and/or
2412 // page state (but *not* when it is also deleted).
2413 void OnDetached(wxPropertyGridPageState
* state
,
2414 wxPropertyGrid
* propgrid
);
2416 // Call after fixed sub-properties added/removed after creation.
2417 // if oldSelInd >= 0 and < new max items, then selection is
2419 void SubPropsChanged( int oldSelInd
= -1 );
2421 int GetY2( int lh
) const;
2425 wxPGProperty
* m_parent
;
2426 wxPropertyGridPageState
* m_parentState
;
2428 wxClientData
* m_clientObject
;
2430 // Overrides editor returned by property class
2431 const wxPGEditor
* m_customEditor
;
2432 #if wxUSE_VALIDATORS
2433 // Editor is going to get this validator
2434 wxValidator
* m_validator
;
2436 // Show this in front of the value
2438 // TODO: Can bitmap be implemented with wxPGCell?
2439 wxBitmap
* m_valueBitmap
;
2442 wxPGAttributeStorage m_attributes
;
2443 wxArrayPGProperty m_children
;
2445 // Extended cell information
2446 wxVector
<wxPGCell
> m_cells
;
2448 // Choices shown in drop-down list of editor control.
2449 wxPGChoices m_choices
;
2451 // Help shown in statusbar or help box.
2452 wxString m_helpString
;
2454 // Index in parent's property array.
2455 unsigned int m_arrIndex
;
2457 // If not -1, then overrides m_value
2462 // Maximum length (mainly for string properties). Could be in some sort of
2463 // wxBaseStringProperty, but currently, for maximum flexibility and
2464 // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
2465 // so short int will fit in just fine.
2468 // Root has 0, categories etc. at that level 1, etc.
2469 unsigned char m_depth
;
2471 // m_depthBgCol indicates width of background colour between margin and item
2472 // (essentially this is category's depth, if none then equals m_depth).
2473 unsigned char m_depthBgCol
;
2476 // Called in constructors.
2478 void Init( const wxString
& label
, const wxString
& name
);
2481 // -----------------------------------------------------------------------
2484 // Property class declaration helper macros
2485 // (wxPGRootPropertyClass and wxPropertyCategory require this).
2488 #define WX_PG_DECLARE_DOGETEDITORCLASS \
2489 virtual const wxPGEditor* DoGetEditorClass() const;
2491 #ifndef WX_PG_DECLARE_PROPERTY_CLASS
2492 #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
2494 DECLARE_DYNAMIC_CLASS(CLASSNAME) \
2495 WX_PG_DECLARE_DOGETEDITORCLASS \
2499 // Implements sans constructor function. Also, first arg is class name, not
2501 #define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
2502 const wxPGEditor* PROPNAME::DoGetEditorClass() const \
2504 return wxPGEditor_##EDITOR; \
2507 // -----------------------------------------------------------------------
2509 /** @class wxPGRootProperty
2511 Root parent property.
2513 class WXDLLIMPEXP_PROPGRID wxPGRootProperty
: public wxPGProperty
2516 WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty
)
2520 wxPGRootProperty( const wxString
& name
= wxS("<Root>") );
2521 virtual ~wxPGRootProperty();
2523 virtual bool StringToValue( wxVariant
&, const wxString
&, int ) const
2531 // -----------------------------------------------------------------------
2533 /** @class wxPropertyCategory
2535 Category (caption) property.
2537 class WXDLLIMPEXP_PROPGRID wxPropertyCategory
: public wxPGProperty
2539 friend class wxPropertyGrid
;
2540 friend class wxPropertyGridPageState
;
2541 WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory
)
2544 /** Default constructor is only used in special cases. */
2545 wxPropertyCategory();
2547 wxPropertyCategory( const wxString
& label
,
2548 const wxString
& name
= wxPG_LABEL
);
2549 ~wxPropertyCategory();
2551 int GetTextExtent( const wxWindow
* wnd
, const wxFont
& font
) const;
2553 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
) const;
2554 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
2557 void SetTextColIndex( unsigned int colInd
)
2558 { m_capFgColIndex
= (wxByte
) colInd
; }
2559 unsigned int GetTextColIndex() const
2560 { return (unsigned int) m_capFgColIndex
; }
2562 void CalculateTextExtent( wxWindow
* wnd
, const wxFont
& font
);
2564 int m_textExtent
; // pre-calculated length of text
2565 wxByte m_capFgColIndex
; // caption text colour index
2571 // -----------------------------------------------------------------------
2573 #endif // wxUSE_PROPGRID
2575 #endif // _WX_PROPGRID_PROPERTY_H_