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_
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 wxPGPropertyFlags
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 ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \
503 wxPG_PROP_CATEGORY | \
504 wxPG_PROP_MISC_PARENT))
509 // Combination of flags that can be stored by GetFlagsAsString
510 #define wxPG_STRING_STORED_FLAGS \
511 (wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED)
513 // -----------------------------------------------------------------------
516 @section propgrid_property_attributes wxPropertyGrid Property Attribute
519 wxPGProperty::SetAttribute() and
520 wxPropertyGridInterface::SetPropertyAttribute() accept one of these as
521 attribute name argument.
523 You can use strings instead of constants. However, some of these
524 constants are redefined to use cached strings which may reduce
525 your binary size by some amount.
530 /** Set default value for property.
532 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
534 /** Universal, int or double. Minimum value for numeric properties.
536 #define wxPG_ATTR_MIN wxS("Min")
538 /** Universal, int or double. Maximum value for numeric properties.
540 #define wxPG_ATTR_MAX wxS("Max")
542 /** Universal, string. When set, will be shown as text after the displayed
543 text value. Alternatively, if third column is enabled, text will be shown
544 there (for any type of property).
546 #define wxPG_ATTR_UNITS wxS("Units")
548 /** When set, will be shown as 'greyed' text in property's value cell when
549 the actual displayed value is blank.
551 #define wxPG_ATTR_HINT wxS("Hint")
553 #if wxPG_COMPATIBILITY_1_4
555 @deprecated Use "Hint" (wxPG_ATTR_HINT) instead.
557 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
560 /** Universal, wxArrayString. Set to enable auto-completion in any
561 wxTextCtrl-based property editor.
563 #define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
565 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
566 Default value is False.
568 When set to True, bool property will use check box instead of a
569 combo box as its editor control. If you set this attribute
570 for a wxFlagsProperty, it is automatically applied to child
573 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
575 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
576 Default value is False.
578 Set to True for the bool property to cycle value on double click
579 (instead of showing the popup listbox). If you set this attribute
580 for a wxFlagsProperty, it is automatically applied to child
583 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
586 wxFloatProperty (and similar) specific, int, default -1.
588 Sets the (max) precision used when floating point value is rendered as
589 text. The default -1 means infinite precision.
591 #define wxPG_FLOAT_PRECISION wxS("Precision")
594 The text will be echoed as asterisks (wxTE_PASSWORD will be passed to
597 #define wxPG_STRING_PASSWORD wxS("Password")
599 /** Define base used by a wxUIntProperty. Valid constants are
600 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
601 (lowercase characters).
603 #define wxPG_UINT_BASE wxS("Base")
605 /** Define prefix rendered to wxUIntProperty. Accepted constants
606 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
607 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
610 #define wxPG_UINT_PREFIX wxS("Prefix")
613 wxFileProperty/wxImageFileProperty specific, wxChar*, default is
615 Sets the wildcard used in the triggered wxFileDialog. Format is the same.
617 #define wxPG_FILE_WILDCARD wxS("Wildcard")
619 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
620 When 0, only the file name is shown (i.e. drive and directory are hidden).
622 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
624 /** Specific to wxFileProperty and derived properties, wxString, default empty.
625 If set, then the filename is shown relative to the given path string.
627 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
630 Specific to wxFileProperty and derived properties, wxString, default is
633 Sets the initial path of where to look for files.
635 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
637 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
638 Sets a specific title for the dir dialog.
640 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
642 /** Specific to wxDirProperty, wxString, default is empty.
643 Sets a specific message for the dir dialog.
645 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
648 wxArrayStringProperty's string delimiter character. If this is aquotation
649 mark or hyphen, then strings will be quoted instead (with given
652 Default delimiter is quotation mark.
654 #define wxPG_ARRAY_DELIMITER wxS("Delimiter")
656 /** Sets displayed date format for wxDateProperty.
658 #define wxPG_DATE_FORMAT wxS("DateFormat")
660 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
661 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
663 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
665 /** SpinCtrl editor, int or double. How much number changes when button is
666 pressed (or up/down on keybard).
668 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
670 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
672 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
675 wxMultiChoiceProperty, int.
676 If 0, no user strings allowed. If 1, user strings appear before list
677 strings. If 2, user strings appear after list string.
679 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
682 wxColourProperty and its kind, int, default 1.
684 Setting this attribute to 0 hides custom colour from property's list of
687 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
692 // Redefine attribute macros to use cached strings
693 #undef wxPG_ATTR_DEFAULT_VALUE
694 #define wxPG_ATTR_DEFAULT_VALUE wxPGGlobalVars->m_strDefaultValue
696 #define wxPG_ATTR_MIN wxPGGlobalVars->m_strMin
698 #define wxPG_ATTR_MAX wxPGGlobalVars->m_strMax
699 #undef wxPG_ATTR_UNITS
700 #define wxPG_ATTR_UNITS wxPGGlobalVars->m_strUnits
701 #undef wxPG_ATTR_HINT
702 #define wxPG_ATTR_HINT wxPGGlobalVars->m_strHint
703 #if wxPG_COMPATIBILITY_1_4
704 #undef wxPG_ATTR_INLINE_HELP
705 #define wxPG_ATTR_INLINE_HELP wxPGGlobalVars->m_strInlineHelp
708 // -----------------------------------------------------------------------
710 /** @class wxPGChoiceEntry
711 Data of a single wxPGChoices choice.
713 class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry
: public wxPGCell
717 wxPGChoiceEntry(const wxPGChoiceEntry
& other
)
720 m_value
= other
.m_value
;
722 wxPGChoiceEntry( const wxString
& label
,
723 int value
= wxPG_INVALID_VALUE
)
724 : wxPGCell(), m_value(value
)
729 virtual ~wxPGChoiceEntry() { }
731 void SetValue( int value
) { m_value
= value
; }
732 int GetValue() const { return m_value
; }
734 wxPGChoiceEntry
& operator=( const wxPGChoiceEntry
& other
)
736 if ( this != &other
)
740 m_value
= other
.m_value
;
749 typedef void* wxPGChoicesId
;
751 class WXDLLIMPEXP_PROPGRID wxPGChoicesData
: public wxObjectRefData
753 friend class wxPGChoices
;
755 // Constructor sets m_refCount to 1.
758 void CopyDataFrom( wxPGChoicesData
* data
);
760 wxPGChoiceEntry
& Insert( int index
, const wxPGChoiceEntry
& item
);
762 // Delete all entries
765 unsigned int GetCount() const
767 return (unsigned int) m_items
.size();
770 const wxPGChoiceEntry
& Item( unsigned int i
) const
772 wxASSERT_MSG( i
< GetCount(), "invalid index" );
776 wxPGChoiceEntry
& Item( unsigned int i
)
778 wxASSERT_MSG( i
< GetCount(), "invalid index" );
783 wxVector
<wxPGChoiceEntry
> m_items
;
785 virtual ~wxPGChoicesData();
788 #define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL)
791 /** @class wxPGChoices
793 Helper class for managing choices of wxPropertyGrid properties.
794 Each entry can have label, value, bitmap, text colour, and background
797 wxPGChoices uses reference counting, similar to other wxWidgets classes.
798 This means that assignment operator and copy constructor only copy the
799 reference and not the actual data. Use Copy() member function to create a
802 @remarks If you do not specify value for entry, index is used.
807 class WXDLLIMPEXP_PROPGRID wxPGChoices
810 typedef long ValArrItem
;
812 /** Default constructor. */
819 Copy constructor, uses reference counting. To create a real copy,
820 use Copy() member function instead.
822 wxPGChoices( const wxPGChoices
& a
)
824 if ( a
.m_data
!= wxPGChoicesEmptyData
)
838 Values for choices. If NULL, indexes are used.
840 wxPGChoices( const wxChar
* const* labels
, const long* values
= NULL
)
853 Values for choices. If empty, indexes are used.
855 wxPGChoices( const wxArrayString
& labels
,
856 const wxArrayInt
& values
= wxArrayInt() )
862 /** Simple interface constructor. */
863 wxPGChoices( wxPGChoicesData
* data
)
879 If did not have own copies, creates them now. If was empty, identical
880 to set except that creates copies.
883 Labels for added choices.
886 Values for added choices. If empty, relevant entry indexes are used.
888 void Add( const wxChar
* const* labels
, const ValArrItem
* values
= NULL
);
890 /** Version that works with wxArrayString and wxArrayInt. */
891 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
= wxArrayInt() );
894 Adds a single choice.
897 Label for added choice.
900 Value for added choice. If unspecified, index is used.
902 wxPGChoiceEntry
& Add( const wxString
& label
,
903 int value
= wxPG_INVALID_VALUE
);
905 /** Adds a single item, with bitmap. */
906 wxPGChoiceEntry
& Add( const wxString
& label
,
907 const wxBitmap
& bitmap
,
908 int value
= wxPG_INVALID_VALUE
);
910 /** Adds a single item with full entry information. */
911 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
913 return Insert(entry
, -1);
916 /** Adds single item. */
917 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
,
918 int value
= wxPG_INVALID_VALUE
);
921 Assigns choices data, using reference counting. To create a real copy,
922 use Copy() member function instead.
924 void Assign( const wxPGChoices
& a
)
926 AssignData(a
.m_data
);
929 void AssignData( wxPGChoicesData
* data
);
931 /** Delete all choices. */
935 Returns a real copy of the choices.
937 wxPGChoices
Copy() const
941 dst
.m_data
->CopyDataFrom(m_data
);
947 if ( m_data
== wxPGChoicesEmptyData
)
948 m_data
= new wxPGChoicesData();
951 /** Gets a unsigned number identifying this list. */
952 wxPGChoicesId
GetId() const { return (wxPGChoicesId
) m_data
; };
954 const wxString
& GetLabel( unsigned int ind
) const
956 return Item(ind
).GetText();
959 unsigned int GetCount () const
964 return m_data
->GetCount();
967 int GetValue( unsigned int ind
) const { return Item(ind
).GetValue(); }
969 /** Returns array of values matching the given strings. Unmatching strings
970 result in wxPG_INVALID_VALUE entry in array.
972 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
974 /** Returns array of indices matching given strings. Unmatching strings
975 are added to 'unmatched', if not NULL.
977 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
978 wxArrayString
* unmatched
= NULL
) const;
980 int Index( const wxString
& str
) const;
981 int Index( int val
) const;
983 /** Inserts single item. */
984 wxPGChoiceEntry
& Insert( const wxString
& label
,
986 int value
= wxPG_INVALID_VALUE
);
988 /** Inserts a single item with full entry information. */
989 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
991 /** Returns false if this is a constant empty set of choices,
992 which should not be modified.
996 return ( m_data
!= wxPGChoicesEmptyData
);
999 const wxPGChoiceEntry
& Item( unsigned int i
) const
1002 return m_data
->Item(i
);
1005 wxPGChoiceEntry
& Item( unsigned int i
)
1008 return m_data
->Item(i
);
1011 /** Removes count items starting at position nIndex. */
1012 void RemoveAt(size_t nIndex
, size_t count
= 1);
1014 /** Does not create copies for itself.
1017 void Set( const wxChar
* const* labels
, const long* values
= NULL
)
1023 /** Version that works with wxArrayString and wxArrayInt. */
1024 void Set( const wxArrayString
& labels
,
1025 const wxArrayInt
& values
= wxArrayInt() )
1034 // Creates exclusive copy of current choices
1035 void AllocExclusive();
1037 // Returns data, increases refcount.
1038 wxPGChoicesData
* GetData()
1040 wxASSERT( m_data
->GetRefCount() != -1 );
1045 // Returns plain data ptr - no refcounting stuff is done.
1046 wxPGChoicesData
* GetDataPtr() const { return m_data
; }
1048 // Changes ownership of data to you.
1049 wxPGChoicesData
* ExtractData()
1051 wxPGChoicesData
* data
= m_data
;
1052 m_data
= wxPGChoicesEmptyData
;
1056 wxArrayString
GetLabels() const;
1058 void operator= (const wxPGChoices
& a
)
1061 AssignData(a
.m_data
);
1064 wxPGChoiceEntry
& operator[](unsigned int i
)
1069 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1075 wxPGChoicesData
* m_data
;
1081 // -----------------------------------------------------------------------
1083 /** @class wxPGProperty
1085 wxPGProperty is base class for all wxPropertyGrid properties.
1087 NB: Full class overview is now only present in
1088 interface/wx/propgrid/property.h.
1090 @library{wxpropgrid}
1093 class WXDLLIMPEXP_PROPGRID wxPGProperty
: public wxObject
1095 friend class wxPropertyGrid
;
1096 friend class wxPropertyGridInterface
;
1097 friend class wxPropertyGridPageState
;
1098 friend class wxPropertyGridPopulator
;
1099 friend class wxStringProperty
; // Proper "<composed>" support requires this
1101 DECLARE_ABSTRACT_CLASS(wxPGProperty
)
1103 typedef wxUint32 FlagType
;
1106 Default constructor.
1113 All non-abstract property classes should have a constructor with
1114 the same first two arguments as this one.
1116 wxPGProperty( const wxString
& label
, const wxString
& name
);
1120 It is customary for derived properties to implement this.
1122 virtual ~wxPGProperty();
1124 /** This virtual function is called after m_value has been set.
1127 - If m_value was set to Null variant (ie. unspecified value),
1128 OnSetValue() will not be called.
1129 - m_value may be of any variant type. Typically properties internally
1130 support only one variant type, and as such OnSetValue() provides a
1131 good opportunity to convert
1132 supported values into internal type.
1133 - Default implementation does nothing.
1135 virtual void OnSetValue();
1137 /** Override this to return something else than m_value as the value.
1139 virtual wxVariant
DoGetValue() const { return m_value
; }
1141 /** Implement this function in derived class to check the value.
1142 Return true if it is ok. Returning false prevents property change events
1146 - Default implementation always returns true.
1148 virtual bool ValidateValue( wxVariant
& value
,
1149 wxPGValidationInfo
& validationInfo
) const;
1152 Converts text into wxVariant value appropriate for this property.
1155 On function entry this is the old value (should not be wxNullVariant
1156 in normal cases). Translated value must be assigned back to it.
1159 Text to be translated into variant.
1162 If wxPG_FULL_VALUE is set, returns complete, storable value instead
1163 of displayable one (they may be different).
1164 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
1165 composite property string value (as generated by ValueToString()
1166 called with this same flag).
1168 @return Returns @true if resulting wxVariant value was different.
1170 @remarks Default implementation converts semicolon delimited tokens into
1171 child values. Only works for properties with children.
1173 You might want to take into account that m_value is Null variant
1174 if property value is unspecified (which is usually only case if
1175 you explicitly enabled that sort behavior).
1177 virtual bool StringToValue( wxVariant
& variant
,
1178 const wxString
& text
,
1179 int argFlags
= 0 ) const;
1182 Converts integer (possibly a choice selection) into wxVariant value
1183 appropriate for this property.
1186 On function entry this is the old value (should not be wxNullVariant
1187 in normal cases). Translated value must be assigned back to it.
1190 Integer to be translated into variant.
1193 If wxPG_FULL_VALUE is set, returns complete, storable value instead
1196 @return Returns @true if resulting wxVariant value was different.
1199 - If property is not supposed to use choice or spinctrl or other editor
1200 with int-based value, it is not necessary to implement this method.
1201 - Default implementation simply assign given int to m_value.
1202 - If property uses choice control, and displays a dialog on some choice
1203 items, then it is preferred to display that dialog in IntToValue
1205 - You might want to take into account that m_value is Null variant if
1206 property value is unspecified (which is usually only case if you
1207 explicitly enabled that sort behavior).
1209 virtual bool IntToValue( wxVariant
& value
,
1211 int argFlags
= 0 ) const;
1214 Converts property value into a text representation.
1217 Value to be converted.
1220 If 0 (default value), then displayed string is returned.
1221 If wxPG_FULL_VALUE is set, returns complete, storable string value
1222 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1223 string value that must be editable in textctrl. If
1224 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1225 display as a part of string property's composite text
1228 @remarks Default implementation calls GenerateComposedValue().
1230 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
= 0 ) const;
1232 /** Converts string to a value, and if successful, calls SetValue() on it.
1233 Default behavior is to do nothing.
1235 String to get the value from.
1237 true if value was changed.
1239 bool SetValueFromString( const wxString
& text
, int flags
= wxPG_PROGRAMMATIC_VALUE
);
1241 /** Converts integer to a value, and if succesful, calls SetValue() on it.
1242 Default behavior is to do nothing.
1244 Int to get the value from.
1246 If has wxPG_FULL_VALUE, then the value given is a actual value and
1249 True if value was changed.
1251 bool SetValueFromInt( long value
, int flags
= 0 );
1254 Returns size of the custom painted image in front of property.
1256 This method must be overridden to return non-default value if
1257 OnCustomPaint is to be called.
1259 Normally -1, but can be an index to the property's list of items.
1261 - Default behavior is to return wxSize(0,0), which means no image.
1262 - Default image width or height is indicated with dimension -1.
1263 - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1).
1265 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
1268 Events received by editor widgets are processed here.
1270 Note that editor class usually processes most events. Some, such as
1271 button press events of TextCtrlAndButton class, can be handled here.
1272 Also, if custom handling for regular events is desired, then that can
1273 also be done (for example, wxSystemColourProperty custom handles
1274 wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
1275 'custom' selection is made).
1277 If the event causes value to be changed, SetValueInEvent()
1278 should be called to set the new value.
1283 Should return true if any changes in value should be reported.
1285 If property uses choice control, and displays a dialog on some choice
1286 items, then it is preferred to display that dialog in IntToValue
1289 virtual bool OnEvent( wxPropertyGrid
* propgrid
,
1290 wxWindow
* wnd_primary
,
1294 Called after value of a child property has been altered. Must return
1295 new value of the whole property (after any alterations warrented by
1298 Note that this function is usually called at the time that value of
1299 this property, or given child property, is still pending for change,
1300 and as such, result of GetValue() or m_value should not be relied
1303 Sample pseudo-code implementation:
1306 wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
1308 wxVariant& childValue ) const
1310 // Acquire reference to actual type of data stored in variant
1311 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
1312 // were used to create the variant class).
1313 T& data = TFromVariant(thisValue);
1315 // Copy childValue into data.
1316 switch ( childIndex )
1319 data.SetSubProp1( childvalue.GetLong() );
1322 data.SetSubProp2( childvalue.GetString() );
1327 // Return altered data
1333 Value of this property. Changed value should be returned (in
1334 previous versions of wxPropertyGrid it was only necessary to
1335 write value back to this argument).
1337 Index of child changed (you can use Item(childIndex) to get
1340 (Pending) value of the child property.
1343 Modified value of the whole property.
1345 virtual wxVariant
ChildChanged( wxVariant
& thisValue
,
1347 wxVariant
& childValue
) const;
1349 /** Returns pointer to an instance of used editor.
1351 virtual const wxPGEditor
* DoGetEditorClass() const;
1353 /** Returns pointer to the wxValidator that should be used
1354 with the editor of this property (NULL for no validator).
1355 Setting validator explicitly via SetPropertyValidator
1358 In most situations, code like this should work well
1359 (macros are used to maintain one actual validator instance,
1360 so on the second call the function exits within the first
1365 wxValidator* wxMyPropertyClass::DoGetValidator () const
1367 WX_PG_DOGETVALIDATOR_ENTRY()
1369 wxMyValidator* validator = new wxMyValidator(...);
1371 ... prepare validator...
1373 WX_PG_DOGETVALIDATOR_EXIT(validator)
1379 You can get common filename validator by returning
1380 wxFileProperty::GetClassValidator(). wxDirProperty,
1381 for example, uses it.
1383 virtual wxValidator
* DoGetValidator () const;
1386 Override to paint an image in front of the property value text or
1387 drop-down list item (but only if wxPGProperty::OnMeasureImage is
1388 overridden as well).
1390 If property's OnMeasureImage() returns size that has height != 0 but
1391 less than row height ( < 0 has special meanings), wxPropertyGrid calls
1392 this method to draw a custom image in a limited area in front of the
1393 editor control or value text/graphics, and if control has drop-down
1394 list, then the image is drawn there as well (even in the case
1395 OnMeasureImage() returned higher height than row height).
1397 NOTE: Following applies when OnMeasureImage() returns a "flexible"
1398 height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
1399 height items: If rect.x is < 0, then this is a measure item call, which
1400 means that dc is invalid and only thing that should be done is to set
1401 paintdata.m_drawnHeight to the height of the image of item at index
1402 paintdata.m_choiceItem. This call may be done even as often as once
1403 every drop-down popup show.
1408 Box reserved for custom graphics. Includes surrounding rectangle,
1409 if any. If x is < 0, then this is a measure item call (see above).
1411 wxPGPaintData structure with much useful data.
1414 - You can actually exceed rect width, but if you do so then
1415 paintdata.m_drawnWidth must be set to the full width drawn in
1417 - Due to technical reasons, rect's height will be default even if
1418 custom height was reported during measure call.
1419 - Brush is guaranteed to be default background colour. It has been
1420 already used to clear the background of area being painted. It
1422 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper
1423 colour) pen for drawing framing rectangle. It can be changed as
1426 @see ValueToString()
1428 virtual void OnCustomPaint( wxDC
& dc
,
1430 wxPGPaintData
& paintdata
);
1433 Returns used wxPGCellRenderer instance for given property column
1436 Default implementation returns editor's renderer for all columns.
1438 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
1440 /** Returns which choice is currently selected. Only applies to properties
1443 Needs to reimplemented in derived class if property value does not
1444 map directly to a choice. Integer as index, bool, and string usually do.
1446 virtual int GetChoiceSelection() const;
1449 Refresh values of child properties.
1451 Automatically called after value is set.
1453 virtual void RefreshChildren();
1456 Reimplement this member function to add special handling for
1457 attributes of this property.
1459 @return Return @false to have the attribute automatically stored in
1460 m_attributes. Default implementation simply does that and
1463 @remarks To actually set property attribute values from the
1464 application, use wxPGProperty::SetAttribute() instead.
1466 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
1468 /** Returns value of an attribute.
1470 Override if custom handling of attributes is needed.
1472 Default implementation simply return NULL variant.
1474 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
1476 /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
1477 used when user presses the (optional) button next to the editor control;
1479 Default implementation returns NULL (ie. no action is generated when
1482 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
1485 Called whenever validation has failed with given pending value.
1487 @remarks If you implement this in your custom property class, please
1488 remember to call the baser implementation as well, since they
1489 may use it to revert property into pre-change state.
1491 virtual void OnValidationFailure( wxVariant
& pendingValue
);
1493 /** Append a new choice to property's list of choices.
1495 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
)
1497 return InsertChoice(label
, wxNOT_FOUND
, value
);
1501 Returns true if children of this property are component values (for
1502 instance, points size, face name, and is_underlined are component
1505 bool AreChildrenComponents() const
1507 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
1514 Deletes children of the property.
1516 void DeleteChildren();
1519 Removes entry from property's wxPGChoices and editor control (if it is
1522 If selected item is deleted, then the value is set to unspecified.
1524 void DeleteChoice( int index
);
1527 Enables or disables the property. Disabled property usually appears
1528 as having grey text.
1531 If @false, property is disabled instead.
1533 @see wxPropertyGridInterface::EnableProperty()
1535 void Enable( bool enable
= true );
1538 Call to enable or disable usage of common value (integer value that can
1539 be selected for properties instead of their normal values) for this
1542 Common values are disabled by the default for all properties.
1544 void EnableCommonValue( bool enable
= true )
1546 if ( enable
) SetFlag( wxPG_PROP_USES_COMMON_VALUE
);
1547 else ClearFlag( wxPG_PROP_USES_COMMON_VALUE
);
1551 Composes text from values of child properties.
1553 wxString
GenerateComposedValue() const
1556 DoGenerateComposedValue(s
);
1560 /** Returns property's label. */
1561 const wxString
& GetLabel() const { return m_label
; }
1563 /** Returns property's name with all (non-category, non-root) parents. */
1564 wxString
GetName() const;
1567 Returns property's base name (ie parent's name is not added in any
1570 const wxString
& GetBaseName() const { return m_name
; }
1572 /** Returns read-only reference to property's list of choices.
1574 const wxPGChoices
& GetChoices() const
1579 /** Returns coordinate to the top y of the property. Note that the
1580 position of scrollbars is not taken into account.
1584 wxVariant
GetValue() const
1586 return DoGetValue();
1589 /** Returns reference to the internal stored value. GetValue is preferred
1590 way to get the actual value, since GetValueRef ignores DoGetValue,
1591 which may override stored value.
1593 wxVariant
& GetValueRef()
1598 const wxVariant
& GetValueRef() const
1603 // Helper function (for wxPython bindings and such) for settings protected
1605 wxVariant
GetValuePlain() const
1610 /** Returns text representation of property's value.
1613 If 0 (default value), then displayed string is returned.
1614 If wxPG_FULL_VALUE is set, returns complete, storable string value
1615 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1616 string value that must be editable in textctrl. If
1617 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1618 display as a part of string property's composite text
1621 @remarks In older versions, this function used to be overridden to convert
1622 property's value into a string representation. This function is
1623 now handled by ValueToString(), and overriding this function now
1624 will result in run-time assertion failure.
1626 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
1628 /** Synonymous to GetValueAsString().
1630 @deprecated Use GetValueAsString() instead.
1632 @see GetValueAsString()
1634 wxDEPRECATED( wxString
GetValueString( int argFlags
= 0 ) const );
1637 Returns wxPGCell of given column.
1639 @remarks const version of this member function returns 'default'
1640 wxPGCell object if the property itself didn't hold
1643 const wxPGCell
& GetCell( unsigned int column
) const;
1646 Returns wxPGCell of given column, creating one if necessary.
1648 wxPGCell
& GetCell( unsigned int column
)
1650 return GetOrCreateCell(column
);
1654 Returns wxPGCell of given column, creating one if necessary.
1656 wxPGCell
& GetOrCreateCell( unsigned int column
);
1658 /** Return number of displayed common values for this property.
1660 int GetDisplayedCommonValueCount() const;
1662 wxString
GetDisplayedString() const
1664 return GetValueAsString(0);
1668 Returns property's hint text (shown in empty value cell).
1670 inline wxString
GetHintText() const;
1672 /** Returns property grid where property lies. */
1673 wxPropertyGrid
* GetGrid() const;
1675 /** Returns owner wxPropertyGrid, but only if one is currently on a page
1676 displaying this property. */
1677 wxPropertyGrid
* GetGridIfDisplayed() const;
1679 /** Returns highest level non-category, non-root parent. Useful when you
1680 have nested wxCustomProperties/wxParentProperties.
1682 Thus, if immediate parent is root or category, this will return the
1685 wxPGProperty
* GetMainParent() const;
1687 /** Return parent of property */
1688 wxPGProperty
* GetParent() const { return m_parent
; }
1690 /** Returns true if property has editable wxTextCtrl when selected.
1693 Altough disabled properties do not displayed editor, they still
1694 return True here as being disabled is considered a temporary
1695 condition (unlike being read-only or having limited editing enabled).
1697 bool IsTextEditable() const;
1699 bool IsValueUnspecified() const
1701 return m_value
.IsNull();
1705 Returns non-zero if property has given flag set.
1707 @see propgrid_propflags
1709 FlagType
HasFlag( wxPGPropertyFlags flag
) const
1711 return ( m_flags
& flag
);
1714 /** Returns comma-delimited string of property attributes.
1716 const wxPGAttributeStorage
& GetAttributes() const
1718 return m_attributes
;
1721 /** Returns m_attributes as list wxVariant.
1723 wxVariant
GetAttributesAsList() const;
1726 Returns property flags.
1728 FlagType
GetFlags() const
1733 const wxPGEditor
* GetEditorClass() const;
1735 wxString
GetValueType() const
1737 return m_value
.GetType();
1740 /** Returns editor used for given column. NULL for no editor.
1742 const wxPGEditor
* GetColumnEditor( int column
) const
1745 return GetEditorClass();
1750 /** Returns common value selected for this property. -1 for none.
1752 int GetCommonValue() const
1754 return m_commonValue
;
1757 /** Returns true if property has even one visible child.
1759 bool HasVisibleChildren() const;
1762 Use this member function to add independent (ie. regular) children to
1765 @return Inserted childProperty.
1767 @remarks wxPropertyGrid is not automatically refreshed by this
1770 @see AddPrivateChild()
1772 wxPGProperty
* InsertChild( int index
, wxPGProperty
* childProperty
);
1774 /** Inserts a new choice to property's list of choices.
1776 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1779 Returns true if this property is actually a wxPropertyCategory.
1781 bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY
)?true:false; }
1783 /** Returns true if this property is actually a wxRootProperty.
1785 bool IsRoot() const { return (m_parent
== NULL
); }
1787 /** Returns true if this is a sub-property. */
1788 bool IsSubProperty() const
1790 wxPGProperty
* parent
= (wxPGProperty
*)m_parent
;
1791 if ( parent
&& !parent
->IsCategory() )
1796 /** Returns last visible sub-property, recursively.
1798 const wxPGProperty
* GetLastVisibleSubItem() const;
1800 wxVariant
GetDefaultValue() const;
1802 int GetMaxLength() const
1804 return (int) m_maxLen
;
1808 Determines, recursively, if all children are not unspecified.
1811 Assumes members in this wxVariant list as pending
1814 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
1816 /** Updates composed values of parent non-category properties, recursively.
1817 Returns topmost property updated.
1820 - Must not call SetValue() (as can be called in it).
1822 wxPGProperty
* UpdateParentValues();
1824 /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1826 bool UsesAutoUnspecified() const
1828 return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED
)?true:false;
1831 wxBitmap
* GetValueImage() const
1833 return m_valueBitmap
;
1836 wxVariant
GetAttribute( const wxString
& name
) const;
1839 Returns named attribute, as string, if found.
1841 Otherwise defVal is returned.
1843 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1846 Returns named attribute, as long, if found.
1848 Otherwise defVal is returned.
1850 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1853 Returns named attribute, as double, if found.
1855 Otherwise defVal is returned.
1857 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1859 unsigned int GetDepth() const { return (unsigned int)m_depth
; }
1861 /** Gets flags as a'|' delimited string. Note that flag names are not
1862 prepended with 'wxPG_PROP_'.
1864 String will only be made to include flags combined by this parameter.
1866 wxString
GetFlagsAsString( FlagType flagsMask
) const;
1868 /** Returns position in parent's array. */
1869 unsigned int GetIndexInParent() const
1871 return (unsigned int)m_arrIndex
;
1874 /** Hides or reveals the property.
1876 true for hide, false for reveal.
1878 By default changes are applied recursively. Set this paramter
1879 wxPG_DONT_RECURSE to prevent this.
1881 bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1883 bool IsExpanded() const
1884 { return (!(m_flags
& wxPG_PROP_COLLAPSED
) && GetChildCount()); }
1886 /** Returns true if all parents expanded.
1888 bool IsVisible() const;
1890 bool IsEnabled() const { return !(m_flags
& wxPG_PROP_DISABLED
); }
1892 /** If property's editor is created this forces its recreation.
1893 Useful in SetAttribute etc. Returns true if actually did anything.
1895 bool RecreateEditor();
1897 /** If property's editor is active, then update it's value.
1899 void RefreshEditor();
1901 /** Sets an attribute for this property.
1903 Text identifier of attribute. See @ref propgrid_property_attributes.
1907 void SetAttribute( const wxString
& name
, wxVariant value
);
1909 void SetAttributes( const wxPGAttributeStorage
& attributes
);
1912 Sets property's background colour.
1915 Background colour to use.
1918 Default is wxPG_RECURSE which causes colour to be set recursively.
1919 Omit this flag to only set colour for the property in question
1920 and not any of its children.
1922 void SetBackgroundColour( const wxColour
& colour
,
1923 int flags
= wxPG_RECURSE
);
1926 Sets property's text colour.
1932 Default is wxPG_RECURSE which causes colour to be set recursively.
1933 Omit this flag to only set colour for the property in question
1934 and not any of its children.
1936 void SetTextColour( const wxColour
& colour
,
1937 int flags
= wxPG_RECURSE
);
1939 /** Set default value of a property. Synonymous to
1942 SetAttribute("DefaultValue", value);
1945 void SetDefaultValue( wxVariant
& value
);
1947 /** Sets editor for a property.
1950 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1951 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
1954 For custom editors, use pointer you received from
1955 wxPropertyGrid::RegisterEditorClass().
1957 void SetEditor( const wxPGEditor
* editor
)
1959 m_customEditor
= editor
;
1962 /** Sets editor for a property.
1964 inline void SetEditor( const wxString
& editorName
);
1967 Sets cell information for given column.
1969 void SetCell( int column
, const wxPGCell
& cell
);
1971 /** Sets common value selected for this property. -1 for none.
1973 void SetCommonValue( int commonValue
)
1975 m_commonValue
= commonValue
;
1978 /** Sets flags from a '|' delimited string. Note that flag names are not
1979 prepended with 'wxPG_PROP_'.
1981 void SetFlagsFromString( const wxString
& str
);
1983 /** Sets property's "is it modified?" flag. Affects children recursively.
1985 void SetModifiedStatus( bool modified
)
1987 SetFlagRecursively(wxPG_PROP_MODIFIED
, modified
);
1990 /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1991 based on user input.
1994 This method is const since it doesn't actually modify value, but posts
1995 given variant as pending value, stored in wxPropertyGrid.
1997 void SetValueInEvent( wxVariant value
) const;
2000 Call this to set value of the property.
2002 Unlike methods in wxPropertyGrid, this does not automatically update
2006 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
2007 through validation process and send property change event.
2009 If you need to change property value in event, based on user input, use
2010 SetValueInEvent() instead.
2013 Pointer to list variant that contains child values. Used to
2014 indicate which children should be marked as modified.
2017 Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR, which is
2018 enabled by default).
2020 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
,
2021 int flags
= wxPG_SETVAL_REFRESH_EDITOR
);
2023 /** Set wxBitmap in front of the value. This bitmap may be ignored
2024 by custom cell renderers.
2026 void SetValueImage( wxBitmap
& bmp
);
2028 /** Sets selected choice and changes property value.
2030 Tries to retain value type, although currently if it is not string,
2031 then it is forced to integer.
2033 void SetChoiceSelection( int newValue
);
2035 void SetExpanded( bool expanded
)
2037 if ( !expanded
) m_flags
|= wxPG_PROP_COLLAPSED
;
2038 else m_flags
&= ~wxPG_PROP_COLLAPSED
;
2042 Sets given property flag.
2044 @see propgrid_propflags
2046 void SetFlag( wxPGPropertyFlags flag
)
2049 // NB: While using wxPGPropertyFlags here makes it difficult to
2050 // combine different flags, it usefully prevents user from
2051 // using incorrect flags (say, wxWindow styles).
2056 Sets or clears given property flag.
2058 @see propgrid_propflags
2060 void ChangeFlag( wxPGPropertyFlags flag
, bool set
)
2069 Sets or clears given property flag, recursively.
2071 @see propgrid_propflags
2073 void SetFlagRecursively( wxPGPropertyFlags flag
, bool set
);
2075 void SetHelpString( const wxString
& helpString
)
2077 m_helpString
= helpString
;
2080 void SetLabel( const wxString
& label
) { m_label
= label
; }
2082 void SetName( const wxString
& newName
);
2085 Changes what sort of parent this property is for its children.
2088 Use one of the following values: wxPG_PROP_MISC_PARENT (for
2089 generic parents), wxPG_PROP_CATEGORY (for categories), or
2090 wxPG_PROP_AGGREGATE (for derived property classes with private
2093 @remarks You generally do not need to call this function.
2095 void SetParentalType( int flag
)
2097 m_flags
&= ~(wxPG_PROP_PROPERTY
|wxPG_PROP_PARENTAL_FLAGS
);
2101 void SetValueToUnspecified()
2103 wxVariant val
; // Create NULL variant
2104 SetValue(val
, NULL
, wxPG_SETVAL_REFRESH_EDITOR
);
2107 // Helper function (for wxPython bindings and such) for settings protected
2109 void SetValuePlain( wxVariant value
)
2114 #if wxUSE_VALIDATORS
2115 /** Sets wxValidator for a property*/
2116 void SetValidator( const wxValidator
& validator
)
2118 m_validator
= wxDynamicCast(validator
.Clone(),wxValidator
);
2121 /** Gets assignable version of property's validator. */
2122 wxValidator
* GetValidator() const
2126 return DoGetValidator();
2128 #endif // wxUSE_VALIDATORS
2130 /** Returns client data (void*) of a property.
2132 void* GetClientData() const
2134 return m_clientData
;
2137 /** Sets client data (void*) of a property.
2139 This untyped client data has to be deleted manually.
2141 void SetClientData( void* clientData
)
2143 m_clientData
= clientData
;
2146 /** Returns client object of a property.
2148 void SetClientObject(wxClientData
* clientObject
)
2150 delete m_clientObject
;
2151 m_clientObject
= clientObject
;
2154 /** Sets managed client object of a property.
2156 wxClientData
*GetClientObject() const { return m_clientObject
; }
2159 Sets new set of choices for the property.
2161 @remarks This operation deselects the property and clears its
2164 bool SetChoices( const wxPGChoices
& choices
);
2166 /** Set max length of text in text editor.
2168 inline bool SetMaxLength( int maxLen
);
2170 /** Call with 'false' in OnSetValue to cancel value changes after all
2171 (ie. cancel 'true' returned by StringToValue() or IntToValue()).
2173 void SetWasModified( bool set
= true )
2175 if ( set
) m_flags
|= wxPG_PROP_WAS_MODIFIED
;
2176 else m_flags
&= ~wxPG_PROP_WAS_MODIFIED
;
2179 const wxString
& GetHelpString() const
2181 return m_helpString
;
2184 void ClearFlag( FlagType flag
) { m_flags
&= ~(flag
); }
2186 // Use, for example, to detect if item is inside collapsed section.
2187 bool IsSomeParent( wxPGProperty
* candidate_parent
) const;
2190 Adapts list variant into proper value using consecutive
2193 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
2195 #if wxPG_COMPATIBILITY_1_4
2197 Adds a private child property.
2199 @deprecated Use AddPrivateChild() instead.
2201 @see AddPrivateChild()
2203 wxDEPRECATED( void AddChild( wxPGProperty
* prop
) );
2207 Adds a private child property. If you use this instead of
2208 wxPropertyGridInterface::Insert() or
2209 wxPropertyGridInterface::AppendIn(), then property's parental
2210 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
2211 words, all properties of this property will become private.
2213 void AddPrivateChild( wxPGProperty
* prop
);
2216 Appends a new child property.
2218 wxPGProperty
* AppendChild( wxPGProperty
* prop
)
2220 return InsertChild(-1, prop
);
2223 /** Returns height of children, recursively, and
2224 by taking expanded/collapsed status into account.
2226 iMax is used when finding property y-positions.
2228 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
2230 /** Returns number of child properties */
2231 unsigned int GetChildCount() const
2233 return (unsigned int) m_children
.size();
2236 /** Returns sub-property at index i. */
2237 wxPGProperty
* Item( unsigned int i
) const
2238 { return m_children
[i
]; }
2240 /** Returns last sub-property.
2242 wxPGProperty
* Last() const { return m_children
.back(); }
2244 /** Returns index of given child property. */
2245 int Index( const wxPGProperty
* p
) const;
2247 // Puts correct indexes to children
2248 void FixIndicesOfChildren( unsigned int starthere
= 0 );
2251 Converts image width into full image offset, with margins.
2253 int GetImageOffset( int imageWidth
) const;
2255 // Returns wxPropertyGridPageState in which this property resides.
2256 wxPropertyGridPageState
* GetParentState() const { return m_parentState
; }
2258 wxPGProperty
* GetItemAtY( unsigned int y
,
2260 unsigned int* nextItemY
) const;
2262 /** Returns property at given virtual y coordinate.
2264 wxPGProperty
* GetItemAtY( unsigned int y
) const;
2266 /** Returns (direct) child property with given name (or NULL if not found).
2268 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
2270 // Returns various display-related information for given column
2271 void GetDisplayInfo( unsigned int column
,
2275 const wxPGCell
** pCell
);
2277 static wxString
* sm_wxPG_LABEL
;
2279 /** This member is public so scripting language bindings
2280 wrapper code can access it freely.
2287 Sets property cell in fashion that reduces number of exclusive
2288 copies of cell data. Used when setting, for instance, same
2289 background colour for a number of properties.
2292 First column to affect.
2295 Last column to affect.
2298 Pre-prepared cell that is used for those which cell data
2299 before this matched unmodCellData.
2302 If unmodCellData did not match, valid cell data from this
2303 is merged into cell (usually generating new exclusive copy
2306 @param unmodCellData
2307 If cell's cell data matches this, its cell is now set to
2310 @param ignoreWithFlags
2311 Properties with any one of these flags are skipped.
2314 If @true, apply this operation recursively in child properties.
2316 void AdaptiveSetCell( unsigned int firstCol
,
2317 unsigned int lastCol
,
2318 const wxPGCell
& preparedCell
,
2319 const wxPGCell
& srcData
,
2320 wxPGCellData
* unmodCellData
,
2321 FlagType ignoreWithFlags
,
2325 Makes sure m_cells has size of column+1 (or more).
2327 void EnsureCells( unsigned int column
);
2329 /** Returns (direct) child property with given name (or NULL if not found),
2333 Start looking for the child at this index.
2336 Does not support scope (ie. Parent.Child notation).
2338 wxPGProperty
* GetPropertyByNameWH( const wxString
& name
,
2339 unsigned int hintIndex
) const;
2341 /** This is used by Insert etc. */
2342 void DoAddChild( wxPGProperty
* prop
,
2344 bool correct_mode
= true );
2346 void DoGenerateComposedValue( wxString
& text
,
2347 int argFlags
= wxPG_VALUE_IS_CURRENT
,
2348 const wxVariantList
* valueOverrides
= NULL
,
2349 wxPGHashMapS2S
* childResults
= NULL
) const;
2351 bool DoHide( bool hide
, int flags
);
2353 void DoSetName(const wxString
& str
) { m_name
= str
; }
2355 /** Deletes all sub-properties. */
2358 bool HasCell( unsigned int column
) const
2360 if ( m_cells
.size() > column
)
2365 void InitAfterAdded( wxPropertyGridPageState
* pageState
,
2366 wxPropertyGrid
* propgrid
);
2368 // Removes child property with given pointer. Does not delete it.
2369 void RemoveChild( wxPGProperty
* p
);
2371 void DoEnable( bool enable
);
2373 void DoPreAddChild( int index
, wxPGProperty
* prop
);
2375 void SetParentState( wxPropertyGridPageState
* pstate
)
2376 { m_parentState
= pstate
; }
2378 // Call after fixed sub-properties added/removed after creation.
2379 // if oldSelInd >= 0 and < new max items, then selection is
2381 void SubPropsChanged( int oldSelInd
= -1 );
2383 int GetY2( int lh
) const;
2387 wxPGProperty
* m_parent
;
2388 wxPropertyGridPageState
* m_parentState
;
2390 wxClientData
* m_clientObject
;
2392 // Overrides editor returned by property class
2393 const wxPGEditor
* m_customEditor
;
2394 #if wxUSE_VALIDATORS
2395 // Editor is going to get this validator
2396 wxValidator
* m_validator
;
2398 // Show this in front of the value
2400 // TODO: Can bitmap be implemented with wxPGCell?
2401 wxBitmap
* m_valueBitmap
;
2404 wxPGAttributeStorage m_attributes
;
2405 wxArrayPGProperty m_children
;
2407 // Extended cell information
2408 wxVector
<wxPGCell
> m_cells
;
2410 // Choices shown in drop-down list of editor control.
2411 wxPGChoices m_choices
;
2413 // Help shown in statusbar or help box.
2414 wxString m_helpString
;
2416 // Index in parent's property array.
2417 unsigned int m_arrIndex
;
2419 // If not -1, then overrides m_value
2424 // Maximum length (mainly for string properties). Could be in some sort of
2425 // wxBaseStringProperty, but currently, for maximum flexibility and
2426 // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
2427 // so short int will fit in just fine.
2430 // Root has 0, categories etc. at that level 1, etc.
2431 unsigned char m_depth
;
2433 // m_depthBgCol indicates width of background colour between margin and item
2434 // (essentially this is category's depth, if none then equals m_depth).
2435 unsigned char m_depthBgCol
;
2438 // Called in constructors.
2440 void Init( const wxString
& label
, const wxString
& name
);
2443 // -----------------------------------------------------------------------
2446 // Property class declaration helper macros
2447 // (wxPGRootPropertyClass and wxPropertyCategory require this).
2450 #define WX_PG_DECLARE_DOGETEDITORCLASS \
2451 virtual const wxPGEditor* DoGetEditorClass() const;
2453 #ifndef WX_PG_DECLARE_PROPERTY_CLASS
2454 #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
2456 DECLARE_DYNAMIC_CLASS(CLASSNAME) \
2457 WX_PG_DECLARE_DOGETEDITORCLASS \
2461 // Implements sans constructor function. Also, first arg is class name, not
2463 #define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
2464 const wxPGEditor* PROPNAME::DoGetEditorClass() const \
2466 return wxPGEditor_##EDITOR; \
2469 // -----------------------------------------------------------------------
2471 /** @class wxPGRootProperty
2473 Root parent property.
2475 class WXDLLIMPEXP_PROPGRID wxPGRootProperty
: public wxPGProperty
2478 WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty
)
2482 wxPGRootProperty( const wxString
& name
= wxS("<Root>") );
2483 virtual ~wxPGRootProperty();
2485 virtual bool StringToValue( wxVariant
&, const wxString
&, int ) const
2493 // -----------------------------------------------------------------------
2495 /** @class wxPropertyCategory
2497 Category (caption) property.
2499 class WXDLLIMPEXP_PROPGRID wxPropertyCategory
: public wxPGProperty
2501 friend class wxPropertyGrid
;
2502 friend class wxPropertyGridPageState
;
2503 WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory
)
2506 /** Default constructor is only used in special cases. */
2507 wxPropertyCategory();
2509 wxPropertyCategory( const wxString
& label
,
2510 const wxString
& name
= wxPG_LABEL
);
2511 ~wxPropertyCategory();
2513 int GetTextExtent( const wxWindow
* wnd
, const wxFont
& font
) const;
2515 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
) const;
2516 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
2519 void SetTextColIndex( unsigned int colInd
)
2520 { m_capFgColIndex
= (wxByte
) colInd
; }
2521 unsigned int GetTextColIndex() const
2522 { return (unsigned int) m_capFgColIndex
; }
2524 void CalculateTextExtent( wxWindow
* wnd
, const wxFont
& font
);
2526 int m_textExtent
; // pre-calculated length of text
2527 wxByte m_capFgColIndex
; // caption text colour index
2533 // -----------------------------------------------------------------------
2535 #endif // wxUSE_PROPGRID
2537 #endif // _WX_PROPGRID_PROPERTY_H_