class maskEdit

superclass(es) edit
subclass(es) -
description The maskEdit class is a simple single line editor class that can be programmed to accept only certain characters, like numbers, at specified positions.

pl_img41.gif (1823 bytes)
see also panel - editControl - edit

tasks

Creating the edit control and setting options like the justification of the text is done by methods of the classes editControl and edit. The panel class has two methods that make it easier to create a masked edit control.

The maskEdit class extends the super class edit with methods specific for masking the input of the user. The mask is a string that specifies which characters may be entered by the user at positions, the meaning of the control characters in the mask string are:

N a numeric character is required
n a numeric character is required or the space character is allowed
Z a numeric character is required and if the control does not have the focus then a '0' character is displayed.
A an alphanumeric character is required (a number or a letter)
a an alphanumeric character is required or the space character
C a letter character is required (a number is not allowed)
c a letter character is required or the space character
* a numeric character or the plus character (+) or the negative sign character (-)
U a letter character is required and converted to an uppercase character
u a letter character (always converted to uppercase) is required or a space character
L a letter character is required and converted to a lowercase character
l a letter character (always converted to lowercase) is required or a space character
\ this character is used to indicate a literal character that must appear in the text of the edit control. for instance, if a mask contains \d then the 'd' character appears in the text of the edit control
\{} the allowed characters is specified by a set, between the '{' and '}' character more than one character can be specified and the user can only press any of the characters from the set. for instance, if the mask contains \{abA} then the user can only enter the lowercase 'a' or 'b' or the uppercase 'A' character

 

Mask string Empty maskEdit Filled maskEdit
NNNN\ CC pl_img42.gif (1799 bytes) pl_img43.gif (1868 bytes)
*NN\,N pl_img44.gif (1800 bytes) pl_img45.gif (1832 bytes)
NN\\NN\\NN pl_img46.gif (1825 bytes) pl_img47.gif (1869 bytes)
N\{aW!}N pl_img48.gif (1796 bytes) pl_img49.gif (1842 bytes)

The mask string can be retrieved and set by the methods mask/1 and putMask/2. The current entered text without the space characters but with the literal characters inserted by the mask can be retrieved by calling the method textWithoutMask/1 and textWithoutMask/4. The text without the empty characters and the literal characters inserted by the mask can be retrieved by calling userText/1. The character used if the user may enter a space character can be retrieved and set by the methods whitespaceChar/1 and putWhitespaceChar/1.
To determine if a character was inserted by the user or was a literal character the methods isLiteralChar/2 can be called.

Since Trinc-Prolog R3B is the default behavior that a maskEdit does not display empty mask characters if it does not have the keyboard focus. A maskEdit control has the keyboard focus if the blinking caret is visible inside a maskEdit control. This new behavior can be turned off by calling the method putAlwaysDisplayMask/1 with the value true.

methods

mask(?OutputString)

func Return the mask string of the control.
pre TRUE
post The mask string was assigned to the variable OutputString.

putMask(+String, ?Output)

func Assign a mask string to the control.
pre The variable String must contain a string.
post If the mask string was successfully stored then was true unified with the value of Output, else was false assigned.

textWithoutMask(?OutputString)

func Create a string that contains the characters entered by the user and all of the literal characters as specified in the mask string of the control. The empty characters visible are not included.
For the masked edit with the text entered:
pl_img66.gif (1869 bytes)
and the mask 'NN\\NN\\NN', this method returns the string '55\5\5'.
pre TRUE
post The characters entered by the user and the literal characters inserted by the mask string were copied to the OutputString variable.

textWithoutMask(+IncludeLiteral, +IncludeEmpty, +TranslateZToZero, ?OutputString)

func Create a string that contains the characters entered by the user. The first three parameters determine which characters are or are not included in the result string. If the value of the parameter IncludeLiteral is true then are literal characters included in the result string, else not. If true is the value of IncludeEmpty then are empty characters included, else not. If empty characters are included then TranslateZToZero determines if the empty characters that correspond to 'Z' characters in the mask are translated to zero ('0') characters or not.

Example: if the values of the first three parameters is true and the mask is 'ZZ\\ZZ\\NN' and the masked edit contains the text:
pl_img66.gif (1869 bytes)
then this method returns the string '55\05\5'.
pre The values of the parameters IncludeLiteral, IncludeEmpty and TranslateZToZero must be boolean values.
post The characters entered by the user and the literal characters inserted by the mask string were copied to the OutputString variable.

userText(?OutputString)

func Create a string that contains only the characters entered by the user and none of the literal characters or empty characters.
For the masked edit with the text entered: pl_img66.gif (1869 bytes) and the mask 'NN\\NN\\NN', this method returns the string '5555'.
pre TRUE
post The characters entered by the user were copied to the OutputString variable.

whitespaceChar(?OutputString)

func Return the space character used by the masked edit control.
pre TRUE
post The whitespace character used was assigned to the OutputString variable.

putWhitespaceChar(+String)

func Assign a character to be used as the space character of the masked edit control.
pre The variable string must contain a string with at least a single character.
post The whitespace character was assigned to the edit control.

isLiteralChar(+Pos, ?Output)

func Determine if the character at the position Pos was entered by the user or inserted because of a literal character in the mask string. The position of the first character is 0.
pre The variable Pos must contain an integer value.
post If the character at position Pos is a literal character of the mask string then true was assigned to Output, else false was assigned to Output.

findCharInText(+Pos, ?Output, ?OutputString, ?Literal, ?SetChar)

func Get the character from the text of the masked edit control at the position Pos.
pre The variable Pos must contain an integer value.
post If the character was found then true was assigned to Output, the character was assigned to the variable OutputString. If the character was not found then no value was assigned to OutputString. If the character at position Pos is a literal character of the mask string then true was assigned to Literal, else false was assigned to Literal. If the character was found and was part of a set (for instance: \{abcdef}) then true was assigned to SetChar, else was false assigned.

findCharInMask(+Pos, ?Output, ?OutputString)

func Get the character from the mask of the masked edit control at the position Pos.
pre The variable Pos must contain an integer value.
post If the character was found then true was assigned to Output, the character was assigned to the variable OutputString. If the character was not found then no value was assigned to OutputString.

findCharInMask(+Pos, ?Output, ?OutputString, ?Literal, ?SetChar)

func Get the character from the mask of the masked edit control at the position Pos.
pre The variable Pos must contain an integer value.
post If the character was found then true was assigned to Output, the character was assigned to the variable OutputString. If the character was not found then no value was assigned to OutputString. If the character at position Pos is a literal character of the mask string then true was assigned to Literal, else false was assigned to Literal. If the character was found and was part of a set (for instance: \{abcdef}) then true was assigned to SetChar, else was false assigned.

putAlwaysDisplayMask(+YesNo)

func Determine if empty mask characters are visible when the control does not have the focus. The current version (since Trinc-Prolog R3B) of this control does not display the mask when it does not have the keyboard focus. To restore the old behavior of the maskEdit control call this method with the parameter value true.
pre The variable YesNo must contain a boolean value.
post If the value of the parameter was true then are the mask characters always visible, else only when the control has the keyboard focus.

checkAlwaysDisplayMask(?Output)

func Check if empty mask characters are visible when the control does not have the focus. The default behavior since Trinc-Prolog R3B is the default behavior to not display mask characters es not display the mask when it does not have the keyboard focus.
pre The variable YesNo must contain a boolean value.
post If the value of the parameter was true then are the mask characters always visible, else only when the control has the keyboard focus.