| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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:
*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.
(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.
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.
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.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |