wxPGProperty Class Reference

wxPGProperty, alias wxBasePropertyClass, is base class for properties. Information here is provided primarily for anyone who creates new properties, since all operations on properties should be done via wxPropertyGrid's or wxPropertyGridManager's methods. More...

#include <propgrid.h>

Inheritance diagram for wxPGProperty:

wxPGPropertyWithChildren wxCustomPropertyClass wxParentPropertyClass wxPGRootPropertyClass wxPropertyCategoryClass List of all members.

Public Types

typedef void * ClientDataType
typedef short FlagType

Public Member Functions

int AppendChoice (const wxString &label, int value=INT_MAX)
bool CanHaveExtraChildren () const
void ClearFlag (FlagType flag)
void DeleteChoice (int index)
virtual const wxPGEditorDoGetEditorClass () const
virtual wxValidator * DoGetValidator () const
virtual wxPGVariant DoGetValue () const
void DoSetName (const wxString &str)
virtual void DoSetValue (wxPGVariant value)
bool EnsureDataExt ()
unsigned int GetArrIndex () const
wxString GetAttributes (unsigned int flagmask=0xFFFF)
size_t GetChildCount () const
virtual int GetChoiceInfo (wxPGChoiceInfo *choiceinfo)
virtual const wxPGPropertyClassInfoGetClassInfo () const=0
virtual const wxChar * GetClassName () const=0
ClientDataType GetClientData () const
wxPGPropertyDataExtGetDataExt ()
unsigned int GetDepth () const
wxString GetDisplayedString () const
const wxPGEditorGetEditorClass () const
unsigned int GetFlags () const
wxPropertyGridGetGrid () const
wxString GetHelpString () const
wxPGId GetId ()
virtual wxSize GetImageSize () const
unsigned int GetIndexInParent () const
const wxString & GetLabel () const
const wxPGPropertyGetLastVisibleSubItem () const
wxPGPropertyGetMainParent () const
int GetMaxLength () const
const wxString & GetName () const
wxPGPropertyWithChildrenGetParent () const
signed char GetParentingType () const
wxPropertyGridStateGetParentState () const
const wxChar * GetType () const
wxValidator * GetValidator () const
virtual wxString GetValueAsString (int argFlags=0) const
wxVariant GetValueAsVariant () const
wxBitmap * GetValueImage () const
virtual const wxPGValueTypeGetValueType () const=0
const wxPGValueTypeGetValueTypePtr () const
int GetY () const
bool HasFlag (FlagType flag) const
bool Hide (bool hide)
void Init (const wxString &label, const wxString &name)
int InsertChoice (const wxString &label, int index, int value=INT_MAX)
bool IsEnabled () const
bool IsFlagSet (FlagType flag) const
bool IsKindOf (wxPGPropertyClassInfo &info)
bool IsOk () const
bool IsSomeParent (wxPGProperty *candidate_parent) const
bool IsSubProperty () const
bool IsValueUnspecified () const
virtual void OnCustomPaint (wxDC &dc, const wxRect &rect, wxPGPaintData &paintdata)
virtual bool OnEvent (wxPropertyGrid *propgrid, wxWindow *wnd_primary, wxEvent &event)
bool PrepareValueForDialogEditing (wxPropertyGrid *propgrid)
bool RecreateEditor ()
void SetAttrib (int id, wxVariant value)
virtual void SetAttribute (int id, wxVariant &value)
void SetAttributes (const wxString &attributes)
bool SetChoices (const wxArrayString &labels, const wxArrayInt &values=(*((wxArrayInt *) NULL)))
bool SetChoices (wxPGChoices &choices)
void SetChoiceSelection (int newValue, const wxPGChoiceInfo &choiceInfo)
void SetChoicesExclusive ()
void SetClientData (ClientDataType clientData)
void SetEditor (const wxString &editorName)
void SetEditor (const wxPGEditor *editor)
void SetFlag (FlagType flag)
void SetHelpString (const wxString &helpString)
void SetLabel (const wxString &label)
bool SetMaxLength (int maxLen)
void SetValidator (const wxValidator &validator)
virtual bool SetValueFromInt (long value, int flags=0)
virtual bool SetValueFromString (const wxString &text, int flags=0)
void SetValueImage (wxBitmap &bmp)
void SetValueToUnspecified ()
void ShowError (const wxString &msg)
bool StdValidationProcedure (wxPGVariant value)
void UpdateControl (wxWindow *primary)
bool UsesAutoUnspecified () const
 wxPGProperty (const wxString &label, const wxString &name)
 wxPGProperty ()
