Implement a Property Editor Based on a Custom Control (WinForms)

• Jun 19, 2024
• 4 minutes to read

This topic explains how to implement a Property Editor for WinForms applications. For demo purposes, the integer Property Editor based on the NumericUpDown control is implemented in this example.

Note

• You can see the code implemented here in the FeatureCenter Demo, installed with XAF. This demo is located in the %PUBLIC%\Documents\DevExpress Demos 24.1\Components\XAF\FeatureCenter.NETFramework.XPO folder, by default.
• If you intend to use a DevExpress WinForms control that is not integrated to XAF by default, refer to the How to: Implement a Property Editor Using a DevExpress WinForms Control topic.

Follow these steps to implement a WinForms Property Editor.

1. Inherit the PropertyEditor or WinPropertyEditor class in the WinForms module project (MySolution.Module.Win). If your solution does not contain this project, add this editor to the WinForms application project (MySolution.Win). Note that your editor should be public.
2. Apply the PropertyEditorAttribute to specify the data type for which the Property Editor will be used (Int32 in this example). If you pass true to the PropertyEditor attribute’s last parameter, the Property Editor will be used for all integer properties in any business class.
3. Override the CreateControlCore method. In this method, instantiate, initialize and return the control instance (the NumericUpDown control in this example).
4. Determine which event of the control occurs when the editing value is changed by a user (e.g., the NumericUpDown.ValueChanged event). Refer to the control’s documentation to find the appropriate event. Subscribe to this event and call the OnControlValueChanged method (which internally raises the PropertyEditor.ControlValueChanged event) from the event handler.
5. Override the Dispose method and unsubscribe the event handled in the previous step.
6. Optionally, support the IInplaceEditSupport interface and implement the IInplaceEditSupport.CreateRepositoryItem method. This step is only required if you are going to make the column editable in the editable List View.

The following code demonstrates CustomIntegerEditor class implementation based on the steps above.

C#

using System.Windows.Forms;
using DevExpress.ExpressApp.Model;
using DevExpress.ExpressApp.Editors;
using DevExpress.ExpressApp.Win.Editors;
using DevExpress.XtraEditors.Repository;
// ...
[PropertyEditor(typeof(Int32), false)]
public class CustomIntegerEditor : PropertyEditor, IInplaceEditSupport {
    private NumericUpDown control = null;
    protected override void ReadValueCore() {
        if(control != null) {
            if(CurrentObject != null) {
                control.ReadOnly = false;
                control.Value = (int)PropertyValue;
            }
            else {
                control.ReadOnly = true;
                control.Value = 0;
            }
        }
    }
    private void control_ValueChanged(object sender, EventArgs e) {
        if(!IsValueReading) {
            OnControlValueChanged();
            WriteValueCore();
        }
    }
    protected override object CreateControlCore() {
        control = new NumericUpDown();
        control.Minimum = 0;
        control.Maximum = 5;
        control.ValueChanged += control_ValueChanged;
        return control;
    }
    protected override void OnControlCreated() {
        base.OnControlCreated();
        ReadValue();
    }
    public CustomIntegerEditor(Type objectType, IModelMemberViewItem info)
        : base(objectType, info) {
    }
    protected override void Dispose(bool disposing) {
        if(control != null) {
            control.ValueChanged -= control_ValueChanged;
            control = null;
        }
        base.Dispose(disposing);
    }
    RepositoryItem IInplaceEditSupport.CreateRepositoryItem() {
        RepositoryItemSpinEdit item = new RepositoryItemSpinEdit();
        item.MinValue = 0;
        item.MaxValue = 5;
        item.Mask.EditMask = "0";
        return item;
    }
    protected override object GetControlValueCore() {
        if(control != null) {
            return (int)control.Value;
        }
        return null;
    }
}

VB.NET

Imports Microsoft.VisualBasic

<PropertyEditor(GetType(Int32), False)> _
Public Class CustomIntegerEditor
    Inherits PropertyEditor
    Implements IInplaceEditSupport

    Private control As NumericUpDown = Nothing
    Protected Overrides Sub ReadValueCore()
        If control IsNot Nothing Then
            If CurrentObject IsNot Nothing Then
                control.ReadOnly = False
                control.Value = CInt(Fix(PropertyValue))
            Else
                control.ReadOnly = True
                control.Value = 0
            End If
        End If
    End Sub
    Private Sub control_ValueChanged(ByVal sender As Object, ByVal e As EventArgs)
        If Not IsValueReading Then
            OnControlValueChanged()
            WriteValueCore()
        End If
    End Sub
    Protected Overrides Function CreateControlCore() As Object
        control = New NumericUpDown()
        control.Minimum = 0
        control.Maximum = 5
        AddHandler control.ValueChanged, AddressOf control_ValueChanged
        Return control
    End Function
    Protected Overrides Sub OnControlCreated()
        MyBase.OnControlCreated()
        ReadValue()
    End Sub
    Public Sub New(ByVal objectType As Type, ByVal info As IModelMemberViewItem)
        MyBase.New(objectType, info)
    End Sub
    Protected Overrides Sub Dispose(ByVal disposing As Boolean)
        If control IsNot Nothing Then
            RemoveHandler control.ValueChanged, AddressOf control_ValueChanged
            control = Nothing
        End If
        MyBase.Dispose(disposing)
    End Sub
    Private Function IInplaceEditSupport_CreateRepositoryItem() As RepositoryItem Implements IInplaceEditSupport.CreateRepositoryItem
        Dim item As New RepositoryItemSpinEdit()
        item.MinValue = 0
        item.MaxValue = 5
        item.Mask.EditMask = "0"
        Return item
    End Function
    Protected Overrides Function GetControlValueCore() As Object
        If control IsNot Nothing Then
            Return CInt(Fix(control.Value))
        End If
        Return Nothing
    End Function
End Class

You can also implement IComplexViewItem in this Property Editor. This interface allows the editor to access the XafApplication instance and use an Object Space to load data from an application database.

To display a particular property using the CustomIntegerEditor Property Editor, customize the Application Model. Invoke the Model Editor for the WinForms application project and navigate to the required BOModel| Class| OwnMembers| Member node. Set the node’s IModelCommonMemberViewItem.PropertyEditorType property to CustomIntegerEditor. After this, the property specified by the Member node will be displayed by the CustomIntegerEditor in all Views. To use a CustomIntegerEditor Property Editor in a specific Detail View only, use the PropertyEditorType property of the Views | <DetailView> | Items | <PropertyEditor> node instead.

Note

You may need to implement the IAppearanceFormat interface and manually apply the IAppearanceFormat.BackColor, IAppearanceFormat.FontColor and IAppearanceFormat.FontStyle settings of the Conditional Appearance Module to the created control.