X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/68bcfd2c10258b50924ad45391b6fbff0e83ce55..02fd8b9b6186623ed61019ac7e69ed9a4ef16773:/include/wx/propgrid/property.h diff --git a/include/wx/propgrid/property.h b/include/wx/propgrid/property.h index 1c209463c8..176db3d61e 100644 --- a/include/wx/propgrid/property.h +++ b/include/wx/propgrid/property.h @@ -75,8 +75,27 @@ public: // Render flags enum { + // We are painting selected item Selected = 0x00010000, - Control = 0x00020000 + + // We are painting item in choice popup + ChoicePopup = 0x00020000, + + // We are rendering wxOwnerDrawnComboBox control + // (or other owner drawn control, but that is only + // officially supported one ATM). + Control = 0x00040000, + + // We are painting a disable property + Disabled = 0x00080000, + + // We are painting selected, disabled, or similar + // item that dictates fore- and background colours, + // overriding any cell values. + DontUseCellFgCol = 0x00100000, + DontUseCellBgCol = 0x00200000, + DontUseCellColours = DontUseCellFgCol | + DontUseCellBgCol }; virtual void Render( wxDC& dc, @@ -145,14 +164,46 @@ private: }; +class WXDLLIMPEXP_PROPGRID wxPGCellData : public wxObjectRefData +{ + friend class wxPGCell; +public: + wxPGCellData(); + + void SetText( const wxString& text ) + { + m_text = text; + m_hasValidText = true; + } + void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; } + void SetFgCol( const wxColour& col ) { m_fgCol = col; } + void SetBgCol( const wxColour& col ) { m_bgCol = col; } + +protected: + virtual ~wxPGCellData() { } + + wxString m_text; + wxBitmap m_bitmap; + wxColour m_fgCol; + wxColour m_bgCol; + + // True if m_text is valid and specified + bool m_hasValidText; +}; + /** @class wxPGCell Base class for simple wxPropertyGrid cell information. */ -class WXDLLIMPEXP_PROPGRID wxPGCell +class WXDLLIMPEXP_PROPGRID wxPGCell : public wxObject { public: wxPGCell(); + wxPGCell(const wxPGCell& other) + : wxObject(other) + { + } + wxPGCell( const wxString& text, const wxBitmap& bitmap = wxNullBitmap, const wxColour& fgCol = wxNullColour, @@ -160,21 +211,50 @@ public: virtual ~wxPGCell() { } - void SetText( const wxString& text ) { m_text = text; } - void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; } - void SetFgCol( const wxColour& col ) { m_fgCol = col; } - void SetBgCol( const wxColour& col ) { m_bgCol = col; } + wxPGCellData* GetData() + { + return (wxPGCellData*) m_refData; + } + + const wxPGCellData* GetData() const + { + return (const wxPGCellData*) m_refData; + } + + bool HasText() const + { + return (m_refData && GetData()->m_hasValidText); + } + + /** + 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 ); + void SetBgCol( const wxColour& col ); - const wxString& GetText() const { return m_text; } - const wxBitmap& GetBitmap() const { return m_bitmap; } - const wxColour& GetFgCol() const { return m_fgCol; } - const wxColour& GetBgCol() const { return m_bgCol; } + const wxString& GetText() const { return GetData()->m_text; } + const wxBitmap& GetBitmap() const { return GetData()->m_bitmap; } + const wxColour& GetFgCol() const { return GetData()->m_fgCol; } + const wxColour& GetBgCol() const { return GetData()->m_bgCol; } + + wxPGCell& operator=( const wxPGCell& other ) + { + if ( this != &other ) + { + Ref(other); + } + return *this; + } protected: - wxString m_text; - wxBitmap m_bitmap; - wxColour m_fgCol; - wxColour m_bgCol; + virtual wxObjectRefData *CreateRefData() const + { return new wxPGCellData(); } + + virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const; }; @@ -242,7 +322,7 @@ public: data->IncRef(); variant.SetData(data); variant.SetName(it->first); - it++; + ++it; return true; } @@ -389,9 +469,6 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 /** @} */ -// Amalgam of flags that should be inherited by sub-properties -#define wxPG_INHERITED_PROPFLAGS (wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR) - // Combination of flags that can be stored by GetFlagsAsString #define wxPG_STRING_STORED_FLAGS \ (wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED) @@ -569,32 +646,32 @@ class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry : public wxPGCell { public: wxPGChoiceEntry(); - wxPGChoiceEntry( const wxPGChoiceEntry& entry ); - wxPGChoiceEntry( const wxString& label, - int value = wxPG_INVALID_VALUE ) - : wxPGCell(), m_value(value) + wxPGChoiceEntry(const wxPGChoiceEntry& other) + : wxPGCell(other) { - m_text = label; + m_value = other.m_value; } - wxPGChoiceEntry( const wxString& label, - int value, - const wxBitmap& bitmap, - const wxColour& fgCol = wxNullColour, - const wxColour& bgCol = wxNullColour ) - : wxPGCell(label, bitmap, fgCol, bgCol), m_value(value) + int value = wxPG_INVALID_VALUE ) + : wxPGCell(), m_value(value) { + SetText(label); } - virtual ~wxPGChoiceEntry() - { - } + virtual ~wxPGChoiceEntry() { } void SetValue( int value ) { m_value = value; } - int GetValue() const { return m_value; } - bool HasValue() const { return (m_value != wxPG_INVALID_VALUE); } + wxPGChoiceEntry& operator=( const wxPGChoiceEntry& other ) + { + if ( this != &other ) + { + Ref(other); + } + m_value = other.m_value; + return *this; + } protected: int m_value; @@ -612,26 +689,7 @@ public: void CopyDataFrom( wxPGChoicesData* data ); - // Takes ownership of 'item' - void Insert( int index, wxPGChoiceEntry* item ) - { - wxVector::iterator it; - if ( index == -1 ) - { - it = m_items.end(); - index = (int) m_items.size(); - } - else - { - it = m_items.begin() + index; - } - - // Need to fix value? - if ( item->GetValue() == wxPG_INVALID_VALUE ) - item->SetValue(index); - - m_items.insert(it, item); - } + wxPGChoiceEntry& Insert( int index, const wxPGChoiceEntry& item ); // Delete all entries void Clear(); @@ -641,10 +699,15 @@ public: return (unsigned int) m_items.size(); } - wxPGChoiceEntry* Item( unsigned int i ) const + const wxPGChoiceEntry& Item( unsigned int i ) const { - wxCHECK_MSG( i < GetCount(), NULL, "invalid index" ); + wxASSERT_MSG( i < GetCount(), "invalid index" ); + return m_items[i]; + } + wxPGChoiceEntry& Item( unsigned int i ) + { + wxASSERT_MSG( i < GetCount(), "invalid index" ); return m_items[i]; } @@ -657,7 +720,7 @@ public: } private: - wxVector m_items; + wxVector m_items; // So that multiple properties can use the same set int m_refCount; @@ -675,6 +738,8 @@ private: Each entry can have label, value, bitmap, text colour, and background colour. + @remarks If you do not specify value for entry, index is used. + @library{wxpropgrid} @category{propgrid} */ @@ -699,14 +764,30 @@ public: } } - /** Constructor. */ + /** + Constructor. + + @param labels + Labels for choices + + @param values + Values for choices. If NULL, indexes are used. + */ wxPGChoices( const wxChar** labels, const long* values = NULL ) { Init(); Set(labels,values); } - /** Constructor. */ + /** + Constructor. + + @param labels + Labels for choices + + @param values + Values for choices. If empty, indexes are used. + */ wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() ) { @@ -733,16 +814,27 @@ public: If did not have own copies, creates them now. If was empty, identical to set except that creates copies. + + @param labels + Labels for added choices. + + @param values + Values for added choices. If empty, relevant entry indexes are used. */ void Add( const wxChar** labels, const ValArrItem* values = NULL ); - /** Version that works with wxArrayString. */ - void Add( const wxArrayString& arr, const ValArrItem* values = NULL ); - /** Version that works with wxArrayString and wxArrayInt. */ - void Add( const wxArrayString& arr, const wxArrayInt& arrint ); + void Add( const wxArrayString& arr, const wxArrayInt& arrint = wxArrayInt() ); - /** Adds single item. */ + /** + Adds a single choice. + + @param label + Label for added choice. + + @param value + Value for added choice. If unspecified, index is used. + */ wxPGChoiceEntry& Add( const wxString& label, int value = wxPG_INVALID_VALUE ); @@ -810,14 +902,6 @@ public: wxArrayInt GetIndicesForStrings( const wxArrayString& strings, wxArrayString* unmatched = NULL ) const; - /** Returns true if choices in general are likely to have values - (depens on that all entries have values or none has) - */ - bool HasValues() const; - - bool HasValue( unsigned int i ) const - { return (i < m_data->GetCount()) && m_data->Item(i)->HasValue(); } - int Index( const wxString& str ) const; int Index( int val ) const; @@ -840,13 +924,13 @@ public: const wxPGChoiceEntry& Item( unsigned int i ) const { wxASSERT( IsOk() ); - return *m_data->Item(i); + return m_data->Item(i); } wxPGChoiceEntry& Item( unsigned int i ) { wxASSERT( IsOk() ); - return *m_data->Item(i); + return m_data->Item(i); } /** Removes count items starting at position nIndex. */ @@ -908,7 +992,8 @@ public: #ifndef SWIG void operator= (const wxPGChoices& a) { - AssignData(a.m_data); + if (this != &a) + AssignData(a.m_data); } wxPGChoiceEntry& operator[](unsigned int i) @@ -974,7 +1059,11 @@ public: variant << value; SetValue(variant); - // If has private child properties then create them here, e.g.: + // If has private child properties then create them here. Also + // set flag that indicates presence of private children. E.g.: + // + // SetParentalType(wxPG_PROP_AGGREGATE); + // // AddChild( new wxStringProperty( "Subprop 1", // wxPG_LABEL, // value.GetSubProp1() ) ); @@ -1032,7 +1121,7 @@ public: 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() + composite property string value (as generated by ValueToString() called with this same flag). @return Returns @true if resulting wxVariant value was different. @@ -1080,22 +1169,24 @@ public: int number, int argFlags = 0 ) const; #endif // !defined(SWIG) || defined(CREATE_VCW) + /** + Converts property value into a text representation. -public: - /** Returns text representation of property's value. + @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 composite property string value. + 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. @@ -1104,7 +1195,7 @@ public: @return true if value was changed. */ - bool SetValueFromString( const wxString& text, int flags = 0 ); + bool SetValueFromString( const wxString& text, int flags = wxPG_PROGRAMMATIC_VALUE ); /** Converts integer to a value, and if succesful, calls SetValue() on it. Default behavior is to do nothing. @@ -1278,7 +1369,7 @@ public: colour) pen for drawing framing rectangle. It can be changed as well. - @see GetValueAsString() + @see ValueToString() */ virtual void OnCustomPaint( wxDC& dc, const wxRect& rect, @@ -1332,18 +1423,14 @@ public: */ 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. */ @@ -1365,6 +1452,11 @@ public: return false; } + /** + Deletes children of the property. + */ + void DeleteChildren(); + /** Removes entry from property's wxPGChoices and editor control (if it is active). @@ -1386,8 +1478,15 @@ public: else ClearFlag( wxPG_PROP_USES_COMMON_VALUE ); } - /** 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 + { + wxString s; + DoGenerateComposedValue(s); + return s; + } /** Returns property's label. */ const wxString& GetLabel() const { return m_label; } @@ -1434,24 +1533,38 @@ public: } #endif - /** 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. */ - wxString GetValueString( int argFlags = 0 ) const; + virtual wxString GetValueAsString( int argFlags = 0 ) const; - void UpdateControl( wxWindow* primary ); + /** Synonymous to GetValueAsString(). - /** Returns wxPGCell of given column, NULL if none. wxPGProperty - will retain ownership of the cell object. + @deprecated Use GetValueAsString() instead. + + @see GetValueAsString() */ - wxPGCell* GetCell( unsigned int column ) const - { - if ( column >= m_cells.size() ) - return NULL; + wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const ); - return (wxPGCell*) m_cells[column]; - } + /** + Returns wxPGCell of given column. + */ + const wxPGCell& GetCell( unsigned int column ) const; + + wxPGCell& GetCell( unsigned int column ); /** Return number of displayed common values for this property. */ @@ -1459,7 +1572,7 @@ public: wxString GetDisplayedString() const { - return GetValueString(0); + return GetValueAsString(0); } /** Returns property grid where property lies. */ @@ -1680,6 +1793,32 @@ public: void SetAttributes( const wxPGAttributeStorage& attributes ); + /** + 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 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 ); + #ifndef SWIG /** Sets editor for a property. @@ -1701,11 +1840,10 @@ public: */ inline void SetEditor( const wxString& editorName ); - /** Sets cell information for given column. - - Note that the property takes ownership of given wxPGCell instance. + /** + Sets cell information for given column. */ - void SetCell( int column, wxPGCell* cellObj ); + void SetCell( int column, const wxPGCell& cell ); /** Sets common value selected for this property. -1 for none. */ @@ -1795,6 +1933,27 @@ public: inline 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 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. + */ + void SetParentalType( int flag ) + { + m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS); + m_flags |= flag; + } + void SetValueToUnspecified() { wxVariant val; // Create NULL variant @@ -1883,7 +2042,23 @@ public: */ void AdaptListToValue( wxVariant& list, wxVariant* value ) const; - /** This is used by properties that have fixed sub-properties. */ + /** + 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: + + @code + wxPGProperty* prop = new wxStringProperty(wxS("Property")); + prop->SetParentalType(wxPG_PROP_MISC_PARENT); + wxPGProperty* prop2 = new wxStringProperty(wxS("Property2")); + prop->AddChild(prop2); + @endcode + */ void AddChild( wxPGProperty* prop ); /** Returns height of children, recursively, and @@ -1910,11 +2085,8 @@ public: /** Returns index of given child property. */ int Index( const wxPGProperty* p ) const; - /** Deletes all sub-properties. */ - void Empty(); - // Puts correct indexes to children - void FixIndexesOfChildren( unsigned int starthere = 0 ); + void FixIndicesOfChildren( unsigned int starthere = 0 ); #ifndef SWIG // Returns wxPropertyGridPageState in which this property resides. @@ -1959,6 +2131,13 @@ public: #ifndef SWIG + // Returns various display-related information for given column + void GetDisplayInfo( unsigned int column, + int choiceIndex, + int flags, + wxString* pString, + const wxPGCell** pCell ); + static wxString* sm_wxPG_LABEL; /** This member is public so scripting language bindings @@ -1967,9 +2146,49 @@ public: void* m_clientData; protected: - /** Returns text for given column. + + /** + Sets property cell in fashion that reduces number of exclusive + copies of cell data. Used when setting, for instance, same + background colour for a number of properties. + + @param firstCol + First column to affect. + + @param lastCol + Last column to affect. + + @param preparedCell + Pre-prepared cell that is used for those which cell data + before this matched unmodCellData. + + @param srcData + If unmodCellData did not match, valid cell data from this + is merged into cell (usually generating new exclusive copy + of cell's data). + + @param unmodCellData + If cell's cell data matches this, its cell is now set to + preparedCell. + + @param ignoreWithFlags + Properties with any one of these flags are skipped. + + @param recursively + If @true, apply this operation recursively in child properties. + */ + void AdaptiveSetCell( unsigned int firstCol, + unsigned int lastCol, + const wxPGCell& preparedCell, + const wxPGCell& srcData, + wxPGCellData* unmodCellData, + FlagType ignoreWithFlags, + bool recursively ); + + /** + Makes sure m_cells has size of column+1 (or more). */ - wxString GetColumnText( unsigned int col ) const; + void EnsureCells( unsigned int column ); /** Returns (direct) child property with given name (or NULL if not found), with hint index. @@ -1988,20 +2207,22 @@ protected: int index = -1, bool correct_mode = true ); + void DoGenerateComposedValue( wxString& text, + int argFlags = wxPG_VALUE_IS_CURRENT, + const wxVariantList* valueOverrides = NULL, + wxPGHashMapS2S* childResults = NULL ) const; + void DoSetName(const wxString& str) { m_name = str; } - // Call for after sub-properties added with AddChild - void PrepareSubProperties(); + /** Deletes all sub-properties. */ + void Empty(); + + void InitAfterAdded( wxPropertyGridPageState* pageState, + wxPropertyGrid* propgrid ); // Removes child property with given pointer. Does not delete it. void RemoveChild( wxPGProperty* p ); - void SetParentalType( int flag ) - { - m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS); - m_flags |= flag; - } - void SetParentState( wxPropertyGridPageState* pstate ) { m_parentState = pstate; } @@ -2015,7 +2236,7 @@ protected: wxString m_label; wxString m_name; wxPGProperty* m_parent; - wxPropertyGridPageState* m_parentState; + wxPropertyGridPageState* m_parentState; wxClientData* m_clientObject; @@ -2035,7 +2256,7 @@ protected: wxArrayPGProperty m_children; // Extended cell information - wxArrayPtrVoid m_cells; + wxVector m_cells; // Choices shown in drop-down list of editor control. wxPGChoices m_choices; @@ -2064,9 +2285,6 @@ protected: // (essentially this is category's depth, if none then equals m_depth). unsigned char m_depthBgCol; - unsigned char m_bgColIndex; // Background brush index. - unsigned char m_fgColIndex; // Foreground colour index. - private: // Called in constructors. void Init(); @@ -2150,9 +2368,9 @@ public: int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const; -protected: - virtual wxString GetValueAsString( int argFlags ) const; + virtual wxString ValueToString( wxVariant& value, int argFlags ) const; +protected: void SetTextColIndex( unsigned int colInd ) { m_capFgColIndex = (wxByte) colInd; } unsigned int GetTextColIndex() const