The VCF Website Home   |   Online Discussion Forums   |   Sourceforge.net Project Page

VCF::PropertyEditor Class Reference

This is the common base class for any editor that is specific of any property. More...

#include <vcf/ApplicationKit/PropertyEditor.h>

Inheritance diagram for VCF::PropertyEditor:

List of all members.

Public Types
enum	PropertyAttributes {   paHasValues = 0x01, paSortValues = 0x0100, paHasSubProperties = 0x02, paAllowsMultiSelect = 0x04,   paReadOnly = 0x08, paNeedsCustomPaint = 0x010, paUsesModalDialogForEditing = 0x020, paValueNeedsDuplicating = 0x040,   paEditorRequestsProperty = 0x080, paCompositeValue = 0x0100, paOverridePropertyDescription = 0x010000, paOverridePropertyName = 0x020000 }
	Defines a set of different attributes that the getAttributes() can return. More...
Public Member Functions
virtual	~PropertyEditor ()
virtual void	setProperty (Property *property)=0
	This sets the current property instance for the property editor.
virtual bool	equalTo (PropertyEditor *editor)=0
	This method needs to be oveeriden so to specify when two PropertyEditor(s) can be considered equal.
virtual int	getAttributes ()=0
	This method returns a mask of potential attributes.
virtual void	internal_setPropertyType (const String &type)=0
	Don't call this - this is used strictly by the framework.
virtual String	getPropertyType ()=0
	Returns the property type that this editor instance is associated with.
virtual Component *	getRootDesignerComponent ()=0
	returns the root component that is being edited in a form designer.
virtual void	setRootDesignerComponent (Component *rootDesigner)=0
	Sets the root component that is being edited in a form designer.
virtual Control *	createEditingControl ()=0
	Returns a control instance that belongs to this editor.
virtual void	edit ()=0
	This method is used to edit the property value.
virtual void	paintValue (VariantData *value, GraphicsContext *context, const Rect &bounds, const DrawUIState &state)=0
	Paints a representation of the editor.
virtual VariantData *	getValue ()=0
	Returns the value for the property.
virtual void	setValue (VariantData *value)=0
	Set's the value on the property editor.
virtual String	getValueAsText ()=0
	Like getValue(), but this returns the value in text format.
virtual void	setValueAsText (const String &textValue)=0
	Like setValue() but allows the value to be a string.
virtual std::vector< String >	getStringValues ()=0
	Returns an array of potential values for the property.
virtual std::vector< PropertyEditor * >	getSubProperties ()=0
	Returns a array of proeprty editors from the current value of this editor.
virtual bool	sort (const String &strVal1, const String &strVal2)=0
	only implement this if sortValues() returns true.
virtual String	getPropertyDescription ()=0
	This returns a string that describes the property.
virtual String	getPropertyName ()=0
	This returns a string that describes the property.
bool	hasValues ()
bool	sortValues ()
bool	hasSubProperties ()
bool	allowsMultiSelect ()
bool	isReadOnly ()
bool	needsCustomPaint ()
bool	usesModalDialogForEditing ()
bool	valueNeedsDuplicating ()
bool	overridesPropertyDescription ()
bool	overridesPropertyName ()
bool	editorRequestsProperty ()
bool	isCompositeValue ()

---

Detailed Description

This is the common base class for any editor that is specific of any property.

See also:

VCF::Property

Any property, and in general any kind of data, can be changed through an appropriate GUI interface called editor. A text editor is good for many kind of data, but some of them are more easily chaged through more specific editors. For example a ComboBox control can be considered an appropriate editor for any boolean value, or for any enumerated value. The VCF library makes readily available some of them.

the editor is used by the host in order to display the property content, retrieve possible values, and to provide a possible UI for performing the editing. The steps are something like this:

• the host selects a source object
• the host retrieves a list of all properties for the source objects
• for each property the

  See also:

  Object::getClass

  Class

  Property

---

Member Enumeration Documentation

enum VCF::PropertyEditor::PropertyAttributes

