TokenField
A custom Xojo class that works similar to a NSTokenField. You can type in and select various "tokens" and they will appear as items within the field. It supports auto-complete, mouse and keyboard control, and various events.

This class is provided as-is and there's no guarantee of future updates. However I wouldn't be surprised if there are...

Events

ClickedListButton
The list button was clicked. This button can be enabled by changing the ListButtonMode property and supplying an image to the ListButtonIcon property.

FailedToGenerateCustomToken
If AllowCustomTokens is set to false and the user presses return to save a Token, this event will fire. You can warn the user about not allowing custom Tokens.

GenerateTagForNewToken(tokenName as string) as boolean
A custom token will be generated, and the class gives you a chance to specify the tag for that token. If nothing is returned, the class will use the tokenName as the tag.

PressedEnterWithoutNewToken
The user has pressed enter in the field and there were no pending token entries. This means they probably want to save.

PressedEscapeKey
The user pressed escape within the field. They probably want to close it.

SelectedTokensChanged
One or more tokens were selected or removed. This will also fire after the user adds custom tokens.

TextChanged
The text in the field itself has changed.

TokenCreated(theToken as TokenClass)
A custom token has been created because there was no Available token that matched the user's entry.

TokenSelected(theToken as TokenClass)
A token was selected (meaning that it was added to the token list). This will fire if the user creates a new custom token. This event gives access to the individual token information, but may fire more than once if multiple tokens are selected simultaneously. Use SelectedTokensChanged event if you want an event that fires once.

WillHideAutoCompletePopup
The autocomplete "popup" will soon be hidden. You can use this to resize a window.

WillShowAutoCompletePopup
The autocomplete "popup" will soon be hidden. You can use this to resize a window.

Methods

AddAvailableToken(t as TokenClass)
Used to populate the AutoComplete list. Add as many available tokens as you'd like.

ClearAvailableTokens()
Will reset the autocomplete list. Please note that if there is text in the field and the token list is cleared, those tokens will no longer display correctly.

ClearCreatedTokens()
When a custom token is created, it will be stored in the class so that you can later save them all at once. You can get the list of created tokens using GetCreatedTokens, and clear it out after you've saved it by using ClearCreatedTokens.

DisplayAutoCompleteBox()
Will force open the autocomplete box. This can be used to show all available tokens if nothing has been recently typed.

GetCreatedTokens() as TokenClass()
When a custom token is created, it will be stored in the class so that you can later save them all at once. You can get the list of created tokens using GetCreatedTokens, and clear it out after you've saved it by using ClearCreatedTokens.

GetRawText() as string
This will retrieve the raw text of the content of the field. The raw text will include tokens in the format </TokenTag/>. This function can be used to save and later load information to/from the field. Please note you are responsible for saving reference to the actual tokens and any custom tokens. If a TokenTag is retrieved within the raw text and that raw text is later added to a different TokenField that does not have a matching TokenClass, it will not be properly displayed. The class will default to showing the Token's tag instead of the token's name.

SelectedTokens() as TokenClass()
Gets the list of currently selected Tokens. This can be used after SelectedTokensChanged to save any changes.

SetRawText(theText as string)
This will set the raw text of the content of the field. The raw text can include tokens in the format </TokenTag/>. This function can be used to save and later load information to/from the field. Please note you are responsible for first loading any reference to the actual tokens and any custom tokens. If a TokenTag is included in theText parameter that has has a tag that does not match any AvailableTokens, it will instead be displayed using the Tag instead of the Name. 

SelectToken(tokenID as string)
This will add the token to the text in the current cursor position. If AllowMissingTokens is false then the tokenID must match a TokenClass that has already been added via AddAvailableToken.

TriggerEnterKey()
This will simulate the user pressing the enter key. This can be used if a window's save button has been pushed and you want to make sure any partially entered tags are saved first.

Properties

AllowCustomTokens as boolean
If this is true, the user can type in whatever they'd like and press return to create a new token. If not, FailedToGenerateCustomToken will fire when they attempt to select a token that hasn't been added via AddAvailableToken

AllowMissingTokens as boolean
If somehow a token has been added to the field with a tag that doesn't match AvailableTokens, it will be automatically removed if this is false. If this is true, a token will be automatically generated and use the token's Tag as its text.

AutoCompleteBoxHeight as integer
The height of the listbox that will be displayed for the autocomplete box.

BackgroundColor as color
The background color of the field.

BorderColor as color
Color of a 1px border around the control.

InnerPadding as integer
Space between the control's edges and the nearest draw text/token.

ListButtonMode as integer
Will determine when the list button should be shown. Use enumeration ListButtonModes to determine between Off, MouseOver, and Always. You must supply a ListButtonIcon for it to draw.

ListButtonIcon as picture
The icon that will be drawn for the list button.

MultiLine as boolean
If this is false, the field will continue indefinitely horizontally when content is added. If true, you can turn it into more of a Text Area than a Text Field, where words and tokens will wrap if the content is wider than the control.

TextColor as color
The color of the text. Does not apply to tokens.

TextSelectionColor as color
The background color when text is selected. You can use declares to set this to the system selected color if you'd like.

TextSize as integer
The size of the text displayed within the field.

TokenCornerRadius as integer
Tokens are drawn as rounded rectangles. Set the value of the corner radius here.

TokenMargin as integer
The horizontal space between a token and the next text or token. Please note two tokens are next to each other this will be used twice.

TokenPaddingX as integer
The horizontal padding between the left/right edges of the token's outline and the token's text.

TokenPaddingY as integer
The vertical padding between the top/bottom edges of the token's outline and the token's text.

TriggerSelectionWithSpaceBar as boolean
If enabled, the user can attempt a token selection with the space bar in addition to the return and enter keys. If this is enabled, custom tokens can't be typed in and include spaces.