DataLayoutControl.FieldRetrieving Event

Fires before a layout item with an embedded editor is generated and thus, prior to the editor’s data binding. It allows you to customize the type of editor to be generated, modify editor binding settings and hide certain editors.

Namespace: DevExpress.XtraDataLayout

Assembly: DevExpress.XtraLayout.v24.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

C#

[DXCategory("Data")]
public event EventHandler<FieldRetrievingEventArgs> FieldRetrieving

VB.NET

<DXCategory("Data")>
Public Event FieldRetrieving As EventHandler(Of FieldRetrievingEventArgs)

Event Data

The FieldRetrieving event's data class is FieldRetrievingEventArgs. The following properties provide information specific to this event:

Property	Description
DataSourceNullValue	Gets or sets the value used to initialize the Binding.DataSourceNullValue property for the auto-generated editor.
DataSourceUpdateMode	Gets or sets the value used to initialize the Binding.DataSourceUpdateMode property for the auto-generated editor.
DataType	Gets the bound field’s data type.
EditorType	Gets or sets the type of the editor to be created.
FieldName	Gets the data source field to which the editor is bound.
Handled	Gets or sets whether the event is handled and the customized event parameters must be applied after the event handler is completed.
PropertyName	Gets or sets the name of the editor’s property to which the data source field is bound.
Visible	Gets or sets the layout item’s (editor’s) visibility.

Remarks

The FieldRetrieving event fires before layout items and editors are created at runtime in the following cases:

• When the DataLayoutControl.RetrieveFields method is called.
• When automatic layout generation is invoked at runtime. This feature is invoked each time the DataLayoutControl.DataSource property is set to a new value, provided that the DataLayoutControl.AutoRetrieveFields property is enabled.

The FieldRetrieving event fires for each public field in the underlying data source. Handle this event to customize the type of editor to be generated, modify editor binding settings and to hide certain editors (hidden layout items will be accessible at runtime from the Customization Form).

For changes made in the FieldRetrieving event to be in effect, set the event’s Handled parameter to true.

Example

This example shows how to handle the DataLayoutControl.FieldRetrieving and DataLayoutControl.FieldRetrieved events to customize binding information, and settings of auto-generated layout items and embedded editors.

In the example, the DataLayoutControl.FieldRetrieving event is handled to assign a ComboBoxEdit control for editing the ZipCode field. Items are added to the ComboBoxEdit after the editor is created (in the DataLayoutControl.FieldRetrieved event).

In the DataLayoutControl.FieldRetrieving event handler, the DataSourceUpdateMode parameter is set to OnPropertyChanged. For instance, this forces the “Full Name” field to be updated immediately on typing text in the “First Name” and “Last Name” fields.

The following image shows the result:

Form1.cs

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
using DevExpress.XtraEditors;
using DevExpress.XtraEditors.Controls;
using DevExpress.XtraEditors.Repository;

namespace DataLayoutControl_FieldRetrieve {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e) {
            BindingSource personBindingSource = new BindingSource();
            personBindingSource.DataSource = typeof(Person);
            personBindingSource.AddNew();

            dataLayoutControl1.FieldRetrieving += dataLayoutControl1_FieldRetrieving;
            dataLayoutControl1.FieldRetrieved += dataLayoutControl1_FieldRetrieved;
            dataLayoutControl1.DataSource = personBindingSource;

            dataLayoutControl1.RetrieveFields();
        }

        void dataLayoutControl1_FieldRetrieving(object sender, DevExpress.XtraDataLayout.FieldRetrievingEventArgs e) {
            if (e.FieldName == "ZipCode") 
                e.EditorType = typeof(ComboBoxEdit);
            e.DataSourceUpdateMode = DataSourceUpdateMode.OnPropertyChanged;
            e.Handled = true;
        }

        void dataLayoutControl1_FieldRetrieved(object sender, DevExpress.XtraDataLayout.FieldRetrievedEventArgs e) {
            if (e.FieldName == "FirstName" || e.FieldName == "LastName") {
                e.Control.BackColor = Color.GreenYellow;
            }
            if (e.FieldName == "ZipCode") {
                RepositoryItemComboBox riComboBox = e.RepositoryItem as RepositoryItemComboBox;
                riComboBox.TextEditStyle = TextEditStyles.DisableTextEditor;
                riComboBox.Items.Add("20505");
                riComboBox.Items.Add("20506");
                riComboBox.Items.Add("20507");
                riComboBox.Items.Add("20508");
                riComboBox.Items.Add("20509");
            }
        }
    }

    public class Person {
        [Display(GroupName = "<GroupName->")]
        public string FirstName { get; set; }
        [Display(GroupName = "<GroupName->")]
        public string LastName { get; set; }
        public string FullName { get { return FirstName + " " + LastName; } }
        [Display(GroupName = "<GroupPhone->")]
        public string Phone { get; set; }
        [Display(GroupName = "<GroupPhone->")]
        public string Email { get; set; }
        [Display(GroupName = "Address")]
        public string City { get; set; }
        [Display(GroupName = "Address")]
        public string ZipCode { get; set; }
    }


}

