PropertyEditor Class

A base class for Property Editors.

Namespace : DevExpress.ExpressApp.Editors

Assembly : DevExpress.ExpressApp.v25.2.dll

NuGet Package : DevExpress.ExpressApp

Declaration

C#
VB.NET

csharp

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

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

Remarks

Implements base functionality for Property Editors:

The control that represents a Property Editor in a UI can read and write the value of the bound property.
The Property Editor derives information on the property it represents using the PropertyEditor.MemberInfo property.
Members that affect the way the properties are displayed in the Property Editor’s control:

PropertyEditor descendants extend its functionality according to a property’s type and the UI platform (Windows Forms and ASP.NET Core Blazor): Data Types Supported by built-in Editors.

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.

csharp

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

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 platform-specific application project. This Property Editor will be loaded into the Application Model, which means that you will be able to use it in a UI.

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 following article: Access the Settings of a Property Editor in a Detail View.

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.

Implements

IAppearanceEnabled

IAppearanceVisibility

INotifyAppearanceVisibilityChanged

Inheritance

Object ViewItem PropertyEditor BlazorPropertyEditorBase

WinPropertyEditor

DXPropertyEditor