X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c82a80e81f58fec31e6e099fe017cb608acb0a95..94dc70d190601bd3ef872009ca16c808bc4af72f:/interface/wx/propgrid/property.h diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h index 4538172cc2..762f6a37f1 100644 --- a/interface/wx/propgrid/property.h +++ b/interface/wx/propgrid/property.h @@ -10,15 +10,15 @@ #define wxNullProperty ((wxPGProperty*)NULL) -/** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers +/** + @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers - wxPGProperty::SetAttribute() and - wxPropertyGridInterface::SetPropertyAttribute() - accept one of these as attribute name argument . + wxPGProperty::SetAttribute() and wxPropertyGridInterface::SetPropertyAttribute() + accept one of these as attribute name argument. - You can use strings instead of constants. However, some of these - constants are redefined to use cached strings which may reduce - your binary size by some amount. + You can use strings instead of constants. + However, some of these constants are redefined to use cached strings which + may reduce your binary size by some amount. @{ */ @@ -41,18 +41,38 @@ */ #define wxPG_ATTR_UNITS wxS("Units") -/** Universal, string. When set, will be shown in property's value cell - when displayed value string is empty, or value is unspecified. +/** When set, will be shown as 'greyed' text in property's value cell when + the actual displayed value is blank. +*/ +#define wxPG_ATTR_HINT wxS("Hint") + +/** + @deprecated Use "Hint" (wxPG_ATTR_HINT) instead. */ #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 +135,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") @@ -124,10 +145,15 @@ */ #define wxPG_ATTR_SPINCTRL_STEP wxS("Step") -/** SpinCtrl editor, bool. If true, value wraps at Min/Max. +/** SpinCtrl editor, bool. If @true, value wraps at Min/Max. */ #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap") +/** SpinCtrl editor, bool. If @true, value can also by changed by moving + mouse when left mouse button is being pressed. +*/ +#define wxPG_ATTR_SPINCTRL_MOTIONSPIN wxS("MotionSpin") + /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings appear before list strings. If 2, user strings appear after list string. */ @@ -141,9 +167,153 @@ /** @} */ -// ----------------------------------------------------------------------- -/** @class wxPGProperty +/** @section propgrid_propflags wxPGProperty Flags + @{ +*/ + +enum wxPGPropertyFlags +{ + +/** Indicates bold font. +*/ +wxPG_PROP_MODIFIED = 0x0001, + +/** Disables ('greyed' text and editor does not activate) property. +*/ +wxPG_PROP_DISABLED = 0x0002, + +/** Hider button will hide this property. +*/ +wxPG_PROP_HIDDEN = 0x0004, + +/** This property has custom paint image just in front of its value. + If property only draws custom images into a popup list, then this + flag should not be set. +*/ +wxPG_PROP_CUSTOMIMAGE = 0x0008, + +/** Do not create text based editor for this property (but button-triggered + dialog and choice are ok). +*/ +wxPG_PROP_NOEDITOR = 0x0010, + +/** Property is collapsed, ie. it's children are hidden. +*/ +wxPG_PROP_COLLAPSED = 0x0020, + +/** + If property is selected, then indicates that validation failed for pending + value. + + If property is not selected, then indicates that the the actual property + value has failed validation (NB: this behavior is not currently supported, + but may be used in future). +*/ +wxPG_PROP_INVALID_VALUE = 0x0040, + +// 0x0080, + +/** Switched via SetWasModified(). Temporary flag - only used when + setting/changing property value. +*/ +wxPG_PROP_WAS_MODIFIED = 0x0200, + +/** + If set, then child properties (if any) are private, and should be + "invisible" to the application. +*/ +wxPG_PROP_AGGREGATE = 0x0400, + +/** If set, then child properties (if any) are copies and should not + be deleted in dtor. +*/ +wxPG_PROP_CHILDREN_ARE_COPIES = 0x0800, + +/** + Classifies this item as a non-category. + + Used for faster item type identification. +*/ +wxPG_PROP_PROPERTY = 0x1000, + +/** + Classifies this item as a category. + + Used for faster item type identification. +*/ +wxPG_PROP_CATEGORY = 0x2000, + +/** Classifies this item as a property that has children, but is not aggregate + (ie children are not private). +*/ +wxPG_PROP_MISC_PARENT = 0x4000, + +/** Property is read-only. Editor is still created for wxTextCtrl-based + property editors. For others, editor is not usually created because + they do implement wxTE_READONLY style or equivalent. +*/ +wxPG_PROP_READONLY = 0x8000, + +// +// NB: FLAGS ABOVE 0x8000 CANNOT BE USED WITH PROPERTY ITERATORS +// + +/** Property's value is composed from values of child properties. + @remarks + This flag cannot be used with property iterators. +*/ +wxPG_PROP_COMPOSED_VALUE = 0x00010000, + +/** Common value of property is selectable in editor. + @remarks + This flag cannot be used with property iterators. +*/ +wxPG_PROP_USES_COMMON_VALUE = 0x00020000, + +/** Property can be set to unspecified value via editor. + Currently, this applies to following properties: + - wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty: + Clear the text field + + @remarks + This flag cannot be used with property iterators. +*/ +wxPG_PROP_AUTO_UNSPECIFIED = 0x00040000, + +/** Indicates the bit useable by derived properties. +*/ +wxPG_PROP_CLASS_SPECIFIC_1 = 0x00080000, + +/** Indicates the bit useable by derived properties. +*/ +wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000, + +/** Indicates that the property is being deleted and should be ignored. +*/ +wxPG_PROP_BEING_DELETED = 0x00200000 + +}; + +/** Topmost flag. +*/ +#define wxPG_PROP_MAX wxPG_PROP_AUTO_UNSPECIFIED + +/** Property with children must have one of these set, otherwise iterators + will not work correctly. + Code should automatically take care of this, however. +*/ +#define wxPG_PROP_PARENTAL_FLAGS \ + ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \ + wxPG_PROP_CATEGORY | \ + wxPG_PROP_MISC_PARENT)) + +/** @} +*/ + + +/** + @class wxPGProperty wxPGProperty is base class for all wxPropertyGrid properties. In sections below we cover few related topics. @@ -180,12 +350,18 @@ @subsection wxPropertyCategory Not an actual property per se, but a header for a group of properties. - Regardless inherits from wxPGProperty. + Regardless inherits from wxPGProperty, and supports displaying 'labels' + for columns other than the first one. Easiest way to set category's + label for second column is to call wxPGProperty::SetValue() with string + argument. @subsection wxStringProperty 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 @@ -275,7 +451,7 @@ Like wxLongStringProperty, but the button triggers file selector instead. Default wildcard is "All files..." but this can be changed by setting wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details). - Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show + Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false inorder to show only the filename, not the entire path. @subsection wxEnumProperty @@ -285,13 +461,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 @@ -304,6 +483,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 @@ -357,7 +537,7 @@ wxColour m_colour; }; @endcode - + in wxSystemColourProperty, and its derived class wxColourProperty, there are various sub-classing features. To set basic list list of colour names, call wxPGProperty::SetChoices(). @@ -399,11 +579,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; @@ -480,7 +664,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). @@ -488,8 +672,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 @@ -517,15 +704,15 @@ public: /** Override this to return something else than m_value as the value. */ - virtual wxVariant DoGetValue() const { return m_value; } + virtual wxVariant DoGetValue() const; /** Implement this function in derived class to check the value. - Return true if it is ok. Returning false prevents property change events + Return @true if it is ok. Returning @false prevents property change events from occurring. @remarks - - Default implementation always returns true. + - Default implementation always returns @true. */ virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const; @@ -564,10 +751,8 @@ public: @param variant On function entry this is the old value (should not be wxNullVariant in normal cases). Translated value must be assigned back to it. - @param number Integer to be translated into variant. - @param argFlags If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one. @@ -581,26 +766,24 @@ public: - If property uses choice control, and displays a dialog on some choice items, then it is preferred to display that dialog in IntToValue instead of OnEvent. - - You might want to take into account that m_value is Null variant if + - You might want to take into account that m_value is Mull variant if property value is unspecified (which is usually only case if you explicitly enabled that sort behavior). */ - virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const; + virtual bool IntToValue( wxVariant& variant, int number, int argFlags = 0 ) const; /** Converts property value into a text representation. @param value Value to be converted. - @param argFlags If 0 (default value), then displayed string is returned. If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable. If wxPG_EDITABLE_VALUE is set, returns - string value that must be editable in textctrl. If - wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to - display as a part of string property's composite text - representation. + string value that must be editable in textctrl. + If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to + display as a part of string property's composite text representation. @remarks Default implementation calls GenerateComposedValue(). */ @@ -609,22 +792,26 @@ public: /** Converts string to a value, and if successful, calls SetValue() on it. Default behavior is to do nothing. + @param text - String to get the value from. - @retval - true if value was changed. + String to get the value from. + @param flags + @todo docme + + @return @true if value was changed. */ bool SetValueFromString( const wxString& text, int flags = 0 ); /** Converts integer to a value, and if succesful, calls SetValue() on it. Default behavior is to do nothing. + @param value - Int to get the value from. + Int to get the value from. @param flags - If has wxPG_FULL_VALUE, then the value given is a actual value and not an index. - @retval - True if value was changed. + If has wxPG_FULL_VALUE, then the value given is a actual value and not an index. + + @return @true if value was changed. */ bool SetValueFromInt( long value, int flags = 0 ); @@ -632,8 +819,10 @@ public: Returns size of the custom painted image in front of property. This method must be overridden to return non-default value if OnCustomPaint is to be called. + @param item - Normally -1, but can be an index to the property's list of items. + Normally -1, but can be an index to the property's list of items. + @remarks - Default behavior is to return wxSize(0,0), which means no image. - Default image width or height is indicated with dimension -1. @@ -649,13 +838,14 @@ public: wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when 'custom' selection is made). - If the event causes value to be changed, SetValueInEvent() - should be called to set the new value. + If the event causes value to be changed, SetValueInEvent() should be called + to set the new value. + + The parameter @a event is the associated wxEvent. - @param event - Associated wxEvent. @retval - Should return true if any changes in value should be reported. + Should return @true if any changes in value should be reported. + @remarks - If property uses choice control, and displays a dialog on some choice items, then it is preferred to display that dialog in IntToValue instead of OnEvent. @@ -663,18 +853,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. @@ -688,17 +885,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. @@ -707,7 +915,7 @@ public: /** Returns pointer to the wxValidator that should be used - with the editor of this property (NULL for no validator). + with the editor of this property (@NULL for no validator). Setting validator explicitly via SetPropertyValidator will override this. @@ -816,12 +1024,15 @@ public: virtual void RefreshChildren(); /** - Special handling for attributes of this property. + Reimplement this member function to add special handling for + attributes of this property. - If returns false, then the attribute will be automatically stored in - m_attributes. + @return Return @false to have the attribute automatically stored in + m_attributes. Default implementation simply does that and + nothing else. - Default implementation simply returns false. + @remarks To actually set property attribute values from the + application, use wxPGProperty::SetAttribute() instead. */ virtual bool DoSetAttribute( const wxString& name, wxVariant& value ); @@ -830,7 +1041,7 @@ public: Override if custom handling of attributes is needed. - Default implementation simply return NULL variant. + Default implementation simply return @NULL variant. */ virtual wxVariant DoGetAttribute( const wxString& name ) const; @@ -838,24 +1049,19 @@ public: Returns instance of a new wxPGEditorDialogAdapter instance, which is used when user presses the (optional) button next to the editor control; - Default implementation returns NULL (ie. no action is generated when + Default implementation returns @NULL (ie. no action is generated when button is pressed). */ virtual wxPGEditorDialogAdapter* GetEditorDialog() const; /** - Returns wxPGCell of given column, NULL if none. If valid - object is returned, caller will gain its ownership. - */ - wxPGCell* AcquireCell( unsigned int column ) - { - if ( column >= m_cells.size() ) - return NULL; + Called whenever validation has failed with given pending value. - wxPGCell* cell = (wxPGCell*) m_cells[column]; - m_cells[column] = NULL; - return cell; - } + @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. @@ -873,23 +1079,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 @@ -897,6 +1102,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. @@ -907,16 +1125,22 @@ public: bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const; /** - Returns true if children of this property are component values (for instance, + Returns @true if children of this property are component values (for instance, points size, face name, and is_underlined are component values of a font). */ - bool AreChildrenComponents() const - { - if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) ) - return true; + bool AreChildrenComponents() const; - return false; - } + /** + Sets or clears given property flag. + + @see propgrid_propflags + */ + void ChangeFlag( wxPGPropertyFlags flag, bool set ); + + /** + Deletes children of the property. + */ + void DeleteChildren(); /** Removes entry from property's wxPGChoices and editor control (if it is active). @@ -956,30 +1180,31 @@ public: wxVariant GetAttributesAsList() const; /** - Returns editor used for given column. NULL for no editor. + Returns editor used for given column. @NULL for no editor. */ - const wxPGEditor* GetColumnEditor( int column ) const - { - if ( column == 1 ) - return GetEditorClass(); - - return NULL; - } + const wxPGEditor* GetColumnEditor( int column ) const; /** Returns property's base name (ie. parent's name is not added in any case) */ - const wxString& GetBaseName() const { return m_name; } + const wxString& GetBaseName() const; /** - Returns wxPGCell of given column, NULL if none. wxPGProperty - will retain ownership of the cell object. + 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. */ - wxPGCell* GetCell( unsigned int column ) const - { - if ( column >= m_cells.size() ) - return NULL; + const wxPGCell& GetCell( unsigned int column ) const; - return (wxPGCell*) m_cells[column]; - } + /** + 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. @@ -1021,10 +1246,7 @@ public: /** Returns property's displayed text. */ - wxString GetDisplayedString() const - { - return GetValueString(0); - } + wxString GetDisplayedString() const; /** Returns wxPGEditor that will be used and created when @@ -1033,6 +1255,11 @@ public: */ const wxPGEditor* GetEditorClass() const; + /** + Returns property flags. + */ + FlagType GetFlags() const; + /** Returns property grid where property lies. */ wxPropertyGrid* GetGrid() const; @@ -1055,7 +1282,7 @@ public: unsigned int GetIndexInParent() const; /** Returns property's label. */ - const wxString& GetLabel() const { return m_label; } + const wxString& GetLabel() const; /** Returns last visible child property, recursively. @@ -1073,19 +1300,16 @@ public: /** Returns maximum allowed length of property's text value. */ - int GetMaxLength() const - { - return (int) m_maxLen; - } + int GetMaxLength() const; /** Returns property's name with all (non-category, non-root) parents. */ wxString GetName() const; /** Return parent of property */ - wxPGProperty* GetParent() const { return m_parent; } + wxPGProperty* GetParent() const; /** - Returns (direct) child property with given name (or NULL if not found). + Returns (direct) child property with given name (or @NULL if not found). */ wxPGProperty* GetPropertyByName( const wxString& name ) const; @@ -1095,13 +1319,10 @@ public: /** Returns property's value. */ - wxVariant GetValue() const - { - return DoGetValue(); - } + wxVariant GetValue() const; /** - Returns bitmap that appears next to value text. Only returns non-NULL + Returns bitmap that appears next to value text. Only returns non-@NULL bitmap if one was set with SetValueImage(). */ wxBitmap* GetValueImage() const; @@ -1135,10 +1356,7 @@ public: /** Returns value type used by this property. */ - wxString GetValueType() const - { - return m_value.GetType(); - } + wxString GetValueType() const; /** Returns coordinate to the top y of the property. Note that the @@ -1147,7 +1365,14 @@ public: int GetY() const; /** - Returns true if property has even one visible child. + Returns non-zero if property has given flag set. + + @see propgrid_propflags + */ + FlagType HasFlag( wxPGPropertyFlags flag ) const; + + /** + Returns @true if property has even one visible child. */ bool HasVisibleChildren() const; @@ -1168,6 +1393,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. @@ -1201,7 +1439,7 @@ public: /** Returns @true if this property is actually a wxRootProperty. */ - bool IsRoot() const { return (m_parent == NULL); } + bool IsRoot() const; /** Returns @true if candidateParent is some parent of this property. @@ -1252,6 +1490,20 @@ public: */ void SetAttribute( const wxString& name, wxVariant value ); + /** + Sets property's background colour. + + @param colour + Background colour to use. + + @param flags + Default is wxPG_RECURSE which causes colour to be set recursively. + Omit this flag to only set colour for the property in question + and not any of its children. + */ + void SetBackgroundColour( const wxColour& colour, + int flags = wxPG_RECURSE ); + /** Sets editor for a property. @@ -1270,24 +1522,17 @@ public: /** Sets cell information for given column. - - Note that the property takes ownership of given wxPGCell instance. */ - void SetCell( int column, wxPGCell* cellObj ); + void SetCell( int column, const wxPGCell& cell ); /** - Sets new set of choices for property. + Sets new set of choices for the property. - @remarks This operation clears the property value. + @remarks This operation deselects the property and clears its + value. */ 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. @@ -1307,6 +1552,28 @@ public: */ void SetChoiceSelection( int newValue ); + /** Set default value of a property. Synonymous to + + @code + SetAttribute("DefaultValue", value); + @endcode + */ + void SetDefaultValue( wxVariant& value ); + + /** + Sets given property flag. + + @see propgrid_propflags + */ + void SetFlag( wxPGPropertyFlags flag ); + + /** + Sets or clears given property flag, recursively. + + @see propgrid_propflags + */ + void SetFlagRecursively( wxPGPropertyFlags flag, bool set ); + /** Sets property's help string, which is shown, for example, in wxPropertyGridManager's description text box. @@ -1319,7 +1586,7 @@ public: @remarks Properties under same parent may have same labels. However, property names must still remain unique. */ - void SetLabel( const wxString& label ) { m_label = label; } + void SetLabel( const wxString& label ); /** Set max length of text in text editor. @@ -1345,14 +1612,24 @@ 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 ); + /** + Sets property's text colour. + + @param colour + Text colour to use. + + @param flags + Default is wxPG_RECURSE which causes colour to be set recursively. + Omit this flag to only set colour for the property in question + and not any of its children. + */ + void SetTextColour( const wxColour& colour, + int flags = wxPG_RECURSE ); + /** Sets wxValidator for a property */ void SetValidator( const wxValidator& validator ); @@ -1367,15 +1644,17 @@ public: If you need to change property value in event, based on user input, use SetValueInEvent() instead. + @param value + The value to set. @param pList Pointer to list variant that contains child values. Used to indicate - which children should be marked as modified. Usually you just use NULL. - + 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 @@ -1410,21 +1689,97 @@ public: wxPGProperty* UpdateParentValues(); /** - Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES. + Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES. */ bool UsesAutoUnspecified() const; }; -/** @class wxPGChoices +/** + @class wxPGCell + + Base class for wxPropertyGrid cell information. + + @library{wxpropgrid} + @category{propgrid} +*/ +class wxPGCell : public wxObject +{ +public: + wxPGCell(); + wxPGCell(const wxPGCell& other); + wxPGCell( const wxString& text, + const wxBitmap& bitmap = wxNullBitmap, + const wxColour& fgCol = wxNullColour, + const wxColour& bgCol = wxNullColour ); + + virtual ~wxPGCell(); + + const wxPGCellData* GetData() const; + + /** + Returns @true if this cell has custom text stored within. + */ + bool HasText() const; + + /** + Merges valid data from srcCell into this. + */ + void MergeFrom( const wxPGCell& srcCell ); + + void SetText( const wxString& text ); + void SetBitmap( const wxBitmap& bitmap ); + void SetFgCol( const wxColour& col ); + + /** + Sets font of the cell. + + @remarks Because wxPropertyGrid does not support rows of + different height, it makes little sense to change + size of the font. Therefore it is recommended + to use return value of wxPropertyGrid::GetFont() + or wxPropertyGrid::GetCaptionFont() as a basis + for the font that, after modifications, is passed + to this member function. + */ + void SetFont( const wxFont& font ); + + void SetBgCol( const wxColour& col ); + + const wxString& GetText() const; + const wxBitmap& GetBitmap() const; + const wxColour& GetFgCol() const; + + /** + Returns font of the cell. If no specific font is set for this + cell, then the font will be invalid. + */ + const wxFont& GetFont() const; + + const wxColour& GetBgCol() const; + + wxPGCell& operator=( const wxPGCell& other ); +}; + + +/** + @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} */ -class WXDLLIMPEXP_PROPGRID wxPGChoices +class wxPGChoices { public: typedef long ValArrItem; @@ -1434,7 +1789,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. */ @@ -1469,21 +1827,16 @@ public: int value = wxPG_INVALID_VALUE ); /** Adds a single item with full entry information. */ - wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry ) - { - return Insert(entry, -1); - } + wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry ); /** Adds single item, sorted. */ 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 ) - { - AssignData(a.m_data); - } + void Assign( const wxPGChoices& a ); /** Assigns data from another set of choices. @@ -1493,11 +1846,12 @@ public: /** Deletes all items. */ - void Clear() - { - if ( m_data != wxPGChoicesEmptyData ) - m_data->Clear(); - } + void Clear(); + + /** + Returns a real copy of the choices. + */ + wxPGChoices Copy() const; /** Returns labe of item. @@ -1522,11 +1876,15 @@ public: /** Returns array of indices matching given strings. Unmatching strings - are added to 'unmatched', if not NULL. + are added to 'unmatched', if not @NULL. */ 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; */ @@ -1553,31 +1911,20 @@ public: wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index ); /** - Returns false if this is a constant empty set of choices, + Returns @false if this is a constant empty set of choices, which should not be modified. */ - bool IsOk() const - { - return ( m_data != wxPGChoicesEmptyData ); - } + bool IsOk() const; /** Returns item at given index. */ - const wxPGChoiceEntry& Item( unsigned int i ) const - { - wxASSERT( IsOk() ); - return *m_data->Item(i); - } + const wxPGChoiceEntry& Item( unsigned int i ) const; /** Returns item at given index. */ - wxPGChoiceEntry& Item( unsigned int i ) - { - wxASSERT( IsOk() ); - return *m_data->Item(i); - } + wxPGChoiceEntry& Item( unsigned int i ); /** Removes count items starting at position nIndex. @@ -1597,27 +1944,17 @@ public: /** Creates exclusive copy of current choices. */ - void SetExclusive(); + void AllocExclusive(); /** Returns array of choice labels. */ wxArrayString GetLabels() const; - void operator= (const wxPGChoices& a) - { - AssignData(a.m_data); - } - - wxPGChoiceEntry& operator[](unsigned int i) - { - return Item(i); - } + void operator= (const wxPGChoices& a); - const wxPGChoiceEntry& operator[](unsigned int i) const - { - return Item(i); - } + wxPGChoiceEntry& operator[](unsigned int i); + const wxPGChoiceEntry& operator[](unsigned int i) const; }; // -----------------------------------------------------------------------