Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [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
    Templated ListBox Items
   [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
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap 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]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Token Edit Control

The WinForms Token Edit Control is an editor inspired by address field controls seen in modern mail clients (services) such as Microsoft Outlook or Google's Gmail. Visually the Token Edit Control is a simple text edit, where end-users may enter textual data. The editor validates the entered text and converts valid text blocks into tokens - separate visual elements that can display a text string, an icon, can be clicked and hovered. In the default mode (TokenList mode), text validation is disabled and end-users are only allowed to select from the range of predefined tokens.

This topic contains the following sections:

In this topic, you will get to know the main features of the Token Edit Control and learn how to use this editor in your application.

Expanded What are tokens?

A token is the TokenEditToken class instance to which a valid text block is transformed. The following figure illustrates an example of the Token Edit Control with two validated text blocks, already transformed into tokens, and a text still being entered to the editor.

As opposed to plain text strings, tokens are non-editable objects and treated by an editor as a solid element. This means once the text is converted into token, you cannot modify its text. Pressing the Backspace key will remove the entire token from the editor.

To populate the editor with tokens, use the Edit Tokens... link within the control's smart tag menu at design-time (see the image below), or add TokenEditToken objects to the RepositoryItemTokenEdit.Tokens collection in code. Note that if you populate token editor in code, wrap your code in BeginUpdate/EndUpdate method calls to improve the performance.

Technically, each token contains only text and value. At runtime however, each token can display a glyph.

Expanded Token Text and Token Value

Token text and value are managed by the TokenEditToken.Description and TokenEditToken.Value properties respectively. The Description property specifies the token text that will be visible to end-users at runtime. Token Values are, in turn, used internally and never shown to end-users.

Important

Token values are used by the BaseEdit.EditValue property, which reflects currently selected (visible within the editor's text box) tokens within this Token Edit Control. Depending on the RepositoryItemTokenEdit.EditValueType property value, the EditValue property returns a string, BindingList structure or enumeration. This edit value is built from token values, not their descriptions. This leads to three conditions that must be fulfilled for the Token Edit to work properly:

  • Each token requires a value. When creating tokens at design-time, each token receives an auto-generated value (Value1, Value2, Value3 etc). If you populate the RepositoryItemTokenEdit.Tokens collection manually in code, remember to assign a value for each token added.
  • Token values must be unique. Otherwise, the exception will be raised.
  • Since the Token Edit identifies its tokens by their values' ToString() method, it must return unique values for each individual token. By default, this method returns the value object's type name. If you face such a situation, you can either override the ToString() method of an object that serves as a token value so it will return the unique value (for instance, the customer ID or the index of a token), or pass this unique value to the token itself as its value (see this example to learn more).

To manually modify the token text shown on-screen without changing the Description property, handle the RepositoryItemTokenEdit.CustomDrawTokenText event, as shown below.

Expanded Token Glyphs

The TokenEditToken class objects do not contain any properties that store token icons. However, each token can display a glyph, when selected.

  • Glyph functionality
    By default, clicking a token glyph removes the related token from the editor's edit box. To disable this behavior, set the RepositoryItemTokenEdit.DeleteTokenOnGlyphClick property to DefaultBoolean.False.

  • Disabling glyphs
    Default token glyphs are small cross icons, which maintains the line with the default RepositoryItemTokenEdit.DeleteTokenOnGlyphClick property value. To completely hide these glyphs set the RepositoryItemTokenEdit.ShowTokenGlyph property to false.

  • Custom glyphs
    To draw custom glyphs, handle the RepositoryItemTokenEdit.CustomDrawTokenGlyph event as shown below.
    The following figure illustrates tokens with customly drawn glyphs.

  • Glyph alignment
    The editor draws token glyphs before the token description by default. To place token glyphs after descriptions, use the RepositoryItemTokenEdit.TokenGlyphLocation property.

Expanded Separators

Separator characters tell the Token Edit Control that the following text, entered to the control's text edit, is the beginning of a new block that should be validated separately. In other words, separators are characters that delimit tokens. You can set multiple separator characters for a single Token Editor. To do so, modify the RepositoryItemTokenEdit.Separators collection in code, or invoke the control's smart-tag menu and click Edit Separators…, as shown below.

The separator character used to delimit token values for the EditValue object is specified by RepositoryItemTokenEdit.EditValueSeparatorChar property and can differ from separators that end-users have to enter. The default edit value separator (comma character) is stored within the RepositoryItemTokenEdit.DefaultEditValueSeparatorChar field.

Expanded Edit Modes

The Token Edit Control can run in two modes - TokenList and Manual. Depending on the editor mode, the editor either allows end-users to add unknown tokens or not. To switch the token edit mode use the RepositoryItemTokenEdit.EditMode property.

TokenList Mode

This is the default Token Edit Control mode in which end-users are allowed to add only predefined tokens (tokens that were previously added to the RepositoryItemTokenEdit.Tokens collection). End-users are free to enter any string data to the editor, but if it does not match any existing token, it will remain as plain text and will be removed when the editor loses focus. To assist end-users, each time a character is entered to the editor, a drop-down menu is shown. This drop-down displays tokens that match the entered text or (if none were found) all predefined tokens that have not been added yet. The following animation illustrates an example.

Expanded Show animation

Manual Mode

In this mode end-users are allowed to enter any desired text to the editor, so predefined tokens can be mixed with new tokens. Not any entered text is converted into tokens, but only those text blocks that pass validation (see the 'Validation' section below). The following animation shows the Token Edit Control running in this mode.

Expanded Show animation

Expanded Validation

In order to transform text into a token, the text block must pass custom validation. Validation is performed during the RepositoryItemTokenEdit.ValidateToken event. For example, the following code transforms the entered text into a token if the text is an email address.

The main scenarios in which the ValidateToken event occurs are as follows:

  • the editor has lost focus;
  • an end-user has entered a separator character;

To disable the specific validation scenario, use the RepositoryItemTokenEdit.ValidationRules property.

Tip

Event arguments also provide the capability to read and modify token values and descriptions. To do so, use the e.Value and e.Description properties. Thus, by handling this event you can also manually process all tokens and modify them as required.

Note

The ValidateToken event is not fired when the editor is in Token List mode (see the 'Drop-Down List and Edit Mode' section below), since in this mode, end-users are only allowed to select existing tokens from the drop-down list, which do not require validation.

Expanded Drop-Down Menu

The Token Edit Control's drop-down menu displays tokens, contained within the RepositoryItemTokenEdit.Tokens collection and appropriate for selecting at the moment. The animation below illustrates this drop-down menu and its runtime features, available to end-users.

Expanded Show animation

The following properties allow you to customize drop-down menu's appearance and behavior.

Expanded Peek Panel

By default, each token can display a peek panel on hover. This feature allows you to peek into a specific token for some additional information associated with this token (see the image below). The pop-up peek panel is a FlyoutPanel assigned to the editor's RepositoryItemTokenEdit.PopupPanel property and its options are stored in the RepositoryItemTokenEdit.PopupPanelOptions properties section.

To implement this feature, drop the FlyoutPanel component onto the form and assign it to the Token Editor via the editor's smart-tag menu, as illustrated in the figure below.

Specify the PopupPanelOptions.ShowPopupPanel and PopupPanelOptions.Location properties to specify whether or not the assigned panel should be displayed, and if so, whether it should be displayed above or below the token. To populate this panel, handle the RepositoryItemTokenEdit.BeforeShowPopupPanel event and use its e.Description and e.Value parameters to get the display text and the tag of the associated token element.

How would you rate this topic?​​​​​​​