X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/91c818f82929ee2164ac5cfc77eaecddcea937a0..4017f5ca49e153e04ffd1c49bc93afd31c1cdf87:/interface/wx/propgrid/property.h diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h index 5cd1d564a1..fb4c7bb7b8 100644 --- a/interface/wx/propgrid/property.h +++ b/interface/wx/propgrid/property.h @@ -46,13 +46,28 @@ */ #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp") -/** wxBoolProperty specific, int, default 0. When 1 sets bool property to - use checkbox instead of choice. +/** Universal, wxArrayString. Set to enable auto-completion in any + wxTextCtrl-based property editor. +*/ +#define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete") + +/** wxBoolProperty and wxFlagsProperty specific. Value type is bool. + Default value is False. + + When set to True, bool property will use check box instead of a + combo box as its editor control. If you set this attribute + for a wxFlagsProperty, it is automatically applied to child + bool properties. */ #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox") -/** wxBoolProperty specific, int, default 0. When 1 sets bool property value - to cycle on double click (instead of showing the popup listbox). +/** wxBoolProperty and wxFlagsProperty specific. Value type is bool. + Default value is False. + + Set to True for the bool property to cycle value on double click + (instead of showing the popup listbox). If you set this attribute + for a wxFlagsProperty, it is automatically applied to child + bool properties. */ #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling") @@ -115,7 +130,8 @@ #define wxPG_DATE_FORMAT wxS("DateFormat") /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default - is wxDP_DEFAULT | wxDP_SHOWCENTURY. + is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable + better unspecified value support in the editor. */ #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle") @@ -192,6 +208,9 @@ Simple string property. wxPG_STRING_PASSWORD attribute may be used to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl. + wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion + (use a wxArrayString value), and is also supported by any property that + happens to use a wxTextCtrl-based editor. @remarks wxStringProperty has a special trait: if it has value of "", and also has child properties, then its displayed @@ -291,13 +310,16 @@ @subsection wxFlagsProperty - Represents a bit set that fits in a long integer. wxBoolProperty sub-properties - are created for editing individual bits. Textctrl is created to manually edit - the flags as a text; a continous sequence of spaces, commas and semicolons - is considered as a flag id separator. - Note: When changing "choices" (ie. flag labels) of wxFlagsProperty, you - will need to use wxPGProperty::SetChoices() - otherwise they will not get updated - properly. + Represents a bit set that fits in a long integer. wxBoolProperty sub- + properties are created for editing individual bits. Textctrl is created to + manually edit the flags as a text; a continous sequence of spaces, commas + and semicolons are considered as a flag id separator. + + Note: When changing "choices" (ie. flag labels) of wxFlagsProperty, + you will need to use wxPGProperty::SetChoices() - otherwise they will not + get updated properly. + + wxFlagsProperty supports the same attributes as wxBoolProperty. @subsection wxArrayStringProperty @@ -310,6 +332,7 @@ string wxDateTime::Format uses (altough default is recommended as it is locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY). + Using wxDP_ALLOWNONE will enable better unspecified value support. @subsection wxEditEnumProperty @@ -405,11 +428,15 @@ class MyProperty : public wxPGProperty { public: - // All arguments of ctor must have a default value - + // Default constructor + MyProperty() { } + + // All arguments of this ctor must have a default value - // use wxPG_LABEL for label and name MyProperty( const wxString& label = wxPG_LABEL, const wxString& name = wxPG_LABEL, const wxString& value = wxEmptyString ) + : wxPGProperty(label, name) { // m_value is wxVariant m_value = value; @@ -486,7 +513,7 @@ public: @code MyProperty( const wxString& label, const wxString& name, const T& value ) - : wxPGProperty() + : wxPGProperty(label, name) { // Generally recommended way to set the initial value // (as it should work in pretty much 100% of cases). @@ -494,8 +521,11 @@ public: variant << value; SetValue(variant); - // If has private child properties then create them here. For example: - // AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) ); + // If has private child properties then create them here. + // For example: + // AddPrivateChild( new wxStringProperty("Subprop 1", + // wxPG_LABEL, + // value.GetSubProp1())); } @endcode @@ -672,18 +702,25 @@ public: virtual bool OnEvent( wxPropertyGrid* propgrid, wxWindow* wnd_primary, wxEvent& event ); /** - Called after value of a child property has been altered. Note that this function is - usually called at the time that value of this property, or given child property, is - still pending for change. + Called after value of a child property has been altered. Must return + new value of the whole property (after any alterations warrented by + child's new value). + + Note that this function is usually called at the time that value of + this property, or given child property, is still pending for change, + and as such, result of GetValue() or m_value should not be relied + on. Sample pseudo-code implementation: @code - void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const + wxVariant MyProperty::ChildChanged( wxVariant& thisValue, + int childIndex, + wxVariant& childValue ) const { // Acquire reference to actual type of data stored in variant - // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create - // the variant class). + // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros + // were used to create the variant class). T& data = TFromVariant(thisValue); // Copy childValue into data. @@ -697,17 +734,28 @@ public: break; ... } + + // Return altered data + return data; } @endcode @param thisValue - Value of this property, that should be altered. + Value of this property. Changed value should be returned (in + previous versions of wxPropertyGrid it was only necessary to + write value back to this argument). @param childIndex - Index of child changed (you can use Item(childIndex) to get). + Index of child changed (you can use Item(childIndex) to get + child property). @param childValue - Value of the child property. + (Pending) value of the child property. + + @return + Modified value of the whole property. */ - virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const; + virtual wxVariant ChildChanged( wxVariant& thisValue, + int childIndex, + wxVariant& childValue ) const; /** Returns pointer to an instance of used editor. @@ -852,6 +900,15 @@ public: */ virtual wxPGEditorDialogAdapter* GetEditorDialog() const; + /** + Called whenever validation has failed with given pending value. + + @remarks If you implement this in your custom property class, please + remember to call the baser implementation as well, since they + may use it to revert property into pre-change state. + */ + virtual void OnValidationFailure( wxVariant& pendingValue ); + /** Append a new choice to property's list of choices. @@ -868,23 +925,22 @@ public: int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE ); /** - Adds a child property. If you use this instead of - wxPropertyGridInterface::Insert() or - wxPropertyGridInterface::AppendIn(), then you must set up - property's parental type before making the call. To do this, - call property's SetParentalType() function with either - wxPG_PROP_MISC_PARENT (normal, public children) or with - wxPG_PROP_AGGREGATE (private children for subclassed property). - For instance: + Adds a private child property. - @code - wxPGProperty* prop = new wxStringProperty(wxS("Property")); - prop->SetParentalType(wxPG_PROP_MISC_PARENT); - wxPGProperty* prop2 = new wxStringProperty(wxS("Property2")); - prop->AddChild(prop2); - @endcode + @deprecated Use AddPrivateChild() instead. + + @see AddPrivateChild() + */ + wxDEPRECATED( void AddChild( wxPGProperty* prop ) ); + + /** + Adds a private child property. If you use this instead of + wxPropertyGridInterface::Insert() or + wxPropertyGridInterface::AppendIn(), then property's parental + type will automatically be set up to wxPG_PROP_AGGREGATE. In other + words, all properties of this property will become private. */ - void AddChild( wxPGProperty* property ); + void AddPrivateChild( wxPGProperty* prop ); /** Adapts list variant into proper value using consecutive @@ -892,6 +948,19 @@ public: */ void AdaptListToValue( wxVariant& list, wxVariant* value ) const; + /** + Use this member function to add independent (ie. regular) children to + a property. + + @return Appended childProperty. + + @remarks wxPropertyGrid is not automatically refreshed by this + function. + + @see InsertChild(), AddPrivateChild() + */ + wxPGProperty* AppendChild( wxPGProperty* childProperty ); + /** Determines, recursively, if all children are not unspecified. @@ -959,9 +1028,23 @@ public: /** Returns wxPGCell of given column. + + @remarks const version of this member function returns 'default' + wxPGCell object if the property itself didn't hold + cell data. */ const wxPGCell& GetCell( unsigned int column ) const; + /** + Returns wxPGCell of given column, creating one if necessary. + */ + wxPGCell& GetCell( unsigned int column ); + + /** + Returns wxPGCell of given column, creating one if necessary. + */ + wxPGCell& GetOrCreateCell( unsigned int column ); + /** Returns number of child properties. */ @@ -1137,6 +1220,19 @@ public: */ int Index( const wxPGProperty* p ) const; + /** + Use this member function to add independent (ie. regular) children to + a property. + + @return Inserted childProperty. + + @remarks wxPropertyGrid is not automatically refreshed by this + function. + + @see AppendChild(), AddPrivateChild() + */ + wxPGProperty* InsertChild( int index, wxPGProperty* childProperty ); + /** Inserts a new choice to property's list of choices. @@ -1262,12 +1358,6 @@ public: */ bool SetChoices( wxPGChoices& choices ); - /** - If property has choices and they are not yet exclusive, new such copy - of them will be created. - */ - void SetChoicesExclusive(); - /** Sets client data (void*) of a property. @@ -1287,6 +1377,14 @@ public: */ void SetChoiceSelection( int newValue ); + /** Set default value of a property. Synonymous to + + @code + SetAttribute("DefaultValue", value); + @endcode + */ + void SetDefaultValue( wxVariant& value ); + /** Sets property's help string, which is shown, for example, in wxPropertyGridManager's description text box. @@ -1325,11 +1423,7 @@ public: wxPG_PROP_AGGREGATE (for derived property classes with private children). - @remarks You only need to call this if you use AddChild() to add - child properties. Adding properties with - wxPropertyGridInterface::Insert() or - wxPropertyGridInterface::AppendIn() will automatically set - property to use wxPG_PROP_MISC_PARENT style. + @remarks You generally do not need to call this function. */ void SetParentalType( int flag ); @@ -1366,10 +1460,11 @@ public: Pointer to list variant that contains child values. Used to indicate which children should be marked as modified. Usually you just use @NULL. @param flags - Use wxPG_SETVAL_REFRESH_EDITOR to update editor control, if it - was selected. + wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor + and redraw properties. */ - void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 ); + void SetValue( wxVariant value, wxVariant* pList = NULL, + int flags = wxPG_SETVAL_REFRESH_EDITOR ); /** Set wxBitmap in front of the value. This bitmap may be ignored @@ -1414,7 +1509,15 @@ public: @class wxPGChoices Helper class for managing choices of wxPropertyGrid properties. - Each entry can have label, value, bitmap, text colour, and background colour. + Each entry can have label, value, bitmap, text colour, and background + colour. + + wxPGChoices uses reference counting, similar to other wxWidgets classes. + This means that assignment operator and copy constructor only copy the + reference and not the actual data. Use Copy() member function to create a + real copy. + + @remarks If you do not specify value for entry, index is used. @library{wxpropgrid} @category{propgrid} @@ -1429,7 +1532,10 @@ public: */ wxPGChoices(); - /** Copy constructor. */ + /** + Copy constructor, uses reference counting. To create a real copy, + use Copy() member function instead. + */ wxPGChoices( const wxPGChoices& a ); /** Constructor. */ @@ -1470,7 +1576,8 @@ public: wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE ); /** - Assigns data from another set of choices. + Assigns choices data, using reference counting. To create a real copy, + use Copy() member function instead. */ void Assign( const wxPGChoices& a ); @@ -1484,6 +1591,11 @@ public: */ void Clear(); + /** + Returns a real copy of the choices. + */ + wxPGChoices Copy() const; + /** Returns labe of item. */ @@ -1512,6 +1624,10 @@ public: wxArrayInt GetIndicesForStrings( const wxArrayString& strings, wxArrayString* unmatched = NULL ) const; + /** Returns property at given virtual y coordinate. + */ + wxPGProperty* GetItemAtY( unsigned int y ) const; + /** Returns @true if item at given index has a valid value; */ @@ -1571,7 +1687,7 @@ public: /** Creates exclusive copy of current choices. */ - void SetExclusive(); + void AllocExclusive(); /** Returns array of choice labels.