Defines a set of different attributes that the getAttributes() can return. Enumerator: paHasValues  Indicates that the property editor can return a vector of string values that represent possible values for the property. For example, a color property editor might return a list of color names. A Font editor might return a list of system fonts. paSortValues  Indicates that the values returned by the editor need to be sorted. The sort process should call the sort() method while iterating through the list. paHasSubProperties  Indicates that the source object's property itself has sub properties. Things like a font or color property may use this to indicate separate elements that can be set. paAllowsMultiSelect  Indicates whether or not the editor allows multiple selection. If is does then the implementor needs to implement setSources paReadOnly  Indicates that the editor is read only - the value cannot be changed is only for display. paNeedsCustomPaint  Indicates that the editor can paint it's representation when not active. paUsesModalDialogForEditing  This indicates that the implementor will popup a modal dialog when the edit() method is called. paValueNeedsDuplicating  This indicates that the property value needs to be cloned. It implies that the property is an Object of some type (if this is not the case this indicates an error condition). The object should be cloned by a call to the original object's Object::clone() method. paEditorRequestsProperty  paCompositeValue  This indicates that the proeprty editor's value is part of a set of values, such as a bit mask. paOverridePropertyDescription  This indicates to the host that the property editor's string description of the property should be used over the value that is retreived from calling Property::getDescription(). paOverridePropertyName  This indicates to the host that the property editor's string name of the property should be used over the value that is retreived from calling Property::getName().

---

Constructor & Destructor Documentation

virtual VCF::PropertyEditor::~PropertyEditor (   )  [inline, virtual]

---

Member Function Documentation

bool VCF::PropertyEditor::allowsMultiSelect (   )  [inline]

virtual Control* VCF::PropertyEditor::createEditingControl (   )  [pure virtual]

Returns a control instance that belongs to this editor. This control instance is managed by the tool using this property editor so you just need to create it. This may be called multiple times, it is the callers responsibility to delete the control, the editor implementor does not need to worry about this. For simple editors this may return null which will mean the implementation of the UI conntrol is up to the host environment. Typically editors for things like numbers, text, etc, will by default use an edit control or, if the property editor support a list of values, a combo box. Returns: Control a new instance of the control for this editor or NULL if the editor doesn't support this. Implemented in VCF::AbstractPropertyEditor.

virtual void VCF::PropertyEditor::edit (   )  [pure virtual]

This method is used to edit the property value. This is an optional method to implement, and only needs to be done if createEditingControl() returns a non null value. If createEditingControl() is NULL then it's assumed that the actual editing process will be completely handled by the host of the property editor. If the implementor does edit this method, then it's up to the implemementor to properly transfer the contents of the propert value to the control. Implemented in VCF::AbstractPropertyEditor, VCF::ColorPropertyEditor, VCF::FontPropertyEditor, VCF::ImageFilenamePropertyEditor, and VCF::ImagePropertyEditor.

bool VCF::PropertyEditor::editorRequestsProperty (   )  [inline]

virtual bool VCF::PropertyEditor::equalTo (  PropertyEditor *  editor  )  [pure virtual]

This method needs to be oveeriden so to specify when two PropertyEditor(s) can be considered equal. Implemented in VCF::AbstractPropertyEditor.

virtual int VCF::PropertyEditor::getAttributes (   )  [pure virtual]

This method returns a mask of potential attributes. Implemented in VCF::AbstractPropertyEditor.

virtual String VCF::PropertyEditor::getPropertyDescription (   )  [pure virtual]

This returns a string that describes the property. A host that displays a UI should first try and call the property's Property::getDescription() method. If this returns an empty string, then the host should call the property editor's getPropertyDescription(). See also: Property::getDescription() paOverridePropertyDescription Implemented in VCF::AbstractPropertyEditor.

virtual String VCF::PropertyEditor::getPropertyName (   )  [pure virtual]

This returns a string that describes the property. A host that displays a UI should first try and call the property's Property::getName() method. If this returns an empty string, then the host should call the property editor's getPropertyName(). See also: Property::getName() paOverridePropertyName Implemented in VCF::AbstractPropertyEditor.

virtual String VCF::PropertyEditor::getPropertyType (   )  [pure virtual]

Returns the property type that this editor instance is associated with. Implemented in VCF::AbstractPropertyEditor.

virtual Component* VCF::PropertyEditor::getRootDesignerComponent (   )  [pure virtual]

returns the root component that is being edited in a form designer. This may or may not be a control. Implemented in VCF::AbstractPropertyEditor.

virtual std::vector<String> VCF::PropertyEditor::getStringValues (   )  [pure virtual]

