Skip to main content
.NET Standard 2.0+

PropertyEditor Class

A base class for Property Editors.

Namespace: DevExpress.ExpressApp.Editors

Assembly: DevExpress.ExpressApp.v22.1.dll

Declaration

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

Remarks

Implements base functionality for Property Editors:

PropertyEditor descendants extend its functionality according to a property’s type and the UI platform (Windows Forms, ASP.NET Web 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.

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 module project and decorated with the PropertyEditorAttribute. If your solution does not contain this project, add an editor to an 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:

  1. 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.
  2. Override the GetControlValueCore method. Return the value specified by the control.
  3. 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.

The following code snippets (auto-collected from DevExpress Examples) contain references to the PropertyEditor class.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

See Also