ContextQMD
Back to Devexpress

Customize Properties

wpf-401044-controls-and-libraries-property-grid-property-definitions-customize-properties.md

latest16.1 KB
Original Source

Customize Properties

  • Sep 01, 2023
  • 6 minutes to read

This topic shows how to customize cell editors, headers, and description in the Property Grid.

Cell Editors

The PropertyGridControl creates cell editors based on property types.

csharp
public class Item {
    public DateTime BirthDate { get; set; }
}

Use the following properties to display other content in property grid cells or additionally configure cell editors:

|

Member

|

Task

| | --- | --- | |

EditSettings

CellTemplate

|

Assign and configure a cell editor

| |

ContentTemplate

|

Display a different property value

Display multiple property values in a single row

|

EditSettings

These approaches are compatible with all BaseEditSettings class descendants.

Approach 1: Set the EditSettings property

Create a property definition and set the EditSettings property for it.

xaml
xmlns:sys="clr-namespace:System;assembly=mscorlib"

<dxprg:PropertyDefinition Type="sys:DateTime">
    <dxprg:PropertyDefinition.EditSettings>
        <dxe:DateEditSettings DisplayFormat="MMM-dd-yyyy" />
    </dxprg:PropertyDefinition.EditSettings>
</dxprg:PropertyDefinition>

Approach 2: Use attributes or the DevExpress Fluent API

Create a template with a BaseEditSettings class descendant and use DevExpress.Mvvm.DataAnnotations.DefaultEditorAttribute , DevExpress.Mvvm.DataAnnotations.PropertyGridEditorAttribute , or the DevExpress Fluent API to specify this template key.

cs
static MainWindow() {
    MetadataLocator.Default = MetadataLocator.Create().AddMetadata<ItemMetadata>();
}
public class Item {
    public DateTime Date { get; set; }
}
public class ItemMetadata : IMetadataProvider<Item> {
    public void BuildMetadata(MetadataBuilder<Item> builder) {
        builder.Property(x => x.Date).PropertyGridEditor("DateEditor");
    }
}
xaml
<Window.Resources>
    <DataTemplate x:Key="DateEditor">
        <dxe:DateEditSettings Mask="dd-MM-yyyy" MaskUseAsDisplayFormat="True" />
    </DataTemplate>
</Window.Resources>

CellTemplate

The table below shows the key differences between the EditSettings and CellTemplate properties.

| |

EditSettings

|

CellTemplate

| | --- | --- | --- | |

Performance

|

Normal

|

Lower

| |

Display custom editors

|

|

| |

Editor settings

|

Editors in all properties associated with the current property definition have similar settings

|

Editors may have different settings, for example, depending on the current property value

| |

Priority

|

Standard

|

Higher

|

To gain the best user experience, use a DevExpress editor and set the editor’s Name to ‘ PART_Editor ‘. For example:

xaml
<DataTemplate>
    <dxe:DateEdit Name="PART_Editor" DisplayFormatString="MMM-dd-yyyy" />
</DataTemplate>

Approach 1: Set the CellTemplate property

Create a property definition and set the CellTemplate property for it.

xaml
xmlns:sys="clr-namespace:System;assembly=mscorlib"

<dxprg:PropertyDefinition Type="sys:DateTime">
    <dxprg:PropertyDefinition.CellTemplate>
        <DataTemplate>
            <dxe:DateEdit Name="PART_Editor" DisplayFormatString="MMM-dd-yyyy" />
        </DataTemplate>
    </dxprg:PropertyDefinition.CellTemplate>
</dxprg:PropertyDefinition>

Approach 2: Use attributes or the DevExpress Fluent API

Create a template with a DevExpress editor whose name is set to PART_Editor and use DevExpress.Mvvm.DataAnnotations.DefaultEditorAttribute , DevExpress.Mvvm.DataAnnotations.PropertyGridEditorAttribute , or the DevExpress Fluent API to specify this template key.