Form1.vb

Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.ComponentModel.DataAnnotations
Imports System.Data
Imports System.Drawing
Imports System.Linq
Imports System.Text
Imports System.Threading.Tasks
Imports System.Windows.Forms
Imports DevExpress.XtraEditors
Imports DevExpress.XtraEditors.Controls
Imports DevExpress.XtraEditors.Repository

Namespace DataLayoutControl_FieldRetrieve
    Partial Public Class Form1
        Inherits Form

        Public Sub New()
            InitializeComponent()
        End Sub

        Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load
            Dim personBindingSource As New BindingSource()
            personBindingSource.DataSource = GetType(Person)
            personBindingSource.AddNew()

            AddHandler dataLayoutControl1.FieldRetrieving, AddressOf dataLayoutControl1_FieldRetrieving
            AddHandler dataLayoutControl1.FieldRetrieved, AddressOf dataLayoutControl1_FieldRetrieved
            dataLayoutControl1.DataSource = personBindingSource

            dataLayoutControl1.RetrieveFields()
        End Sub

        Private Sub dataLayoutControl1_FieldRetrieving(ByVal sender As Object, ByVal e As DevExpress.XtraDataLayout.FieldRetrievingEventArgs)
            If e.FieldName = "ZipCode" Then
                e.EditorType = GetType(ComboBoxEdit)
            End If
            e.DataSourceUpdateMode = DataSourceUpdateMode.OnPropertyChanged
            e.Handled = True
        End Sub

        Private Sub dataLayoutControl1_FieldRetrieved(ByVal sender As Object, ByVal e As DevExpress.XtraDataLayout.FieldRetrievedEventArgs)
            If e.FieldName = "FirstName" OrElse e.FieldName = "LastName" Then
                e.Control.BackColor = Color.GreenYellow
            End If
            If e.FieldName = "ZipCode" Then
                Dim riComboBox As RepositoryItemComboBox = TryCast(e.RepositoryItem, RepositoryItemComboBox)
                riComboBox.TextEditStyle = TextEditStyles.DisableTextEditor
                riComboBox.Items.Add("20505")
                riComboBox.Items.Add("20506")
                riComboBox.Items.Add("20507")
                riComboBox.Items.Add("20508")
                riComboBox.Items.Add("20509")
            End If
        End Sub
    End Class

    Public Class Person
        <Display(GroupName := "<GroupName->")> _
        Public Property FirstName() As String
        <Display(GroupName := "<GroupName->")> _
        Public Property LastName() As String
        Public ReadOnly Property FullName() As String
            Get
                Return FirstName & " " & LastName
            End Get
        End Property
        <Display(GroupName := "<GroupPhone->")> _
        Public Property Phone() As String
        <Display(GroupName := "<GroupPhone->")> _
        Public Property Email() As String
        <Display(GroupName := "Address")> _
        Public Property City() As String
        <Display(GroupName := "Address")> _
        Public Property ZipCode() As String
    End Class


End Namespace

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the FieldRetrieving event.

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.

C#

winforms-dashboard-custom-properties/CS/WinForms-Dashboard-Custom-Properties/Modules/ConstantLineUserValueModule.cs#L126

dataLayoutControl.DataSource = source;
dataLayoutControl.FieldRetrieving += (s, e) => {
    if(e.FieldName == nameof(ConstantLineModuleData.PaneName)) {

VB.NET

winforms-dashboard-custom-properties/VB/WinForms-Dashboard-Custom-Properties/Modules/ConstantLineUserValueModule.vb#L134

dataLayoutControl.DataSource = source
AddHandler dataLayoutControl.FieldRetrieving, Sub(s, e)
    If e.FieldName = NameOf(ConstantLineModuleData.PaneName) Then