Log In
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Collapse]eXpressApp Framework
 [Expand]Getting Started
 [Expand]Design-Time Features
 [Collapse]Task-Based Help
  [Expand]Business Model Design
  [Expand]Application Model
  [Collapse]List Editors
    How to: Configure Bands in a Grid List Editor (WinForms and ASP.NET)
    How to: Edit a Reference Property in the Batch Edit Mode
    How to: Implement a Custom WinForms List Editor
    How to: Implement an ASP.NET Web List Editor Using a Custom Control
    How to: Support a Context Menu for a Custom WinForms List Editor
  [Expand]Property Editors
  [Expand]Scheduler and Notifications
  [Expand]Miscellaneous UI Customizations
  Frequently Asked Questions (FAQ)
 [Expand]API Reference
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
This documentation page describes implementations made in our v17.2 release cycle. To learn about functionality shipping with v18.1, navigate to our updated help file experience at docs.devexpress.com. Learn More

How to: Implement a Custom WinForms List Editor

The eXpressApp Framework is shipped with a number of built-in List Editors. However, in certain scenarios you may need to implement a custom List Editor, to display object collections in a particular way. This topic demonstrates how to implement a custom WinCustomListEditor List Editor that uses a control from the .NET Framework library. This List Editor is designed to display objects, implementing a custom IPictureItem interface as a list of images, one for each object. It can be used, for instance, to display DVD covers.

The following image demonstrates the implemented List Editor in an Album List View:


You can see the code implemented here in the FeatureCenter Demo installed with XAF. This demo is located in the %PUBLIC%\Documents\DevExpress Demos 18.1\Components\eXpressApp Framework\FeatureCenter folder, by default.


To learn how to support a context menu for the WinCustomListEditor, refer to the How to: Support a Context Menu for a Custom WinForms List Editor topic.

When implementing a custom List Editor that works with specific data, you can design it for a particular class. However, in this example, an interface will be introduced containing the properties required by the List Editor. Then, the List Editor will be designed to display objects implementing the interface. This approach allows you to simultaneously use that same List Editor for different classes. List Views displayed using the WinCustomListEditor will have two columns: Image and Text. The special interface has an additional ID property that represents a unique object identifier.

Start implementing the List Editor by inheriting its class from the ListEditor class, and implement basic functionality by overriding the following members. Note that your editor should be public.

  • CreateControlsCore method, that instantiates the List Editor's control. Override it to create and configure the control.
  • AssignDataSourceToControl method, that assigns the List Editor's data source to its control. Override it to support object change notification, when the data source implements the IBindingList interface.
  • ListEditor.Refresh method, that refreshes data in the List Editor's control. Override it to make the control reload all objects from its data source.
  • ListEditor.Dispose method, that disposes of a manually allocated controlDataSource property .
  • To specify that List Views displaying IPictureItem, objects should use the WinCustomListEditor, decorate the List Editor class with the ListEditorAttribute.

The demonstrated List Editor can display a collection of objects implementing the IPictureItem interface. However, it does not support items selection, because it cannot recognize what item is currently selected. To support selection, the following members must be modified:

  • In the CreateControlsCore method, subscribe to the control's SelectedIndexChanged and ItemSelectionChanged events. In the SelectedIndexChanged event handler, call the OnSelectionChanged method. In the ItemSelectionChanged event handler, call the OnSelectionChanged and OnFocusedObjectChanged methods.
  • Override the ListEditor.SelectionType property. Since the ListView control supports both single and multiple selections, this property must return SelectionType.Full.
  • Override the ListEditor.GetSelectedObjects method. This method must return a list of the selected objects.

In addition to selection, a List Editor should be able to invoke a Detail View for the focused object when an end-user presses ENTER, or double-clicks the object. For this purpose, modify the following members:

  • In the CreateControlsCore method, subscribe to the control's MouseDoubleClick and KeyDown events. In the event handlers, call the OnProcessSelectedItem method.
  • Override the ListEditor.FocusedObject property, to get and set the focused object. To do this, we implement an additional FindByTag helper method.
  • Modify the ListEditor.Refresh method, to make the List Editor retain focus when refreshing data in the control.

If you need to store the editor settings in the Application Model, implement the ListEditor.SaveModel method. Otherwise, leave this method empty

This code snippet demonstrates the steps above.

Expanded See Also

Is this topic helpful?​​​​​​​