TokenEditor control in DotNetBar for WinForms is an advanced text-box control which parses the input and converts it into the set of parts (tokens). This is very similar to email address entry text-box in modern email clients, but more flexible. Each text-part, token is validated before being accepted so it can be rejected if it does not pass the validation. This is an example of how this control looks like:

DotNetBar WinForms TokenEditor Control

In heart of TokenEditor control are EditToken object. Text entered by the user is converted to EditToken and validated before being accepted. EditToken object allows you to associate Value (for example an email address) and Text (for example an actual name for the email address) with token, as well as assign an Image or Symbol to be displayed next to the token text when selected.

TokenEditor provides auto-complete drop-down which will be filtered based on user input and which allows you to select token from predefined token list. TokenEditor.Tokens collection stores list of the EditToken objects displayed on drop-down:

DotNetBar for WInForms TokenEditor control auto-complete drop-down

This code shows an example of how Tokens collection is populated so the auto-complete popup shows values:

// Load data into the TokenEditor for stored already recognized email addresses
tokenEmails.Tokens.Add(new EditToken("", "Shawn Smith"));
tokenEmails.Tokens.Add(new EditToken("", "Pete Barley"));
tokenEmails.Tokens.Add(new EditToken("", "Toby Huck"));
tokenEmails.Tokens.Add(new EditToken("", "Steven Ratcliffe"));
tokenEmails.Tokens.Add(new EditToken("", "Dennis Smith"));

When a token is either entered as text and parsed and validated it gets stored in TokenEditor.SelectedTokens collection.

Separators and Validation

While user is entering text into the TokenEditor the control will watch for the characters listed in Separators collection and when they are encountered the text will be parsed, converted into the EditToken object and before the token is accepted and added to SelectedTokens collection the ValidateToken event is raised to give you an opportunity to modify and validate the EditToken object. By default Separators collection has comma “,” and semicolon “;” characters added which are used as the token separators.

ValidateToken event is used to validate the token before its added to SelectedTokens collection. ValidateTokenEventArgs are the event arguments that are provided in the event. You can set IsValid property to false to refuse the token so for example if you are validating the email address the code would look like this:

Regex _MailRegex = new Regex(@"^[-a-z0-9!#$%&'*+/=?^_`{|}~]+(?:\.[-a-z0-9!#$%&'*+/=?^_`{|}~]+)*@(?:[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?\.)*(?:aero|arpa|asia|biz|cat|com|coop|edu|gov|info|int|jobs|mil|mobi|museum|name|net|org|pro|tel|travel|[a-z][a-z])$", RegexOptions.Compiled);
private void tokenEmails_ValidateToken(object sender, DevComponents.DotNetBar.Controls.ValidateTokenEventArgs ea)
    // Validate email address before allowing it into the SelectedTokens collection
    ea.IsValid = _MailRegex.IsMatch(ea.Token.Value);

ValidateTokenEventArgs also provides following properties:

  • IsNewToken – which indicates whether token is a newly created token from the user entered text or an existing token from Tokens collection.
  • Token – which returns the reference to EditToken object which will be added to SelectedTokens collection if validation is passed, i.e. IsValid=true (which is default). You can perform modification on this object if needed.

TokenEditor as multi-selection combo-box

Starting with 12.2 version of DotNetBar we have added functionality to token editor control so you can use it as multi-selection combo-box control. For this simply set CheckBoxesVisible and DropDownButtonVisible properties to true and you will get drop-down button inside the token editor to show popup with item selection and popup will use check-boxes to indicate the current selection and allow selection/deselection of the items. Since by default TokenEditor allows entry of new items through keyboard entry to disallow that simply handle ValidateToken event and if event arguments IsNewToken property is true then set IsValid=false to reject new entries…

Key Properties

BackgroundStyle – returns an object which defines the appearance of control background and its border.

CheckBoxesVisible – indicates whether check-boxes are shown next to the list of tokens when popup is open. This allows you to create multi-selection style combo-box control when combined with DropDownButtonVisible property.

DropDownButtonVisible – indicates whether drop-down button is visible inside of the control which shows the popup when clicked.

DropDownHeight – indicates the height of the auto-complete drop-down.

DropDownWidth – indicates the width of the auto-complete drop-down.

EnablePopupResize – indicates whether auto-complete popup can be resized by end user.

EnterKeyValidatesToken – indicates whether when token text is entered into the text-box pressing the Enter key attempts to validate the token and converts the text to token.

IsPopupOpen – indicates whether auto-complete popup window is open.

MaxHeightLines – indicates maximum number of lines control will grow to when AutoSizeHeight=true. Set to 0 to indicates unlimited growth.

PopupCloseButtonVisible – indicates whether multi-column popup close button is visible.

PreservePopupSize – indicates whether auto-complete popup size is preserved between popup displays if popup is resized by end-user.

ReadOnly – indicates whether tokens can be added or removed by end user. Default value is false.

RemoveTokenButtonVisible – indicates whether remove token button is displayed on individual tokens so they can be removed from the selection.

Separators – collection of separators which are used to divide entered text into the tokens.

Tokens – collection of the tokens available for selection.

ValidateTokenTextOnLostFocus – indicates whether any text entered into the token editor is validated and converted to token when control loses focus.

Key Events

AutoCompletePopupOpened –  occurs after the auto-complete popup is opened.

BeforeAutoCompletePopupOpen – occurs before auto-complete popup is opened and allows you to cancel popup opening.

RemovingToken – occurs before token is removed from the SelectedTokens by end user.

SelectedTokensChanged – occurs when SelectedTokens collection changes.

ValidateToken – occurs when an token is selected from the auto-complete list or when text entry by end user is parsed into token to validate it.