PropertyEditor Class

A base class for Property Editors.

Namespace: DevExpress.ExpressApp.Editors

Assembly: DevExpress.ExpressApp.v21.1.dll

NuGet Package: DevExpress.ExpressApp

Declaration

C#
VB.NET

public abstract class PropertyEditor :
    ViewItem,
    IAppearanceEnabled,
    IAppearanceBase,
    IAppearanceVisibility,
    INotifyAppearanceVisibilityChanged,
    IDisposable

Public MustInherit Class PropertyEditor
    Inherits ViewItem
    Implements IAppearanceEnabled,
               IAppearanceBase,
               IAppearanceVisibility,
               INotifyAppearanceVisibilityChanged,
               IDisposable

Remarks

A Detail View represents an object through a set of Property Editors, each of which is bound to a property of the object. The eXpressApp Framework ships with numerous Property Editor types, for Windows Forms and ASP.NET Web Forms applications, and for different data types. The base class for all Property Editor types is the Property Editor type. It provides basic functionality:

The control that represents a Property Editor in a UI can read and write the value of the bound property.

See the PropertyEditor.ReadValue, PropertyEditor.WriteValue, PropertyEditor.ControlValueChanged, PropertyEditor.ValueStoring, PropertyEditor.ValueStored, PropertyEditor.ValueRead, PropertyEditor.Refresh, PropertyEditor.ControlValue and PropertyEditor.PropertyValue members.
The Property Editor derives information on the property it represents using the PropertyEditor.MemberInfo property.

See also PropertyEditor.PropertyName.
There are properties that are used to display the property via the Property Editor’s control.

See PropertyEditor.IsPassword, PropertyEditor.EditMask, PropertyEditor.DisplayFormat, PropertyEditor.MaxLength, PropertyEditor.AllowEdit, PropertyEditor.IsCaptionVisible, PropertyEditor.ImmediatePostData and PropertyEditor.Caption.

The PropertyEditor class and its descendants can be used to implement custom Property Editors. For details, see the Implement Custom Property Editors topic. When deriving from the PropertyEditor class, the following protected members, not described in the documentation, can be overridden:

Member	Description
OnValueStoring	Called in the PropertyEditor.WriteValue method, before the value specified in a Property Editor’s control is set for the bound property. Raises the PropertyEditor.ValueStoring event. Note that the WriteValue method is not called in the built-in Windows Forms Property Editors, because they support Binding (see System.Windows.Forms.Binding in MSDN). If you implement a Property Editor that supports binding, call the OnValueStoring method, where required.
OnValueStored	Called in the PropertyEditor.WriteValue method, after the value specified in a Property Editor’s control has been set for the bound property. Raises the PropertyEditor.ValueStored event. Note that the WriteValue method is not called in the built-in Windows Forms Property Editors, because they support Binding (see System.Windows.Forms.Binding in MSDN). If you implement a Property Editor that supports binding, call the OnValueStored method, where required.
OnControlValueChanged	Raises the PropertyEditor.ControlValueChanged event. However, the OnControlValueChanged method is not called by default. You should call it in your PropertyEditor class’ descendants, after the control’s value has been changed. For details, refer to the event’s description.
WriteValueCore	Called in the PropertyEditor.WriteValue method. Passes the value from the control to the property (from PropertyEditor.ControlValue to PropertyEditor.PropertyValue). Override this method to implement custom code. Note that the WriteValue method is not called in the built-in Windows Forms Property Editors, because they support binding (see System.Windows.Forms.Binding in MSDN). So, do not override the WriteValueCore method in descendants of these Property Editors.
OnValueRead	Called in the PropertyEditor.ReadValue method, after the value of the bound property is set for the control’s value.
ReadValueCore	Called as a result of calling the PropertyEditor.ReadValue method. Since it is abstract, override it to add the code that passes the value from the property to a control (from PropertyEditor.PropertyValue to PropertyEditor.ControlValue).
CanReadValue	Returns true if the Property Editor’s control is created. Override this method to provide extra conditions to determine whether the property’s value can be read to the control’s value.
OnAllowEditChanged	Called after the Property Editor’s read-only state has been changed (see PropertyEditor.AllowEdit). Raises the PropertyEditor.AllowEditChanged event.
IsMemberSetterRequired	Returns whether the Property Editor requires a property with a set accessor to allow editing. For most Property Editor types, override this method to return true. However, for certain Property Editors, such as Property Editors that deal with reference properties, this method must return false to allow editing of the referenced object’s properties.
GetControlValueCore	This method is abstract. Override it to perform the code that gets the value of the Property Editor’s control.

A constructor of a custom Property Editor must be implemented in the following manner.

C#
VB.NET

public MyPropertyEditor(Type objectType, IModelMemberViewItem model) : base(objectType, model) { }

Public Sub New(ByVal objectType As Type, ByVal model As IModelMemberViewItem)
   MyBase.New(objectType, model)
End Sub

The model parameter is required for the factory that creates all View Items, including Property Editors for a Detail View.

Note

A custom Property Editor should be implemented in a module project and decorated with the PropertyEditorAttribute. In this instance, it will be loaded into the Application Model, which means that you will be able to use it in a UI. Additionally, the module should be UI-specific, because the Property Editor creates a UI-specific control.

Typical implementation of the PropertyEditor class’ descendant comprises the following steps:

Override the CreateControlCore method. Create and return an instance of the required control. Subscribe to the control’s ValueChanged event to call the WriteValue method.
Override the GetControlValueCore method. Return the value specified by the control.
Override the ReadValueCore method. Assign the Property Editor’s PropertyValue to the control’s binding property.

The PropertyEditor class exposes the basic Property Editor functionality. When implementing a custom Property Editor, use one of the derived classes.

If you implement a Property Editor, use the PropertyEditorAttribute.

To access a Property Editor of the View for which a Controller is activated, handle the Controller.Activated and ViewItem.ControlCreated events, as demonstrated in the Access Editor Settings tutorial.

The PropertyEditor class implements the IAppearanceVisibility and IAppearanceEnabled interfaces so that the AppearanceController can change the visibility or enabled state of a property to which a conditional appearance rule is applied.

It is recommended to place your control customization code to the SetupControl method when you create custom property editor.