X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bb6720bb9e4bbc17bcea2d933e80ba7cb8246d67..c398434d925aa9e2b190ce632fac1a79ffcbf043:/interface/wx/propgrid/property.h diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h index 8394762127..2c4b99c16f 100644 --- a/interface/wx/propgrid/property.h +++ b/interface/wx/propgrid/property.h @@ -2,7 +2,7 @@ // Name: property.h // Purpose: interface of wxPGProperty // Author: wxWidgets team -// RCS-ID: $Id: +// RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// @@ -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. @{ */ @@ -46,6 +46,11 @@ */ #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp") +/** Universal, wxArrayString. Set to enable auto-completion in any + wxTextCtrl-based property editor. +*/ +#define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete") + /** wxBoolProperty specific, int, default 0. When 1 sets bool property to use checkbox instead of choice. */ @@ -115,7 +120,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 +130,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 +152,10 @@ /** @} */ -// ----------------------------------------------------------------------- -/** @class wxPGProperty + +/** + @class wxPGProperty wxPGProperty is base class for all wxPropertyGrid properties. In sections below we cover few related topics. @@ -186,6 +198,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 @@ -234,6 +249,37 @@ dialog. Note that in long string values, tabs are represented by "\t" and line break by "\n". + To display custom dialog on button press, you can subclass + wxLongStringProperty and implement OnButtonClick, like this: + + @code + virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value ) + { + wxSize dialogSize(...size of your dialog...); + + wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this, + dialogSize) + + // Create dialog dlg at dlgPos. Use value as initial string + // value. + ... + + if ( dlg.ShowModal() == wxID_OK ) + { + value = dlg.GetStringValue); + return true; + } + return false; + } + @endcode + + Also, if you wish not to have line breaks and tabs translated to + escape sequences, then do following in constructor of your subclass: + + @code + m_flags |= wxPG_PROP_NO_ESCAPE; + @endcode + @subsection wxDirProperty Like wxLongStringProperty, but the button triggers dir selector instead. @@ -244,7 +290,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 @@ -273,6 +319,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 @@ -295,6 +342,8 @@ Useful alternate editor: Choice. Represents wxColour. wxButton is used to trigger a colour picker dialog. + There are various sub-classing opportunities with this class. See + below in wxSystemColourProperty section for details. @subsection wxFontProperty @@ -305,7 +354,9 @@ Represents wxColour and a system colour index. wxChoice is used to edit the value. Drop-down list has color images. Note that value type - is wxColourPropertyValue instead of wxColour. + is wxColourPropertyValue instead of wxColour (which wxColourProperty + uses). + @code class wxColourPropertyValue : public wxObject { @@ -323,6 +374,27 @@ }; @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(). + + @code + // Override in derived class to customize how colours are translated + // to strings. + virtual wxString ColourToString( const wxColour& col, int index ) const; + + // Returns index of entry that triggers colour picker dialog + // (default is last). + virtual int GetCustomColourIndex() const; + + // Helper function to show the colour dialog + bool QueryColourFromUser( wxVariant& variant ) const; + + // Returns colour for given choice. + // Default function returns wxSystemSettings::GetColour(index). + virtual wxColour GetColour( int index ) const; + @endcode + @subsection wxCursorProperty Represents a wxCursor. wxChoice is used to edit the value. @@ -365,9 +437,10 @@ return wxPGEditor_TextCtrl; } - virtual wxString GetValueAsString( int argFlags ) const + virtual wxString ValueToString( wxVariant& value, + int argFlags ) const { - // TODO: Return property value in string format + // TODO: Convert given property value to a string } virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags ) @@ -431,8 +504,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 @@ -460,83 +536,114 @@ 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; /** - Converts 'text' into proper value 'variant'. Returns true if new (different than - m_value) value could be interpreted from the text. + Converts text into wxVariant value appropriate for this property. + + @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 text + Text to be translated into variant. + @param argFlags - If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable - one (they may be different). - If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite - property string value (as generated by GetValueAsString() called with this same - flag). + If wxPG_FULL_VALUE is set, returns complete, storable value instead + of displayable one (they may be different). + If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of + composite property string value (as generated by ValueToString() + called with this same flag). - @remarks - Default implementation converts semicolon delimited tokens into child values. Only - works for properties with children. + @return Returns @true if resulting wxVariant value was different. + + @remarks Default implementation converts semicolon delimited tokens into + child values. Only works for properties with children. + + You might want to take into account that m_value is Null variant + if property value is unspecified (which is usually only case if + you explicitly enabled that sort behavior). */ virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const; /** - Converts 'number' (including choice selection) into proper value 'variant'. - Returns true if new (different than m_value) value could be interpreted from the integer. + Converts integer (possibly a choice selection) into wxVariant value + appropriate for this property. + + @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. + If wxPG_FULL_VALUE is set, returns complete, storable value instead + of displayable one. + + @return Returns @true if resulting wxVariant value was different. @remarks - If property is not supposed to use choice or spinctrl or other editor with int-based value, it is not necessary to implement this method. - Default implementation simply assign given int to m_value. - - 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. + - 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 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; /** - Returns text representation of property's value. + Converts property value into a text representation. + @param value + Value to be converted. @param argFlags - 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 composite property string value. + 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. - @remarks - Default implementation returns string composed from text representations of - child properties. + @remarks Default implementation calls GenerateComposedValue(). */ - virtual wxString GetValueAsString( int argFlags = 0 ) const; + virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const; /** 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 ); @@ -544,8 +651,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. @@ -561,13 +670,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. @@ -604,11 +714,11 @@ public: @endcode @param thisValue - Value of this property, that should be altered. + Value of this property, that should be altered. @param childIndex - Index of child changed (you can use Item(childIndex) to get). + Index of child changed (you can use Item(childIndex) to get). @param childValue - Value of the child property. + Value of the child property. */ virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const; @@ -619,7 +729,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. @@ -702,7 +812,7 @@ public: - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for drawing framing rectangle. It can be changed as well. - @see GetValueAsString() + @see ValueToString() */ virtual void OnCustomPaint( wxDC& dc, const wxRect& rect, wxPGPaintData& paintdata ); @@ -730,10 +840,10 @@ public: /** Special handling for attributes of this property. - If returns false, then the attribute will be automatically stored in + If returns @false, then the attribute will be automatically stored in m_attributes. - Default implementation simply returns false. + Default implementation simply returns @false. */ virtual bool DoSetAttribute( const wxString& name, wxVariant& value ); @@ -742,7 +852,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; @@ -750,24 +860,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. @@ -785,10 +890,22 @@ public: int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE ); /** - Properties which have private child properties should add them - with this function, called in their constructor. + Adds a private child property. + + @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 @@ -796,6 +913,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. @@ -806,16 +936,15 @@ 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; - } + /** + Deletes children of the property. + */ + void DeleteChildren(); /** Removes entry from property's wxPGChoices and editor control (if it is active). @@ -827,8 +956,10 @@ public: /** Deletes all child properties. */ void Empty(); - /** Composes text from values of child properties. */ - void GenerateComposedValue( wxString& text, int argFlags = 0 ) const; + /** + Composes text from values of child properties. + */ + wxString GenerateComposedValue() const; /** Returns property attribute value, null variant if not found. @@ -853,30 +984,17 @@ 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. */ - wxPGCell* GetCell( unsigned int column ) const - { - if ( column >= m_cells.size() ) - return NULL; - - return (wxPGCell*) m_cells[column]; - } + const wxPGCell& GetCell( unsigned int column ) const; /** Returns number of child properties. @@ -918,10 +1036,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 @@ -952,7 +1067,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. @@ -961,7 +1076,7 @@ public: /** Returns highest level non-category, non-root parent. Useful when you - have nested wxCustomProperties/wxParentProperties. + have nested properties with children. @remarks If immediate parent is root or category, this will return the property itself. @@ -970,19 +1085,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; @@ -992,33 +1104,44 @@ 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; - /** - To acquire property's value as string, you should use this - function (instead of GetValueAsString()), as it may produce - more accurate value in future versions. + /** Returns text representation of property's value. + + @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. + + @remarks In older versions, this function used to be overridden to convert + property's value into a string representation. This function is + now handled by ValueToString(), and overriding this function now + will result in run-time assertion failure. + */ + virtual wxString GetValueAsString( int argFlags = 0 ) const; + + /** Synonymous to GetValueAsString(). + + @deprecated Use GetValueAsString() instead. @see GetValueAsString() */ - wxString GetValueString( int argFlags = 0 ) const; + wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const ); /** 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 @@ -1027,7 +1150,7 @@ public: int GetY() const; /** - Returns true if property has even one visible child. + Returns @true if property has even one visible child. */ bool HasVisibleChildren() const; @@ -1048,6 +1171,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. @@ -1081,7 +1217,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. @@ -1111,25 +1247,7 @@ public: /** Returns child property at index i. */ - wxPGProperty* Item( size_t i ) const; - - /** - Updates property value in case there were last minute - changes. If value was unspecified, it will be set to default. - Use only for properties that have TextCtrl-based editor. - - @remarks If you have code similar to - @code - // Update the value in case of last minute changes - if ( primary && propgrid->IsEditorsValueModified() ) - GetEditorClass()->CopyValueFromControl( this, primary ); - @endcode - in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler, - then replace it with call to this method. - - @return Returns @true if value changed. - */ - bool PrepareValueForDialogEditing( wxPropertyGrid* propgrid ); + wxPGProperty* Item( unsigned int i ) const; /** If property's editor is active, then update it's value. @@ -1144,9 +1262,25 @@ public: @param value Value of attribute. + + @remarks Setting attribute's value to Null variant will simply remove it + from property's set of attributes. */ void SetAttribute( const wxString& name, wxVariant value ); + /** + Sets property's background colour. + + @param colour + Background colour to use. + + @param recursively + If @true, children are affected recursively, and any categories + are not. + */ + void SetBackgroundColour( const wxColour& colour, + bool recursively = false ); + /** Sets editor for a property. @@ -1165,10 +1299,8 @@ 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. @@ -1177,12 +1309,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. @@ -1214,7 +1340,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. @@ -1231,6 +1357,32 @@ public: */ void SetName( const wxString& newName ); + /** + Changes what sort of parent this property is for its children. + + @param flag + Use one of the following values: wxPG_PROP_MISC_PARENT (for generic + parents), wxPG_PROP_CATEGORY (for categories), or + wxPG_PROP_AGGREGATE (for derived property classes with private + children). + + @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 recursively + If @true, children are affected recursively, and any categories + are not. + */ + void SetTextColour( const wxColour& colour, + bool recursively = false ); + /** Sets wxValidator for a property */ void SetValidator( const wxValidator& validator ); @@ -1245,15 +1397,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 @@ -1288,16 +1442,25 @@ 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 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} @@ -1312,7 +1475,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. */ @@ -1347,21 +1513,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. @@ -1371,26 +1532,27 @@ 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. */ - const wxString& GetLabel( size_t ind ) const; + const wxString& GetLabel( unsigned int ind ) const; /** Returns number of items. */ - size_t GetCount () const; + unsigned int GetCount() const; /** Returns value of item; */ - int GetValue( size_t ind ) const; + int GetValue( unsigned int ind ) const; /** Returns array of values matching the given strings. Unmatching strings @@ -1400,7 +1562,7 @@ 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; @@ -1431,31 +1593,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. @@ -1475,27 +1626,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; }; // -----------------------------------------------------------------------