WklTokenBox

Dim myWklTokenBox As WklTokenBox
Set myWklTokenBox = Me!ControlName.Object

A box of tokens (tags, roles, keywords): each value is a chip with a remove button, new values are typed into the box with suggestions as you type.

None

Use the token box where a record has a short list of values of one kind - the roles of a user, the tags of a document, the e-mail recipients of a rule. It binds like an Access subform: RecordSource names the child table (or query), ValueField the field that holds one value, and LinkChildFields/LinkMasterFields connect the child rows to the record of the form, also with several fields. Each token is one child row. Adding a token inserts its row at once, removing it deletes the row at once, as a subform saves its rows; there is no pending state and no Undo.

For the box to follow the record, set its Control Source (ControlSource of the Access control) to the key field of the form: Access writes it into MasterValue on every record change, and the box reads the master values from LinkMasterFields and loads the tokens of that record. The box also checks the master values four times a second, so it follows the record even without a Control Source. On a new record that is not saved yet, the box shows no tokens and refuses input until the record has its key, as a subform does.

Without RecordSource the box is unbound: Text holds the values, joined by Separator, and code saves them where it wants.

In design view, Properties of the control opens its designer with the pages Data (child table and link), Suggestions and rules, and Appearance (caption, colors, font, a preview with sample values); OK refuses a pattern that does not compile, an empty separator, a bound box without value field and link fields of different number. A walkthrough: How to: Keep several values of a record as tokens.

The user types a value and confirms it with Enter, a one-character separator, or by picking a suggestion (Down opens the list); leaving the box with text also adds it, Esc clears the input. Backspace in an empty input selects and then removes the last token; Left and Right move between tokens, Delete removes the selected one. Suggestions come from SuggestionList and SuggestionSource; AllowFreeText = False accepts only suggested values. Pattern and ValidationText check each new value, and a value that is already a token is refused. A refused value stays in the input, and the reason appears below the box and in ErrorText.

Enabled, Locked, Visible, Tab Stop, and ControlTip Text are the properties Access gives every ActiveX control. A locked box, a form with Allow Edits set to No, and the design view show the tokens without remove buttons and refuse input.

Screen readers hear the box as a list named by Caption (or the control name); each token is a list item with a button “entfernen” that a screen reader can invoke.

A list column can show the same chips read-only: wedTokens as Editor of a column of WklGrid or WklTreeList, over a field that joins the values of the child rows into one text.

Do not use the multivalued fields of Access for this: they exist only in Access tables (not on SQL Server or over ODBC), and Access saves them with the parent record. A child table works with every back end.

An ActiveX control: inserted into a form in design view (Form Design › Controls › ActiveX Controls); reports are not supported. VBA reaches it through the Object property of the control, where ControlName is the name of the control on the form.

None

None

Property Get Text() As String
Property Let Text(RHS As String)

Gets or sets all tokens as one text.

None

Property value: String – The values joined by Separator and one blank, for example Red; Green; Blue. When set, the text is split at Separator, blanks around each value are removed, empty values and repeated values are dropped.

Setting Text of a bound box writes only the differences: it deletes the child rows of tokens that are no longer in the text and inserts rows for the new ones, without the events TokenAdding … Change. The values are not checked against Pattern or AllowFreeText; code is trusted, as with AddToken and RemoveToken. If writing a row fails, DataError occurs and the box reads the tokens from the table again. On a new record that is not saved yet, a linked box writes nothing.

Read/write.

Me!tokRollen.Object.Text = "Leser; Autor"

Declared by WklTokenBox.

Property Get Separator() As String
Property Let Separator(RHS As String)

Gets or sets the separator of Text and SuggestionList.

None

Property value: String – Any text that is not empty; ; (default). An empty text raises wkeInvalidValue.

Typing a separator of one character in the box also confirms the value before it. Choose a character that never occurs in a value.

Read/write.

None

Declared by WklTokenBox.

Property Get RecordSource() As String
Property Let RecordSource(RHS As String)

Gets or sets the child table or query that holds one row per token.

None

Property value: String – The name of a table or query, or a SQL statement; empty (default) for an unbound box.

The source must be updatable: the box inserts and deletes its rows. A linked SQL Server table needs a primary key or a unique index, as for any edit in Access. The rows are read and written through the database of the form (DAO), so linked ODBC tables work as local ones. Messages of the back end, for example a violated constraint, reach DataError.

Read/write.

None

Declared by WklTokenBox.

Property Get ValueField() As String
Property Let ValueField(RHS As String)

Gets or sets the field of the child row that holds the value of the token.