virtual ~wxPGProperty ()

Protected Member Functions

void Init ()

Protected Attributes

unsigned int m_arrIndex
unsigned char m_bgColIndex
ClientDataType m_clientData
wxPGPropertyDataExtm_dataExt
unsigned char m_depth
unsigned char m_depthBgCol
unsigned char m_fgColIndex
FlagType m_flags
wxString m_label
short m_maxLen
wxString m_name
wxPGPropertyWithChildrenm_parent
signed char m_parentingType
int m_y

Detailed Description

wxPGProperty, alias wxBasePropertyClass, is base class for properties. Information here is provided primarily for anyone who creates new properties, since all operations on properties should be done via wxPropertyGrid's or wxPropertyGridManager's methods.

Remarks:


Constructor & Destructor Documentation

wxPGProperty::wxPGProperty  ) 
 

Basic constructor.

Should not be necessary to override.

wxPGProperty::wxPGProperty const wxString &  label,
const wxString &  name
 

Constructor.

Real used property classes should have constructor of this style:

// If MyValueType is a class, then it should be a constant reference // (e.g. const MyValueType& ) instead. wxMyProperty( const wxString& label, const wxString& name, MyValueType value ) : wxPGProperty { // Only required if MyValueType is not built-in default // (wxString, long, double, bool, and wxArrayString are; // wxFont, wxColour, etc. are not). wxPG_INIT_REQUIRED_TYPE(MyValueType) DoSetValue(value); // Generally recommended way to set the initial value. // If has child properties (i.e. wxPGPropertyWithChildren is used // as the parent class), then create children here. For example: // AddChild( new wxStringProperty( wxT("Subprop 1"), wxPG_LABEL, value.GetSubProp1() ) ); }

Of course, in this example, wxPGProperty could also be wxPGPropertyWithChildren (if it has sub-properties) or actually any other property class.

virtual wxPGProperty::~wxPGProperty  )  [virtual]
 

Virtual destructor.

It is customary for derived properties to override this.


Member Function Documentation

int wxPGProperty::AppendChoice const wxString &  label,
int  value = INT_MAX
[inline]
 

Adds entry to property's wxPGChoices and editor control (if it is active).

Returns index of item added.

bool wxPGProperty::CanHaveExtraChildren  )  const [inline]
 

Returns true if extra children can be added for this property (i.e.

it is wxPropertyCategory or wxCustomProperty)

void wxPGProperty::DeleteChoice int  index  ) 
 

Removes entry from property's wxPGChoices and editor control (if it is active).

If selected item is deleted, then the value is set to unspecified.

virtual const wxPGEditor* wxPGProperty::DoGetEditorClass  )  const [virtual]
 

Returns pointer to an instance of editor class.

Reimplemented in wxPGRootPropertyClass, and wxPropertyCategoryClass.

virtual wxValidator* wxPGProperty::DoGetValidator  )  const [virtual]
 

Returns pointer to the wxValidator that should be used with the editor of this property (NULL for no validator).

Setting validator explicitly via SetPropertyValidator will override this.

In most situations, code like this should work well (macros are used to maintain one actual validator instance, so on the second call the function exits within the first macro):

wxValidator* wxMyPropertyClass::DoGetValidator () const { WX_PG_DOGETVALIDATOR_ENTRY() wxMyValidator* validator = new wxMyValidator(...); ... prepare validator... WX_PG_DOGETVALIDATOR_EXIT(validator) }