csharp
static MainWindow() {
    MetadataLocator.Default = MetadataLocator.Create().AddMetadata<ItemMetadata>();
}
public class Item {
    public DateTime Date { get; set; }
}
public class ItemMetadata : IMetadataProvider<Item> {
    public void BuildMetadata(MetadataBuilder<Item> builder) {
        builder.Property(x => x.Date).PropertyGridEditor("DateEditor");
    }
}
xaml
<Window.Resources>
    <DataTemplate x:Key="DateEditor">
        <dxe:DateEdit Mask="dd-MM-yyyy" MaskUseAsDisplayFormat="True" />
    </DataTemplate>
</Window.Resources>

ContentTemplate

PropertyDefinitionBase.ContentTemplate should contain CellEditorPresenter controls with the Path property set. Set PathMode to manage where CellEditorPresenter should look for a property specified in Path. The table below describes the available options.

|

Value

|

Description

| | --- | --- | |

Relative (default)

|

The CellEditorPresenter.Path points to a property of an object associated with the parent PropertyDefinition.

| |

Absolute

|

The CellEditorPresenter.Path points to a property of PropertyGridControl.SelectedObject.

|

Example 1: How to display multiple properties in a single row

This example demonstrates a custom template that displays multiple properties in a single PropertyGridControl cell.

Both the absolute and relative paths are specified for the cell editor presenter objects.

csharp
using System;

namespace DXSample {
    public class CategoryAttributesViewModel {
        public virtual Person Person { get; protected set; }
        public CategoryAttributesViewModel() {
            Person = new Person {
                FirstName = "Anita",
                LastName = "Benson",
                Address = new Address {
                    AddressLine1 = "9602 South Main",
                    AddressLine2 = "Seattle, 77025, USA",
                },
                Phone = "7138638137",
            };
        }
    }
    public class Person {
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public Address Address { get; set; }
        public string Phone { get; set; }
    }
    public class Address {
        public string AddressLine1 { get; set; }
        public string AddressLine2 { get; set; }
    }
}
xaml
<Window x:Class="DXSample.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"
        xmlns:dxe="http://schemas.devexpress.com/winfx/2008/xaml/editors"
        xmlns:dxprg="http://schemas.devexpress.com/winfx/2008/xaml/propertygrid"  
        xmlns:dxmvvm="http://schemas.devexpress.com/winfx/2008/xaml/mvvm"
        xmlns:local="clr-namespace:DXSample"
        DataContext="{dxmvvm:ViewModelSource Type=local:CategoryAttributesViewModel}"
        dx:ThemeManager.ThemeName="Office2013"
        Title="MainWindow" Height="350" Width="525">
    <Grid>
        <dxprg:PropertyGridControl SelectedObject="{Binding Person}" ExpandCategoriesWhenSelectedObjectChanged="True" ShowProperties="WithPropertyDefinitions">
            <dxprg:PropertyGridControl.PropertyDefinitions>
                <dxprg:PropertyDefinition Path="FirstName"/>
                <dxprg:PropertyDefinition Path="LastName"/>
                <dxprg:PropertyDefinition Path="Address" Header="Contact">
                    <dxprg:PropertyDefinition.ContentTemplate>
                        <DataTemplate>
                            <StackPanel>
                                <dxprg:CellEditorPresenter Path="AddressLine1"/>
                                <dxprg:CellEditorPresenter Path="AddressLine2"/>
                                <dxprg:CellEditorPresenter Path="Phone" PathMode="Absolute"/>
                            </StackPanel>
                        </DataTemplate>
                    </dxprg:PropertyDefinition.ContentTemplate>
                </dxprg:PropertyDefinition>
            </dxprg:PropertyGridControl.PropertyDefinitions>
        </dxprg:PropertyGridControl>
    </Grid>
</Window>
vb
Imports System

Namespace DXSample
    Public Class CategoryAttributesViewModel
        Private privatePerson As Person
        Public Overridable Property Person() As Person
            Get
                Return privatePerson
            End Get
            Protected Set(ByVal value As Person)
                privatePerson = value
            End Set
        End Property
        Public Sub New()
            Person = New Person With {.FirstName = "Anita", .LastName = "Benson", .Address = New Address With {.AddressLine1 = "9602 South Main", .AddressLine2 = "Seattle, 77025, USA"}, .Phone = "7138638137"}
        End Sub
    End Class
    Public Class Person
        Public Property FirstName() As String
        Public Property LastName() As String
        Public Property Address() As Address
        Public Property Phone() As String
    End Class
    Public Class Address
        Public Property AddressLine1() As String
        Public Property AddressLine2() As String
    End Class