None

Property value: String – The name of a field of RecordSource.

A row whose field is Null or an empty text gives no token.

Read/write.

None

Declared by WklTokenBox.

Property Get LinkChildFields() As String
Property Let LinkChildFields(RHS As String)

Gets or sets the fields of the child rows that link them to the record of the form.

None

Property value: String – Field names separated by ;, as for a subform; empty (default) shows all rows of RecordSource.

A new token's row gets the master values in these fields. The number and order of the fields must match LinkMasterFields.

Read/write.

None

Declared by WklTokenBox.

Property Get LinkMasterFields() As String
Property Let LinkMasterFields(RHS As String)

Gets or sets the fields or controls of the form whose values the child rows must match.

None

Property value: String – Field or control names of the form separated by ;, as for a subform.

Read/write.

None

Declared by WklTokenBox.

Property Get MasterValue() As Variant
Property Let MasterValue(RHS As Variant)

Gets or sets the value Access writes into the box on every record change.

None

Property value: Variant – Any value.

MasterValue is the bound property of the box: set the Control Source of the Access control to the key field of the form, so Access writes it on every record change. It is only the signal; the values that select the child rows always come from LinkMasterFields. When they have changed, the box loads the tokens of the new record.

Read/write.

None

Declared by WklTokenBox.

Property Get SuggestionSource() As String
Property Let SuggestionSource(RHS As String)

Gets or sets a table, query or SQL statement whose first column lists the suggestions.

None

Property value: String – The name of a table or query, or a SQL statement; empty (default) for none.

The source is read once, when the suggestions are first needed, and again on Requery. The suggestions of SuggestionList come first. A value that is already a token is not suggested again.

Read/write.

Me!tokRollen.Object.SuggestionSource = "SELECT Rolle FROM tblRolle ORDER BY Rolle"

Declared by WklTokenBox.

Property Get SuggestionList() As String
Property Let SuggestionList(RHS As String)

Gets or sets suggestions as a value list.

None

Property value: String – Values joined by Separator, for example Leser; Autor; Admin; empty (default) for none.

Read/write.

None

Declared by WklTokenBox.

Property Get AllowFreeText() As Boolean
Property Let AllowFreeText(RHS As Boolean)

Gets or sets whether any typed value can become a token.

None

Property value: Boolean – True (default) accepts any value; False accepts only a value of the suggestions.

With False, a typed value that matches a suggestion becomes a token in the spelling of the suggestion.

Read/write.

None

Declared by WklTokenBox.

Property Get Pattern() As String
Property Let Pattern(RHS As String)

Gets or sets a regular expression each new value must match as a whole.

None

Property value: String – A .NET regular expression; empty (default) for none. An expression that does not compile raises wkeInvalidValue.

Read/write.

Me!tokTags.Object.Pattern = "[a-z0-9-]+"
Me!tokTags.Object.ValidationText = "Nur Kleinbuchstaben, Ziffern und Bindestrich."

Declared by WklTokenBox.

Property Get ValidationText() As String
Property Let ValidationText(RHS As String)

Gets or sets the message when Pattern refuses a value.

None

Property value: String – Any text; empty (default) for the generated message.

Read/write.

None

Declared by WklTokenBox.

Property Get MatchCase() As Boolean
Property Let MatchCase(RHS As Boolean)

Gets or sets whether tokens that differ only in case are different.

None

Property value: Boolean – False (default) treats Rot and rot as the same token, as Access compares text; True tells them apart.

Read/write.

None

Declared by WklTokenBox.

Property Get Caption() As String
Property Let Caption(RHS As String)

Gets or sets the name of the box in messages and for screen readers.

None

Property value: String – Any text; empty (default) for the control name.

Read/write.

None

Declared by WklTokenBox.

Property Get BackColor() As OLE_COLOR
Property Let BackColor(RHS As OLE_COLOR)

Gets or sets the background color.

None

Property value: OLE_COLOR – An OLE color; the window background of Windows (vbWindowBackground, default).

Read/write.

None

Declared by WklTokenBox.

Property Get ForeColor() As OLE_COLOR
Property Let ForeColor(RHS As OLE_COLOR)

Gets or sets the color of the token text and the input.

None

Property value: OLE_COLOR – An OLE color; the window text of Windows (vbWindowText, default).

Read/write.

None

Declared by WklTokenBox.

Property Get FontName() As String
Property Let FontName(RHS As String)

Gets or sets the font of the tokens and the input.

None

Property value: String – The name of an installed font; “Segoe UI” (default). An empty name raises wkeInvalidValue.