Remarks:
You can get common filename validator by returning wxFilePropertyClass::GetClassValidator(). wxDirProperty, for example, uses it.

virtual wxPGVariant wxPGProperty::DoGetValue  )  const [virtual]
 

Returns properly constructed wxPGVariant.

Reimplemented in wxParentPropertyClass, and wxCustomPropertyClass.

virtual void wxPGProperty::DoSetValue wxPGVariant  value  )  [virtual]
 

Sets property's internal value.

Parameters:
value Simple container with GetString(), GetLong() etc. methods. Currently recommended means to extract value is to use wxPGVariantToXXX(value) macro.
Remarks:
Example pseudo-implementation with comments:
void wxMyProperty::DoSetValue ( wxPGVariant value ) { // A) Get value. For example const wxMyValueType* pvalue = wxPGVariantToWxObjectPtr(value,wxMyValueType); // or: const wxString& str = wxPGVariantToString(value); // or: long val = wxPGVariantToLong(value); // B) If value is wxObject or void based with NULL default, then handle that: if ( pvalue ) m_value = *pvalue; else pmyvalue->SetToDefault(); // Otherwise // m_value = *pvalue; // is sufficient. // C) If has children, this should be here (before displaying in control). RefreshChildren(); }

Reimplemented in wxParentPropertyClass, and wxCustomPropertyClass.

bool wxPGProperty::EnsureDataExt  ) 
 

If property did not have data extension, one is created now (returns true in that case).

wxString wxPGProperty::GetAttributes unsigned int  flagmask = 0xFFFF  ) 
 

Returns comma-delimited string of property attributes.

size_t wxPGProperty::GetChildCount  )  const
 

Returns number of children (always 0 for normal properties).

virtual int wxPGProperty::GetChoiceInfo wxPGChoiceInfo *  choiceinfo  )  [virtual]
 

Returns current value's index to the choice control.

May also return, through pointer arguments, strings that should be inserted to that control. Irrelevant to classes which do not employ wxPG_EDITOR(Choice) or similar.

Remarks:
  • If returns -1 in choiceinfo->m_itemCount, then in that case this class be derived from wxBaseEnumPropertyClass (see propdev.h) and GetEntry is used to fill an array (slower, but handier if you don't store your labels as arrays of strings).
  • Must not crash even if property's set of choices is uninitialized (i.e. it points to wxPGGlobalVars->m_emptyConstants).

Reimplemented in wxCustomPropertyClass.

virtual const wxPGPropertyClassInfo* wxPGProperty::GetClassInfo  )  const [pure virtual]
 

Returns classinfo of the property class.

Implemented in wxPGRootPropertyClass, and wxPropertyCategoryClass.

virtual const wxChar* wxPGProperty::GetClassName  )  const [pure virtual]
 

Returns classname (for example, "wxStringProperty" for wxStringProperty) of a property class.

Implemented in wxPGRootPropertyClass, and wxPropertyCategoryClass.

wxPGPropertyDataExt* wxPGProperty::GetDataExt  )  [inline]
 

Returns property's data extension (NULL if none).

wxPropertyGrid* wxPGProperty::GetGrid  )  const
 

Returns property grid where property lies.

wxPGId wxPGProperty::GetId  )  [inline]
 

Returns property id.

virtual wxSize wxPGProperty::GetImageSize  )  const [virtual]
 

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.

Remarks:

Reimplemented in wxCustomPropertyClass.

unsigned int wxPGProperty::GetIndexInParent  )  const [inline]
 

Returns position in parent's array.

const wxString& wxPGProperty::GetLabel  )  const [inline]
 

Returns property's label.

const wxPGProperty* wxPGProperty::GetLastVisibleSubItem  )  const
 

Returns last visible sub-property, recursively.

wxPGProperty* wxPGProperty::GetMainParent  )  const
 

Returns highest level non-category, non-root parent.

Useful when you have nested wxCustomProperties/wxParentProperties.

Remarks:
Thus, if immediate parent is root or category, this will return the property itself.

const wxString& wxPGProperty::GetName  )  const [inline]
 

