[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications, and Dialogs
  [Collapse]Editors and Simple Controls
   [Expand]Simple Editors
   [Expand]Lookup Editors
   [Collapse]Token Edit Control
     How to: Use complex objects as token values
     TokenEdit with Custom Drop-Down Control
   [Expand]Breadcrumb Edit Control
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
    Templated ListBox Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Gantt Control
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[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
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

TokenEdit with Custom Drop-Down Control

The Token Edit Control displays its currently available tokens within a drop-down based on a simple pop-up menu. There can be scenarios when a simple pop-up is insufficient. In this case, you can manually create your own drop-down control and assign it to the TokenEdit.

This example will demonstrate you how to add a GalleryControl as a TokenEdit's drop-down.

  1. Create a new Windows Forms solution and drop a TokenEdit onto the form.
  2. Right-click your solution in the Visual Studio's Solution Explorer and add a new user control as shown below.

    This control will serve as a drop-down for the TokenEdit control.

  3. Drop a GalleryControl onto this user control.
  4. Derive your user control from the CustomTokenEditDropDownControlBase class in code.

    This class provides all necessary functionality that a control may require as a TokenEdit's drop-down. To acheive this goal, you will overload this class' methods with the following steps.

  5. The first method you will require is the SetDataSource method. It takes an object as a parameter and allows you to bind your custom drop-down control to data (if the control used supports data binding). This method is called automatically each time a drop-down is about to be displayed. In this example, a very simple scenario is described - a list containing tokens is created and populated with 10 tokens, and for each token in this list a new gallery item is created.

  6. For the next step, override the GetItemCount method. You need to return the number of tokens within the drop-down control. Otherwise, the editor will not display its drop-down. In this example, this count depends on the number of tokens added to the list in the previous step.

  7. To tweak the details of your custom drop-down, override the CalcFormHeight and CalcFormWidth methods that return the drop-down height and width respectively.

  8. Assign a new instance of your custom drop-down control to the RepositoryItemTokenEdit.CustomDropDownControl property.

  9. If you now launch the application and try to enter something in the editor, your custom drop-down with 10 items will be displayed. But, clicking gallery items will do nothing and no new token will be added to the editor's edit box. To provide this functionality, you need to manually access the gallery's OwnerControl object (which will be your TokenEdit control) and call its ClosePopup method with the PopupCloseMode.Normal parameter that tells the editor that its drop-down was intentionally closed. Then, you will need to override the GetResultValue method - it will be called automatically after a drop-down is closed and needs to return a token (if any) that was selected in this drop-down.

  10. Depending on the control you have chosen as the TokenEdit drop-down, the previous step could be your last. For instance, if you use a GridControl, you need only to follow the steps above (except for setting the BaseView.Editable property to false to avoid entering the edit mode each time a grid cell is clicked). But with some editors, like GalleryControl in this example, you need to deal with the fact that each editor works with user focus in its own way. The GalleryControl keeps the user focus when the drop-down is closed. This causes the drop-down to be closed differently than you would expect, like when you call the ClosePopup method with the Normal parameter. Instead, the GalleryControl will be closed in the Immediate mode, which corresponds to an unexpected close due to losing focus.


    The editor within your custom drop-down control must be able to lose focus when the drop-down closes.

    To fix this issue, create a new custom class that will derive from the GalleryControl. The only thing you need is to override its AllowFocus property so it will always return false.

    This step can vary, depending on the control chosen. For instance, if you use the TreeList control, you will need to modify its ControlStyle, as shown in the code below.

    Rebuild the solution and remove your GalleryControl from the UserControl. Then, since you used the ToolboxItem(true) attribute, you will be able to find your custom GalleryControl descendant in the Visual Studio toolbox and drop it onto the User Control.

    Remember to search the previous gallery name and replace it with the new gallery name throughout the solution.

  11. Launch the application to see the result.

Expanded Code Central Examples

To explore and download solutions that demonstrate different controls used as the TokenEdit drop-down controls, click a corresponding link below.

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