template-string

Arguments: editable-text

Returns the template for a single-line editable-text control, which constrains the number and type of characters that a user can type into the control. The value can be set at creation time by specifying the template-string initarg, or any time later by calling (setf template-string).

A template consists of two kinds of characters:

1. static characters that are shown in the control and over which users cannot type (the cursor is moved past these characters as the user types or uses the arrow keys).
2. template characters, which must be described in the *template-chars* association list (any character not in this alist is regarded as a static character). Initially the template characters appear as blank spaces, zeroes, or other default characters in the control and allow users to enter certain types of characters depending on which template character is specified for each position.

Templates can be cleared with clear-template.

Example:

(setf (template-string my-editable-text-widget) "999-99-9999")

This example would set up a template for entering a social security number. There is an entry in *template-chars* for the character #\9 indicating that a user must enter a numeral in its position, and that it displays initially as a space. There is no entry in *template-chars* for the dash character, so the dashes in this template will display as dashes, and users cannot type over them.

template-string is a property of the editable-text class, as well as the editable-text-column-mixin and combo-box-column-mixin  grid-widget classes.

Behavior of Various Keystrokes

When a graphical character is typed, it will be considered for the character position at the text cursor if there is a template character rather than a static character at that position. Otherwise it will be considered for the first position to the right of that position at which there is a template character, if any. If the typed character passes the predicate function for that position, then it will replace the character at that position. The text cursor will then move to the next template character position to the right, if there is one, and otherwise will move to the rightmost end of the template string. When the character is not valid at the current position, there is a beep and nothing else is done.

A special case is that if the text cursor is at the rightmost end of the template string, then typing a character will shift each character that has already been typed one template character position to the left, and then the new character is written to the rightmost template character position. This is typically used for entering numbers as with a calculator or ATM machine.

If any text is selected when a graphical character is typed, then the selected characters are first converted (cleared) to the initial print characters for those positions, then the text cursor is moved to the front of the selection (deselecting the text), and then the character is handled as above. An exception is that if the justification of the widget is :right and all of the text is selected, then the text cursor is moved to the end of the selection rather than to the front.

The left and right arrow keys will move the text cursor to the next template character position in each direction if there is one, or else to front or end of the template string if it is not there already. Pressing the left and right arrow keys while holding down the Shift key will select text as usual.

The Home key will move the text cursor to the first template character position that does not have a space in it, unless the text cursor is already in that posiiton, in which case it will move to the first template character position. (In other words, typing Home will first move to the beginning of the text that has been entered, and typing it again will move to the first typable position. That is intended to be useful especially when editing right-justified numbers.) Similarly, typing End will first move the text cursor just to the right of the last template character position that does not contain a space, unless the text cursor is already at that position, in which case it is moved just after the last template character position.

The Delete key will change the character at the text cursor to the initial print character for that position and move to the next template character position to the right. The Backspace key will move to the next template character position to the left and change the character at that position to the initial print character for that position. A special case is that typing Delete when the text cursor is at the rightmost end of the template string will delete the last character by shifting all other typed characters one position to the right.

Allowing Numeric Sign Characters

If the template-allows-sign property of the widget is true, then the user will be allowed to type a plus or minus character in any template character position that is to the left of all non-space typed characters.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.