End Namespace

Example 2: How to specify a custom editor for CellEditorPresenter

This example demonstrates how to specify a custom editor for CellEditorPresenter associated with the Phone property. For this, create a separate PropertyDefinition for the Phone property and set EditSettings / CellTemplate for it.

xaml
<dxprg:PropertyGridControl SelectedObject="{Binding Customer}" ShowProperties="WithPropertyDefinitions">
    <dxprg:PropertyDefinition Path="Name" />
    <dxprg:PropertyDefinition Path="Phone">
        <dxprg:PropertyDefinition.ContentTemplate>
            <DataTemplate>
                <StackPanel>
                    <dxprg:CellEditorPresenter Path="Email" PathMode="Absolute" />
                    <dxprg:CellEditorPresenter Path="Phone" PathMode="Absolute" />
                </StackPanel>
            </DataTemplate>
        </dxprg:PropertyDefinition.ContentTemplate>
    </dxprg:PropertyDefinition>
    <dxprg:PropertyDefinition Path="Email" Visibility="Collapsed">
        <dxprg:PropertyDefinition.EditSettings>
            <dxe:HyperlinkEditSettings AllowAutoNavigate="True" NavigationUrlFormat="mailto:{0}" />
        </dxprg:PropertyDefinition.EditSettings>
    </dxprg:PropertyDefinition>    
</dxprg:PropertyGridControl>
csharp
public class Customer {
    public String Name { get; set; }
    public String Email { get; set; }
    public String Phone { get; set; }
}

Process User Actions

The PropertyGridControl includes the following events that allow you to specify how users can interact with editors:

EventDescription
GetIsEditorActivationActionAllows you to specify whether an action (key down, text input, or mouse left button click) activates the focused editor.
ProcessEditorActivationActionAllows you to prohibit the focused editor to process an activation action.
GetActiveEditorNeedsKeyAllows you to specify whether an active editor responds to keys that a user presses.

Immediate Posting

The PropertyGridControl posts new values to its data source when a user presses Enter or focuses another row. Set the PropertyDefinition.PostOnEditValueChanged property to true to post data each time a user modifies a value.

Headers

The Header is the leftmost element within a PropertyGrid row.

Use the following properties to affect the header.

|

Member

|

Characteristics

| | --- | --- | |

PropertyDefinitionBase.Header

|

Content

| |

PropertyDefinitionBase.HeaderShowMode

|

Position

| |

PropertyDefinitionBase.HeaderTemplate

|

Template

|

For example, property definitions below remove headers ([0], [1], and so on) from collection members and make the Name property header red.

xaml
<!-- xmlns:collections="clr-namespace:System.Collections;assembly=mscorlib" -->
<dxprg:PropertyDefinition Type="{x:Type collections:IList}" TypeMatchMode="Extended">
    <dxprg:PropertyDefinition Header="" />
</dxprg:PropertyDefinition>
<dxprg:PropertyDefinition Header="Name">
    <dxprg:PropertyDefinition.HeaderTemplate>
        <DataTemplate>
            <TextBlock Foreground="Red" Text="{Binding Header}" />
        </DataTemplate>
    </dxprg:PropertyDefinition.HeaderTemplate>
</dxprg:PropertyDefinition>

Description

The Description appears in a tooltip or a panel at the bottom of the Property Grid.

Use the following properties to change the description behavior or appearance.

|

Member

|

Characteristics

| | --- | --- | |

PropertyDefinitionBase.Description

|

Content

| |

PropertyGridControl.ShowDescriptionIn

|

Position

| |

PropertyGridControl.DescriptionTemplate

PropertyDefinitionBase.DescriptionTemplate

|

Template

|

For example, the following code makes the description text red.

xaml
<dxprg:PropertyDefinition Description="Local number" Header="Home number" Path="HomeNumber">
    <dxprg:PropertyDefinition.DescriptionTemplate>
        <DataTemplate>
            <TextBlock Foreground="Red" Text="{Binding}" />
        </DataTemplate>
    </dxprg:PropertyDefinition.DescriptionTemplate>
</dxprg:PropertyDefinition>