Read/write.

None

Declared by WklTokenBox.

Property Get FontSize() As Long
Property Let FontSize(RHS As Long)

Gets or sets the font size in points.

None

Property value: Long – 6 to 72; 9 (default). Other values raise wkeInvalidValue.

Read/write.

None

Declared by WklTokenBox.

Property Get Count() As Long

Gets the number of tokens.

None

Property value: Long – 0 or more.

Read-only.

None

Declared by WklTokenBox.

Property Get Item(ByVal Index As Long) As String

Gets the value of a token.

Property value: String – The value of the token.

Read-only.

Dim i As Long
For i = 0 To Me!tokRollen.Object.Count - 1
    Debug.Print Me!tokRollen.Object.Item(i)
Next

Declared by WklTokenBox.

Function AddToken(ByVal Value As String) As Boolean

Adds a token by code.

Return value: Boolean – The value to add.

The value passes the same checks as typed input (Pattern, AllowFreeText, an existing token); ErrorText names the reason of a refusal. A bound box inserts the child row; a linked box on a new record that is not saved yet refuses, because the row would belong to no record. The events TokenAdding, TokenAdded and Change do not occur.

None

Declared by WklTokenBox.

Function RemoveToken(ByVal Value As String) As Boolean

Removes a token by code.

Return value: Boolean – The value to remove; compared as MatchCase says.

A bound box deletes the child rows with this value. The events TokenRemoving, TokenRemoved and Change do not occur.

None

Declared by WklTokenBox.

Sub Requery()

Reads the tokens and the suggestions again.

None

Use it after code has changed the child table or the suggestion source behind the box's back.

None

Declared by WklTokenBox.

Property Get ErrorText() As String

Gets the reason why the last value was refused.

None

Property value: String – The message also shown below the box; empty after a value was accepted.

Read-only.

None

Declared by WklTokenBox.

Property Get ListRows() As Long
Property Let ListRows(RHS As Long)

Gets or sets how many suggestions the list shows at most.

None

Property value: Long – 1 to 50; 8 (default). Other values raise wkeInvalidValue.

Read/write.

None

Declared by WklTokenBox.

Property Get ColorScheme() As WklColorScheme
Property Let ColorScheme(RHS As WklColorScheme)

Gets or sets the color scheme the control draws in.

None

Property value: `WklColorScheme` – wcoAutomatic (default), wcoLight, wcoDark or wcoHighContrast.

wcoAutomatic follows, in this order, Windows high contrast mode, then the color set of the database design (Access: Design › Themes or Colors), and draws light when the database has no design or the control is on an Excel or Word UserForm. Office's own design setting and the Windows app mode are not followed: a database looks the same on every PC. In high contrast mode the control always uses the system colors. The scheme colors background and text (while BackColor and ForeColor keep the system defaults), the tokens, the selection and the suggestion list; a BackColor you set wins over the scheme. Every text keeps a contrast of at least 4.5:1. The control reads the database design after it is first drawn, never while Access draws the form, and again when the form opens anew. The value is saved with the form.

Read/write.

None

Declared by WklTokenBox.

Event TokenAdding(ByVal Value As String, ByRef Cancel As Integer)

Occurs before the user adds a token.

In a form module: Private Sub <ControlName>_TokenAdding(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklTokenBox.

Event TokenAdded(ByVal Value As String)

Occurs after the user has added a token; a bound box has inserted its child row.

In a form module: Private Sub <ControlName>_TokenAdded(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklTokenBox.

Event TokenRemoving(ByVal Value As String, ByRef Cancel As Integer)

Occurs before the user removes a token.

In a form module: Private Sub <ControlName>_TokenRemoving(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklTokenBox.

Event TokenRemoved(ByVal Value As String)

Occurs after the user has removed a token; a bound box has deleted its child row.

In a form module: Private Sub <ControlName>_TokenRemoved(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklTokenBox.

Event Change()

Occurs after the user has added or removed a token, after TokenAdded or TokenRemoved.

None

It does not occur for Text, AddToken, RemoveToken or a record change. Like all events of an ActiveX control it needs a procedure in the form's module.

In a form module: Private Sub <ControlName>_Change(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklTokenBox.

Event DataError(ByVal DataErr As Long, ByVal Description As String, ByRef Response As Integer)

Occurs when the child rows or the suggestions cannot be read or written.

A token whose row could not be inserted is not added, a token whose row could not be deleted stays. Errors while reading show no message box: the box stays empty, and the event is the only report.

In a form module: Private Sub <ControlName>_DataError(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklTokenBox.