Skip to main content
.NET 6.0+

DevExpress v24.1 Update — Your Feedback Matters

Our What's New in v24.1 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

DXPropertyEditor Class

A base class for Property Editors that use Developer Express Windows Forms controls.

Namespace: DevExpress.ExpressApp.Win.Editors

Assembly: DevExpress.ExpressApp.Win.v24.1.dll

NuGet Package: DevExpress.ExpressApp.Win

#Declaration

public abstract class DXPropertyEditor :
    WinPropertyEditor,
    IInplaceEditSupport,
    IAppearanceFormat,
    IAppearanceBase

#Remarks

Inherit from this class to implement a custom Property Editor using a control from the XtraEditors library. All the controls from this library support in-place editing. It is a mechanism that allows you to embed an editor into container controls. To support in-place editing, these editors have a Repository Item. This item stores properties and event handlers used to set up the editor. Repository Items can be created as stand-alone objects to embed editors of particular types into container controls. For details, see Repositories and Repository Items. The XAF utilizes this feature to provide the in-place editing functionality in the GridListEditor (the List Editor that uses XtraGrid control).

The simplest implementation of the DXPropertyEditor class’ descendant requires a single step:

  1. Override the CreateControlCore method. This method returns the Property Editor’s control (see How to: Implement a Property Editor Based on a Custom Control (WinForms)). The following code snippet illustrates this:
using System.Drawing;
using DevExpress.ExpressApp.Model;
using DevExpress.ExpressApp.Editors;
using DevExpress.ExpressApp.Win.Editors;
//...
[PropertyEditor(typeof(String))]
public class MyStringPropertyEditor : DXPropertyEditor {
    public MyStringPropertyEditor(Type objectType, IModelMemberViewItem model)
       : base(objectType, model) { }
    protected override object CreateControlCore() {
        StringEdit control = new StringEdit();            
        control.Properties.Appearance.ForeColor = Color.Coral;
        return control;
    }
}

The following image demonstrates a business object’s property which is displayed via the implemented Property Editor in a Detail View:

DXPropertyEditor1

In a List View, the column which displays the business object property is represented by a simple label, since the Repository Item is not created, by default:

DXPropertyEditor2

The implemented Property Editor does not support in-place editing in the List Views that are represented by the GridListEditor List Editor. To implement the in-place editing support, two additional steps should be taken:

  1. Override the CreateRepositoryItem method. It is called by the GridListEditor List Editor to create a repository item for a column.

  2. Override the SetupRepositoryItem method. In this method, perform the customization of the control’s settings, if needed. This method is called when creating an in-place editor for the GridListEditor’s column. In addition, this method is called after a Property Editor has been created in a Detail View. So, the implemented customization will affect the controls created both in the Detail View and List View. It is necessary to call the base SetupRepositoryItem method in the overridden method to perform common control initialization. The following code snippet illustrates this:

using DevExpress.XtraEditors.Repository;
//...
[PropertyEditor(typeof(String))]
public class MyStringPropertyEditor : DXPropertyEditor {
    public MyStringPropertyEditor(Type objectType, IModelMemberViewItem model)
        : base(objectType, model) { }
    protected override object CreateControlCore() {
        StringEdit control = new StringEdit();
        control.Properties.Appearance.ForeColor = Color.Coral;
        return control;
    }
    protected override RepositoryItem CreateRepositoryItem() {
        return new RepositoryItemStringEdit();
    }
    protected override void SetupRepositoryItem(RepositoryItem item) {
        base.SetupRepositoryItem(item);
        item.Appearance.ForeColor = Color.Coral;            
    }
}

The following image demonstrates a business object’s property, displayed via the implemented Property Editor in a Detail View:

DXPropertyEditor1

In a List View, the column which displays the business object property uses the Property Editor’s Repository Item. So, in edit mode, the property is displayed in a List View using the same options as in the Detail View:

DXPropertyEditor3

 

Compared to the WinPropertyEditor class, the DXPropertyEditor class introduces additional members:

Member Description
DXPropertyEditor.Control Returns a DevExpress.XtraEditors.BaseEdit class descendant that represents the Property Editor’s control.
DXPropertyEditor.CustomSetupRepositoryItem Occurs after the creation of a Property Editor’s control.
DXPropertyEditor.RepositoryItemsTypesWithMandatoryButtons Used to determine the visibility state of the Property Editor control’s buttons.

When implementing a DXPropertyEditor class descendant, the following protected members, which are not described in the documentation, can be overridden:

Member Description
CreateRepositoryItem Used to support the IInplaceEditSupport interface. This method is called when a column is created in an editable XtraGrid. The created repository item is assigned to the column’s ColumnEdit property. This behavior allows the display of a business property in the same manner in a Detail and List View.
SetRepositoryItemReadOnly Called in the SetupRepositoryItem and OnAllowEditChanged methods. Override this method to perform specific actions when the PropertyEditor.AllowEdit mode is changed.
SetupRepositoryItem Called in the OnControlCreated method. Override this method to perform additional repository item initialization.
OnCustomSetupRepositoryItem Called in the SetupRepositoryItem method. Raises the DXPropertyEditor.CustomSetupRepositoryItem event.

The DXPropertyEditor class implements the IAppearanceFormat interface, so that the AppearanceController can change the appearance format of a property to which a conditional appearance rule is applied.

To see an example of a DXPropertyEditor class descendant implementation, refer to the How to: Implement a Property Editor Using a DevExpress WinForms Control topic.

Tip

Set the CanUpdateControlEnabled protected property to true in the constructor of your custom Property Editor if it is required to update the Control.Enabled property value (e.g., when the underlying control is created or the PropertyEditor.AllowEdit property is changed).

See Also