Returns an array of potential values for the property. Only usable if the PropertEditor::paHasValues bit is set. See also: PropertEditor::paHasValues Implemented in VCF::AbstractPropertyEditor, VCF::BoolPropertyEditor, VCF::EnumPropertyEditor, VCF::CursorPropertyEditor, and VCF::ColorPropertyEditor.

virtual std::vector<PropertyEditor*> VCF::PropertyEditor::getSubProperties (   )  [pure virtual]

Returns a array of proeprty editors from the current value of this editor. The requirement, of course, is that the variant data that is returned by getValue() is a pdObject. This is not meaningful to call unless PropertEditor::paHasSubProperties is set. See also: PropertEditor::paHasSubProperties Implemented in VCF::AbstractPropertyEditor, VCF::EnumSetPropertyEditor, and VCF::FontPropertyEditor.

virtual VariantData* VCF::PropertyEditor::getValue (   )  [pure virtual]

Returns the value for the property. Note that this value is completely independant of the actual value that may be crurently stored in the source object's property. The assignment of this value to the source's property is up to the tool/IDE/etc that is using this interface. Implemented in VCF::AbstractPropertyEditor.

virtual String VCF::PropertyEditor::getValueAsText (   )  [pure virtual]

Like getValue(), but this returns the value in text format. This value is used for display purposes if the editor doesn't support custom painting. Implemented in VCF::AbstractPropertyEditor, VCF::EnumSetPropertyEditor, and VCF::CursorPropertyEditor.

bool VCF::PropertyEditor::hasSubProperties (   )  [inline]

bool VCF::PropertyEditor::hasValues (   )  [inline]

virtual void VCF::PropertyEditor::internal_setPropertyType (  const String &  type  )  [pure virtual]

Don't call this - this is used strictly by the framework. Implemented in VCF::AbstractPropertyEditor.

bool VCF::PropertyEditor::isCompositeValue (   )  [inline]

bool VCF::PropertyEditor::isReadOnly (   )  [inline]

bool VCF::PropertyEditor::needsCustomPaint (   )  [inline]

bool VCF::PropertyEditor::overridesPropertyDescription (   )  [inline]

bool VCF::PropertyEditor::overridesPropertyName (   )  [inline]

virtual void VCF::PropertyEditor::paintValue (  VariantData *  value, GraphicsContext *  context, const Rect &  bounds, const DrawUIState &  state )  [pure virtual]

Paints a representation of the editor. This will only get called if needsCustomPaint() method returns true. This is for custom painting of the property editor when it is not being edited. Implemented in VCF::AbstractPropertyEditor, VCF::ColorPropertyEditor, and VCF::FontPropertyEditor.

virtual void VCF::PropertyEditor::setProperty (  Property *  property  )  [pure virtual]

This sets the current property instance for the property editor. This should only get called if the property editor has the paEditorRequestsProperty attribute set. Implemented in VCF::AbstractPropertyEditor.

virtual void VCF::PropertyEditor::setRootDesignerComponent (  Component *  rootDesigner  )  [pure virtual]

Sets the root component that is being edited in a form designer. This may or may not be a control. This root component is then used by some property editor's to enumerator choices for assign values to properties. For example a component proeprty editor might try and find all sub components of the root component whose class name matches a certain criteria and disply these as possible choices to assign a value to the property editor. Implemented in VCF::AbstractPropertyEditor.

virtual void VCF::PropertyEditor::setValue (  VariantData *  value  )  [pure virtual]

Set's the value on the property editor. Implemented in VCF::AbstractPropertyEditor.

virtual void VCF::PropertyEditor::setValueAsText (  const String &  textValue  )  [pure virtual]

Like setValue() but allows the value to be a string. Implemented in VCF::AbstractPropertyEditor, VCF::CursorPropertyEditor, and VCF::ColorPropertyEditor.

virtual bool VCF::PropertyEditor::sort (  const String &  strVal1, const String &  strVal2 )  [pure virtual]

only implement this if sortValues() returns true. If this is the case, then return true if strVal1 is greater than strVal2. Implemented in VCF::AbstractPropertyEditor, and VCF::ColorPropertyEditor.

bool VCF::PropertyEditor::sortValues (   )  [inline]

bool VCF::PropertyEditor::usesModalDialogForEditing (   )  [inline]

bool VCF::PropertyEditor::valueNeedsDuplicating (   )  [inline]

---

The documentation for this class was generated from the following file:

• vcf/ApplicationKit/PropertyEditor.h

Comments or Suggestions?    License Information