Returns property's name (alternate way to access property).

wxPGPropertyWithChildren* wxPGProperty::GetParent  )  const [inline]
 

Return parent of property.

signed char wxPGProperty::GetParentingType  )  const [inline]
 

Returns 0 for normal items.

1 for categories, -1 for other properties with children, -2 for wxCustomProperty (mostly like -1 ones but with few expections).

Remarks:
Should not be overridden by new custom properties. Usually only used internally.

wxPropertyGridState* wxPGProperty::GetParentState  )  const
 

Returns wxPropertyGridState to which this property belongs.

Reimplemented in wxPGPropertyWithChildren.

const wxChar* wxPGProperty::GetType  )  const [inline]
 

Returns type name of property that is compatible with CreatePropertyByType.

and wxVariant::GetType.

wxValidator* wxPGProperty::GetValidator  )  const [inline]
 

Gets assignable version of property's validator.

virtual wxString wxPGProperty::GetValueAsString int  argFlags = 0  )  const [virtual]
 

Returns text representation of property's value.

Parameters:
argFlags If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one (they may be different).

Reimplemented in wxParentPropertyClass, wxCustomPropertyClass, wxPGPropertyWithChildren, and wxPropertyCategoryClass.

wxVariant wxPGProperty::GetValueAsVariant  )  const
 

Returns value as wxVariant.

virtual const wxPGValueType* wxPGProperty::GetValueType  )  const [pure virtual]
 

Returns pointer to the object that has methods related to the value type of this property.

Keep atleast this method abstract so the class is kept abstract.

Implemented in wxPGRootPropertyClass, and wxPropertyCategoryClass.

int wxPGProperty::GetY  )  const [inline]
 

Gets pre-calculated top y coordinate of property graphics.

This cannot be relied on all times (wxPropertyGrid knows when :) ), and value is -1 if property is not visible.

bool wxPGProperty::Hide bool  hide  )  [inline]
 

Hides or reveals the property.

Parameters:
hide true for hide, false for reveal.

void wxPGProperty::Init const wxString &  label,
const wxString &  name
 

Initializes the property.

Usually only called in the constructor.

int wxPGProperty::InsertChoice const wxString &  label,
int  index,
int  value = INT_MAX
 

Adds entry to property's wxPGChoices and editor control (if it is active).

Returns index of item added.

bool wxPGProperty::IsOk  )  const [inline]
 

Returns true if property is valid and wxPropertyGrid methods can operate on it safely.

bool wxPGProperty::IsSubProperty  )  const [inline]
 

Returns true if this is a sub-property.

virtual void wxPGProperty::OnCustomPaint wxDC &  dc,
const wxRect &  rect,
wxPGPaintData paintdata
[virtual]
 

Override to paint an image in front of the property value text or drop-down list item (but only if wxPGProperty::GetImageSize is overridden as well).

If property's GetImageSize() returns size that has height != 0 but less than row height ( < 0 has special meanings), wxPropertyGrid calls this method to draw a custom image in a limited area in front of the editor control or value text/graphics, and if control has drop-down list, then the image is drawn there as well (even in the case GetImageSize() returned higher height than row height).

NOTE: Following applies when GetImageSize() returns a "flexible" height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items: If rect.x is < 0, then this is a measure item call, which means that dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight to the height of the image of item at index paintdata.m_choiceItem. This call may be done even as often as once every drop-down popup show.

Parameters:
dc wxDC to paint on.
rect Box reserved for custom graphics. Includes surrounding rectangle, if any. If x is < 0, then this is a measure item call (see above).
paintdata wxPGPaintData structure with much useful data.
Remarks:
  • You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth must be set to the full width drawn in pixels.
  • Due to technical reasons, rect's height will be default even if custom height was reported during measure call.
  • Changing font and text colour affects the text drawn next to the painted image (which is done immediately after the OnCustomPaint call finishes).
  • Brush is guaranteed to be default background colour. It has been already used to clear the background of area being painted. It can be modified.
  • 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 also:

