tokenentry::tokenentry - Create and manipulate tokenentry widgetstokenentry::tokenentry pathName ?options?-background or -bg-borderwidth or -bd-cursor-exportselection-font-foreground or -fg-highlightbackground-highlightcolor-highlightthickness-insertbackground-insertborderwidth-insertofftime-insertontime-insertwidth-padx-pady-relief-selectbackground-selectborderwidth-selectforeground-setgrid-takefocus-xscrollcommand-yscrollcommand-dropdownformatstring string-dropdownheight numlines-dropdownmaxheight numlines-height numlines-listvar variable-listvaronly boolean-matchcase bool-matchdisplayindex index-matchindex index-matchmode glob|regexp-state normal|disabled-tokenbg color-tokenbordercolor color-tokenfg color-tokenselectbg color-tokenselectfg color-tokenselectbordercolor color-tokenshape shape(s)-tokenvar variable-watermark text-watermarkfg color-width characters-wrap bool-background color-bg color-bordercolor color-foreground color-fg color-selectbackground color-selectbg color-selectbordercolor color-selectforeground color-selectfg color-shape shape(s)-text textpathName cget
optionpathName configure
?option? ?value option value ...?pathName entrygetpathName entrytagpathName listtagpathName see
indexpathName tokencget
optionpathName tokenconfigure
?option? ?value option value ...?pathName tokendelete
firstIndex ?lastIndex?pathName tokengetpathName tokenindex
namepathName tokeninsert
index namespathName tokenselection
option args
pathName tokenselection clear
firstIndex ?lastIndexpathName tokenselection getpathName tokenselection set
firstIndex ?lastIndexpathName xview
args
pathName xviewpathName xview moveto fractionpathName xview scroll number whatpathName yview
args
pathName yviewpathName yview moveto fractionpathName yview scroll number whattokenentry::tokenentry - Create and manipulate tokenentry widgetstokenentry::tokenentry pathName ?options?
-background or -bg-borderwidth or -bd-exportselection-font-foreground or -fg-highlightbackground-highlightcolor-highlightthickness-insertbackground-insertborderwidth-insertofftime-insertontime-insertwidth-padx-pady-relief-selectbackground-selectborderwidth-selectforeground-setgrid-takefocus-xscrollcommand-yscrollcommand| Command-Line Name: | -dropdownformatstring |
| Database Name: | dropDownFormatString |
| Database Class: | DropDownFormatString |
Specifies the format string to use when displaying each entry in the
-listvarlist. By default, the formatstring is set to {%s}. The value of the format string can be value that is legal to theformatTcl command.
| Command-Line Name: | -dropdownheight |
| Database Name: | dropDownHeight |
| Database Class: | DropDownHeight |
Specifies the number of text lines to display in the drop-down listbox that pops up when the user enters text into token entry text field. If the value is set to 0, the drop-down listbox will be set to the lesser of the number of elements in the
-listvarlist or the value specified by-dropdownmaxheight. By default, the drop-down height is set to a value of 0.
| Command-Line Name: | -dropdownmaxheight |
| Database Name: | dropDownMaxHeight |
| Database Class: | DropDownMaxHeight |
If the value of
-dropdownheightis set to a value of 0, this value determines the maximum number of lines that will be displayed in the drop-down listbox. By default, this value is set to 5.
| Command-Line Name: | -height |
| Database Name: | height |
| Database Class: | Height |
Specifies the number of lines that can be displayed in the widget without scrolling. The widget does allow scrolling via the
-xscrollcommandand-yscrollcommandcommands. By default, this is set to a value of 1.
| Command-Line Name: | -listvar |
| Database Name: | listVar |
| Database Class: | ListVar |
Specifies a variable which contains a Tcl list containing the names of available token names that will be matched against user-specified text and displayed in a drop-down listbox for quick and accurate selection. If this option is not specified, no drop-down listbox will be displayed as the user enters text into the widget. The given variable must be a reference to a global variable.
The Tcl list can contain sublists. This makes it possible to store values like e-mail addresses where each element in the list could be comprised of both an e-mail address and a name where the user could either type a part of the e-mail address or the person's name and get a match in the drop-down list box. However, when the user selects a name in the drop-down listbox, the token could show just the e-mail address or the name.
If a multi-dimensional Tcl list is used, the user will want to configure the
-matchmode,-matchindex,-matchcaseand-matchdisplayindexoptions to control the matching process.
| Command-Line Name: | -listvaronly |
| Database Name: | cco listVarOnly |
| atabase Class: | ListVarOnly |
If set to a value of true, the tokenentry widget will guarantee that the user may only enter/select values from the list of entries specified in the
-listvarvariable. If this value is set to false (the default), the user may enter any value in the widget, including those from the-listvarvariable. This option is only used if the-listvaroption is also specified.
| Command-Line Name: | -matchcase |
| Database Name: | matchCase |
| Database Class: | MatchCase |
Specifies whether case matching should be used or not when matching the user-input string to the values in the
-valueslist. This option should be set to a boolean value. By default, this option is set to false.
| Command-Line Name: | -matchdisplayindex |
| Database Name: | matchDisplayIndex |
| Database Class: | MatchDisplayIndex |
When an item in the drop-down listbox is selected by the user, this option specifies the path of indices (like that used by the
lindexorlsetcommands) that leads to the element to display in the token.For example, suppose we have the following tokenentry widget:
If the user, chose the entry for Alice, the token would be populated with the string "Alice". However, if we appended the following code:tokenentry::tokenentry .te -values {{{John} {john@example.comd}} {{Alice} {alice@example.com}} {{Chris} {chris@example.com}}} -matchdisplayindex 0If Alice was selected from the drop-down listbox again, the string "alice@example.com" would be displayed in the token..te configure -matchdisplayindex 1
| Command-Line Name: | -matchindex |
| Database Name: | matchIndex |
| Database Class: | MatchIndex |
If this option is specified, specifies a path of indices (like that used by the
lindexorlsetcommands) within each element in the-valueslist to allow the location of the term being matched against. By default, all fields within each list item will be matched against.
| Command-Line Name: | -matchmode |
| Database Name: | matchMode |
| Database Class: | MatchMode |
Specifies the mode used to match the results of the user-entered text to the contents of the
-listvarlist. The allowed values are: glob and regexp. If glob is specified, then glob-style pattern matching is used using the same rules as thestring matchcommand. If regexp is specified, then regular expression pattern matching is used using the rules described in there_syntaxreference page. By default, the match mode is set to glob.
| Command-Line Name: | -state |
| Database Name: | state |
| Database Class: | State |
Specifies the current state of the widget: normal or disabled. If the widget state is normal the user may fully interact with the widget. If the state is disabled, the widget will be viewable only, but any interactions with the tokens or entry portion of the widget will be turned off.
| Command-Line Name: | -tokenbg |
| Database Name: | tokenBackground |
| Database Class: | TokenBackground |
Specifies the color to use for the background of the token when it is not selected.
| Command-Line Name: | -tokenbordercolor |
| Database Name: | tokenBorderColor |
| Database Class: | TokenBorderColor |
Specifies the color to use for the border of the token when it is not selected.
| Command-Line Name: | -tokenfg |
| Database Name: | tokenForeground |
| Database Class: | TokenForeground |
Specifies the color to use for the token text when the token is not selected.
| Command-Line Name: | -tokenselectbg |
| Database Name: | tokenSelectBackground |
| Database Class: | TokenSelectBackground |
Specifies the color to use for the background of the token when it is selected.
| Command-Line Name: | -tokenselectbordercolor |
| Database Name: | tokenSelectBorderColor |
| Database Class: | TokenSelectBorderColor |
Specifies the color to use for the border of the token when it is selected.
| Command-Line Name: | -tokenselectfg |
| Database Name: | tokenSelectForeground |
| Database Class: | TokenSelectForeground |
Specifies the color to use for the token text when the token is selected.
| Command-Line Name: | -tokenshape |
| Database Name: | tokenShape |
| Database Class: | TokenShape |
Specifies shape(s) to use for the left and right side of the token. See the token
-shapeoption for an explanation of the legal shape values and their usage.
| Command-Line Name: | -tokenvar |
| Database Name: | tokenVar |
| Database Class: | TokenVar |
Specifies a variable in which the tokenentry widget will automatically store the token values when they are modified. The variable must reference a global variable.
| Command-Line Name: | -watermark |
| Database Name: | watermark |
| Database Class: | Watermark |
Specifies a textual string that will be used as a watermark in the entry field. The watermark string cannot be copied or selected and only is visible when the entry field is empty. Once the user begins to type in the entry field, the watermark string is cleared and the user's input data is visible. By default, no watermark is displayed in the entry field. The watermark can be cleared by setting this option to the empty string.
| Command-Line Name: | -watermarkfg |
| Database Name: | watermarkForeground |
| Database Class: | Foreground |
Specifies the foreground color to use when a watermark is to be displayed in the entry field.
| Command-Line Name: | -width |
| Database Name: | width |
| Database Class: | Width |
Specifies the number of characters (based on the average character size of the currently assigned font) that can fit in the widget without wrapping. By default, the widget width is set to a value of 50.
| Command-Line Name: | -wrap |
| Database Name: | wrap |
| Database Class: | Wrap |
Specifies whether line wrapping should be enabled (true) or disabled (false). If line wrapping is enabled, tokens and text will continue onto the next line (i.e., y-axis scrolling will be needed to view all tokens). Text will be wrapped on a word basis in this mode. If line wrapping is disabled, tokens will continue on the same line (i.e., x-axis scrolling will be needed to view all tokens). By default, this option will be set to false.
tokenentry::tokenentry command creates a new window named
pathName and of the class Tokenentry, and makes it
into a tokenentry widget. Additional options, described above, may be
specified on the command-line or in the option database to configure aspects of the
tokenentry sucah as its colors, font, and sizing. The
tokenentry::tokenentry command returns its pathName
argument. At the time this command is invoked, there must not exist a window named
pathName, but pathName's parent must exist.
-listvar option). When this value list is
specified, any user-specified text entered into the widget will be matched against this
list of values and if any matches are found, they will be displayed in a drop-down listbox below the
tokenentry widget. This drop-down listbox can be used by the user to quickly and accurately
select an item to tokenize.
tokencget
and the tokenconfigure commands:
-background color-bg color
-bordercolor color
-foreground color-fg color
-selectbackground color-selectbg color
-selectbordercolor color
-selectforeground color-selectfg color
-shape shape(s)
shape(s) list can
contain one or two shape values. The legal values for shape(s)
are pill (large rounded corners), tag (angled corners), square
(squared corners), eased (slightly rounded corners), and ticket
(concave corners). If shape(s) contains a single value, both the
left and right sides of the token will take on the given shape. If
shape(s) contains two values, the first value refers to the shape
of the left side of the token and the second value refers to the shape of the right
side of the token.
tokenentry::tokenentry .te .te insert end foobar .te tokenconfigure 0 -shape pill
tokenentry::tokenentry .te .te insert end foobar .te tokenconfigure 0 -shape [list tag square]
-text text
tokenentry::tokenentry command creates a new Tcl command whose
name is pathName. This command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
option and the args determine the exact behavior
of the command. The following commands are possible for tokenentry widgets:
pathName cget optionpathName configure ?option? ?value option value ...?pathName entrygetpathName entrytagpathName listtagpathName see indexpathName tokencget index optionpathName tokenconfigure index option value ?option value ...?index.
Returns the empty string. See TOKEN CONFIGURATION OPTIONS
for the available options.
pathName tokendelete firstIndex ?lastIndex?lastIndex is not specified, deletes the token at firstIndex.
If lastIndex is specified, deletes the tokens between
firstIndex and lastIndex, inclusive.
pathName tokengetpathName tokenindex namepathName tokeninsert index namesindex. The
names is a list of token values to add. Tokens will be inserted such
that their order will be preserved in the listed order.
pathName tokenselection option argsoption:
pathName tokenselection clear firstIndex ?lastIndex?lastIndex is not specified, clears the selected token at the specified index.
If lastIndex is specified, clears all of the tokens between firstIndex
and lastIndex, inclusive.
pathName tokenselection getpathName tokenselection set firstIndex ?lastIndex?lastIndex is not specified, selects the token specified at the given index.
If lastIndex is specified, selects all of the tokens between firstIndex
and lastIndex, inclusive.
pathName xview argspathName xview-xscrollcommand option.
pathName xview moveto fractionpathName xview scroll number whatpathName yview argspathName yview-yscrollcommand option.
pathName yview moveto fractionpathName yview scroll number what-values list (if this option has been
set to a list value). Any matches (as determined by the matching options) are
displayed in a drop-down listbox to allow the user to quickly select a token value.
Comma or Enter key is pressed, the current text
entered into the widget will immediately be replaced with a token representing the
textual value.
Enter key is pressed, the
currently selected value in the drop-down listbox is used to create a token at the
current insertion point. If any non-tokenized text exists within the widget, it is
removed prior to the token being created for the selected value.
Tab key is pressed, focus will be given to the next window in
the parent window of the widget. If any text has been entered into the widget, it is
immediately replaced with a token containing the text.
Down key will change the selection
in the drop-down listbox to the value immediately below the currently selected value.
Additionally, the Up key will will change the selection in the drop-down
listbox to the value immediately above the currently selected value.
Escape key will hide the
drop-down listbox and return focus to the entry portion of the widget.
Control-x (or
Command-x on aqua-based windowing systems) will copy the selected text to
the clipboard and delete the selected text from the widget. If no text is currently
selected, the key binding will copy all of the non-tokenized text to the clipboard and
remove all non-tokenized text from the widget.
Control-c (or
Command-x on aqua-based windowing systems) will copy the selected text to
the clipboard. If no text is currently selected, the key binding will copy all of the
non-tokenized text to the clipboard.
Control-v (or
Command-v on aqua-based windowing systems) will paste the given string
information contained in the clipboard and insert it into the entry portion of the
widget. If the drop-down listbox is currently visible, it is hidden from view after
the paste operation.
Left arrow key is pressed, the token to the left of the insertion cursor is
selected and given the focus.
Right arrow key is pressed, the token to the right of the insertion cursor is
selected and given the focus.
<<TokenEntryModified>> event is automatically generated.
Shift key is down; this will adjust the end of the selection that was
nearest to the mouse when the left button was pressed. If the button id double-clicked
before dragging then the selection will be adjusted in units of whole words; if it is
triple-clicked then the selection will be adjusted in units of whole lines.
Control key down will reposition the
insertion cursor without affecting the selection.
Left and Right keys move the insertion cursor on
character/token to th left or right; they also clear any text selection. If left or right
is typed with the Shift key down, then the insertion cursor moves and the
selection is extended to include the new character. Control-Left and
Control-Right move the insertion cursor by words, and
Control-Shift-Left and Control-Shift-Right move the insertion
cursor by words and also extend the selection. Control-B and
Control-F behave the same as left and right, respectively.
Meta-B and Meta-F behave the same as Control-Left
and Control-Right, respectively.
Home and Control-A keys move the insertion cursor to the
beginning of its display line and clear any selection in the widget.
Shift-Home moves the insertion cursor to the beginning of the display line
and also extends the selection to that point.
End and Control-E keys move the insertion cursor to the
end of the display line and clear any selection in the widget. Shift-End
moves the cursor to the end of the display line and extends the selection to that point.
-values value is set to
a non-empty Tcl list, an arrow icon will be displayed to the right of the token text
to indicate that clicking on the arrow will display the drop-down list of all
available values. When the cursor leaves the token, the drop-down list arrow will
auto-hide. While the arrow is displayed, left-clicking the arrow will display the
drop-down listbox.
Delete key will delete
the given token, set the focus to the entry widget, and set the insertion cursor to
the point in the entry widget where the token previously existed.
Control-x (or Command-x on
aqua-based windowing systems) will copy the token's value to the clipboard as a string and
the token will be deleted from the widget.
Control-c (or Command-c on
aqua-based windowing systems) will copy the token's value to the clipboard.
<<TokenEntrySelected>>
event is generated.
Right or Left key is pressed,
the token is deselected and the insertion cursor is moved to the right or left of the token.
Additionally, if the drop-down listbox is currently shown, it is automatically closed.
Down arrow key is pressed, the drop-down
listbox (if available) is displayed and the first item in the listbox is selected.
Escape key will cause the drop-down listbox to be closed.
Return key is pressed, the token is removed, its text is inserted into the
text field in the same location, the text string is selected and focus is given to the
text field for immediate value editing.