Reimplemented in wxCustomPropertyClass.

virtual bool wxPGProperty::OnEvent wxPropertyGrid propgrid,
wxWindow *  wnd_primary,
wxEvent &  event
[virtual]
 

Events received by editor widgets are processed here.

Note that editor class usually processes most events. Some, such as button press events of TextCtrlAndButton class, should be handled here. Also, if custom handling for regular events is desired, then that can also be done (for example, wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED).

Parameters:
event Associated wxEvent.
Return values:
Should return true if any changes in value should be reported. This is case, for example, when enter is pressed in wxTextCtrl.

bool wxPGProperty::PrepareValueForDialogEditing wxPropertyGrid propgrid  ) 
 

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
// Update the value in case of last minute changes if ( primary && propgrid->IsEditorsValueModified() ) GetEditorClass()->CopyValueFromControl( this, primary );
in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler, then replace it with call to this method.
Return values:
True if value changed.

bool wxPGProperty::RecreateEditor  ) 
 

If property's editor is created this forces its recreation.

Useful in SetAttribute etc. Returns true if actually did anything.

virtual void wxPGProperty::SetAttribute int  id,
wxVariant &  value
[virtual]
 

Sets an attribute of this property.

This is quite property class specific, and there are no common attributes. Note that attribute may be specific to a property instance, or it may affect all properties of its class.

Parameters:
id Identifier of attribute
value Value for that attribute.

Reimplemented in wxCustomPropertyClass.

void wxPGProperty::SetAttributes const wxString &  attributes  ) 
 

Sets attributes from a comma-delimited string.

bool wxPGProperty::SetChoices const wxArrayString &  labels,
const wxArrayInt &  values = (*((wxArrayInt *) NULL))
[inline]
 

Sets new set of choices for property.

bool wxPGProperty::SetChoices wxPGChoices choices  ) 
 

Sets new set of choices for property.

void wxPGProperty::SetChoiceSelection int  newValue,
const wxPGChoiceInfo &  choiceInfo
 

Changes value of a property with choices, but only works if the value type is long or string.

void wxPGProperty::SetChoicesExclusive  ) 
 

If property has choices and they are not yet exclusive, new such copy of them will be created.

void wxPGProperty::SetClientData ClientDataType  clientData  )  [inline]
 

Sets client data (void*) of a property.

Remarks:
This untyped client data has to be deleted manually.

void wxPGProperty::SetEditor const wxString &  editorName  )  [inline]
 

Sets editor for a property.

void wxPGProperty::SetEditor const wxPGEditor editor  )  [inline]
 

Sets editor for a property.

bool wxPGProperty::SetMaxLength int  maxLen  )  [inline]
 

Set max length of text editor.

void wxPGProperty::SetValidator const wxValidator &  validator  )  [inline]
 

Sets wxValidator for a property.

virtual bool wxPGProperty::SetValueFromInt long  value,
int  flags = 0
[virtual]
 

Converts integer to a value, and if succesfull, calls DoSetValue() on it.

Default behaviour is to do nothing.

Parameters:
value Int to get the value from.
flags If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
Return values:
true if value was changed.

Reimplemented in wxCustomPropertyClass.

virtual bool wxPGProperty::SetValueFromString const wxString &  text,
int  flags = 0
[virtual]
 

Converts string to a value, and if succesfull, calls DoSetValue() on it.

Default behaviour is to do nothing.

Parameters:
text String to get the value from.
report_error If true, invalid string will be reported (prefer to use wxLogError).
Return values:
true if value was changed.

Reimplemented in wxCustomPropertyClass, and wxPGPropertyWithChildren.

void wxPGProperty::SetValueImage wxBitmap &  bmp  ) 
 

Set wxBitmap in front of the value.

This bitmap will be ignored if property class has implemented OnCustomPaint.

bool wxPGProperty::UsesAutoUnspecified  )  const
 

Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.


The documentation for this class was generated from the following file:
Generated on Mon Oct 29 16:56:23 2007 for wxPropertyGrid by doxygen 1.3.6