path: root/fpcsrc/packages/ncurses/src/pxpic.txt

This text describes the Paradox picture input masking capabilities. It comes
from chapter 5 of the Paradox PAL Programmers Guide for Paradox 4.0. This is
what the nSEdit() function in the oCrt unit uses to mask user input when a
picture string has been set for the nEC.Picture property.

CHAPTER 5

Using pictures to format input

A PAL picture is a powerful and flexible tool for controlling what a
user can type into a field during data entry. You can use pictures to

a) shape and limit what the user can type into a field

b) make data entry easier by filling in required or default values
   automatically.

You can think of pictures as a way to define new field types by
imposing restrictions on existing ones. In effect, the Social Security
number picture in Example 5-1 defines a new type of alphanumeric
field. So would a picture of a telephone number (with or without the
area code), or a part number in which X is always the second
character. Pictures can also help users fill in default or repetitive
values during data entry. For instance, through a picture, you can
specify that the X in the part number will be filled in automatically.

Example 5-1 Using a picture to format input.

Suppose you want a user to enter Social Security numbers. Use a picture
to make sure the input has the proper format.

PICTURE = "###-##-###"

The picture fills in the hyphens automatically and ensures that the user types
the proper number of digits -- no other characters will be accepted.

When a picture is specified, the user must fill it exactly and
completely. In Example 5-1, if a user starts by typing a letter, a beep
results. If someone tries to leave the field before typing all the digits,
Paradox displays the message Incomplete field and leaves the cursor
in the field.

While a user is typing data into a picture, pressing Backspace or Del
erases characters and Ctrl-Backspace clears the field as long as the
resulting entry fills the picture. You can also design the picture to fill
in optional characters when the user presses Space.

How to define pictures

A picture is a kind of pattern. It consists of a sequence of literal
characters interlaced with any of the match characters listed in
Table 5-1.

Table 5-1  Match characters in pictures

Picture element    Description
----------------   --------------------------------------------

Match characters

#                  Accept only a digit
?                  Accept only a letter (upper- or lowercase)
&                  Accept only a letter, convert to uppercase
@                  Accept any character
!                  Accept any character, convert to uppercase
t                  Any character taken literally

Special characters

;                  Take next character literally
*                  Repetition count
[]                 Option
{}                 Grouping operators
,                  Set of alternatives
---------------------------------------------------------------
Any number, letter, or punctuation character not defined as one of the unique
match or special characters (that is, anything you can type that isn't on this
list) is taken literally.

The Social Security number in Example 5-1 was specified with the
picture ###-##-####. The # is a match character that accepts only
digits in its place. The hyphen is a literal character, meaning that it
must literally appear in the typed value (matched exactly).
Literal characters in a picture are filled in automatically unless

a) you specify otherwise (see "Inhibiting automatic fill-in" later in
   this chapter)
b) they occur at the beginning of a picture (this helps to
   accommodate blank fields)

For example, when the cursor arrives at a blank field governed by the
picture

ABC-###

the "ABC-" is not filled in automatically because it occurs at the
beginning of the picture. But as soon as the user types A or a, or
presses Space, the "ABC-" appears.

If you want to specify a literal character that happens to be a match
character, precede it with a semicolon (;). For example, here's how
you'd specify a part number that contains three letters, a hyphen, and
a number sign (#):

???-;#

If you omitted the semicolon, the picture would call for three letters,
a hyphen, and a digit. You can use the semicolon in a picture to
precede any of the characters in Table 5-1 that you want to be taken
literallyincluding the semicolon itself. Here are some other
examples:

$*#.##;@      ; price each, like $345.67@
*?;?          ; questions, adding ? to any text
###;,###      ; six-digit number with comma separating thousands,
              ; like 345.678
???;;;#       ; part number with three letters, semicolon, and
              ; number sign, like ABC;#


Special features of
pictures

The special features of pictures are described in detail in the
following sections. These spedal features are summarized in Table 5-2

Table 5-2 Special features of pictures

Operator  Name      Examples           Satisfied by
--------  --------  -----------------  ---------------------------------------
*         Repeat    *5#                Five numbers; equivalent to #####
                    *#                 Zero or more numbers
                    (*#.##), *#.##     Currency amounts, negative or
                                       positive
                    &*?                Initial capitalization of a single word
{ }       Set       *5{##}             Ten numbers or five times the set of
                                       two numbers

                    {20,40,60,75,100}W Light bulbs in different wattages
[ ]       Optional  ###-####[###[#]]   Phone number with or without a 3-
                                       or 4-digit extension
                    *[&[*?][@][ ]]     Any number of capitalized words
                                       and initials
,       Alternative RED,BLUE           Literals "RED" or "BLUE"; entering
                                       an R fills RED, a B fills BLUE
                    ###,##             2- or 3-digit number; ##,### would
                                       not work
{ }       Inhibit   ###{-)##           The hyphen is not filled in
          Fill                         automatically: the user must press
                                       Space to have the hvohen filled in
------------------------------------------------------------------------------

Repetition counts

You'll find the repetition count match character (*) useful when
specifying pictures for long fields. For example, these two pictures
are equivalent:

*25#
#########################

The match character * in the first picture is followed by a number,
which is the number of times to repeat the match character or literal
that follows. If you omit the *, the picture would mean the number 25
followed by any other digit.

To repeat a group of match characters, enclose the group in braces {}
following the number of repetitions:

*3{##:}   ; equivalent to ##:##:##:

Notice how this picture mixes literal and match characters in the
group. Each group consists of two digits to be typed by the user and
a colon to be filled in by Paradox.

Also use the grouping braces {} when you want to repeat a single
number, as in

*3{5}#   ; equivalent to 555# (three fives followed by any other digit)

Without the braces, Paradox would think you wanted *35#, 35
repetitions of "#".

Omitting the number after the *, tells Paradox to accept zero or more
repetitions of the character or group. You might use this variation
when you want the user to type at least a certain number of
characters, but perhaps more. For example, this picture in a State field

&&*&

requires at least the two-letter state abbreviation, but would also
accept a state name spelled out in full.

To use the * as a literal character in a picture, precede it with a
semicolon (;). For example,

;*###;*     ; equivalent to *###*

Optional elements

You can make part of a value optional by enclosing the
corresponding part of the picture within brackets [ ]. This means that
the user can enter data for that part of the value, but is not required
to do so. The user can accept the optional part by typing a character
that fits it or by pressing Space if the character is a literal.

Note:  When the user reaches an optional part of a value, any matching
character accepts the entire optional part. For example,

[###l ###-####

doesn't make the area code optional. Suppose the user tries to skip the
area code and types the first digit of the phone number. Since this
matches the first optional character, Paradox assumes it is the area
code and requires all 10 digits.

Similarly, the following picture won't work to specify a number with
either two or three digits:

[#]##

since the first digit typed is always understood to be the [#]. To
specify an optional number of digits, place the optional portion after
the required portion:

##[#]

Here, the first two digits typed will match the mandatory #
characters, and the third digit may or may not be added. Remember
that pictures are always scanned left to right, so the optional portion
of a repeating element should always come at the end.

Example 5-2 demonstrates the correct way to create a picture for a
telephone number with an optional area code.

Example 5-2 Options in pictures

The following picture accepts a 7-digit telephone number with an optional,
parenthesized 3-digit area code:

[(###)] ### - ####

The user can fill in this field in two ways:

a) If the first character typed is the left parenthesis or Space,
   it matches the optional part of the picture and Paradox will look for a
   3-digit area code before the 7-digit number.

b) If the first character typed is a digit, Paradox ignores the option and
   skips to the required digits. The right parenthesis (if used) and hyphen
   are filled in automatically.

Literal characters at the beginning of an optional part of a value are
never filled in automatically. For example, in the picture

#[ABC]#

the characters "ABC" are not automatically filled in after the user
types the first digit. They are filled in if the user types "A" or "a" or
presses Space. The automatic fill-in occurs only when the filled-in
characters are mandatory, or when the user explicitly elects the
option by typing the first character or pressing Space.

Optional elements can be nested, as in the following picture:

#[[#[a]]

Because the characters [ and ] are used to specify options, they must
be preceded by a semicolon (;) if you want to use them literally in a
picture.

Alternative choices

Many applications require the user to type one of several possible
choices as part or all of a data value. A part number, for example,
might consist of a three-digit number, followed by a color code of
RED, GRE, YEL, or BLU, followed by another three-digit number.
You specify a set of alternatives in a picture as a comma-separated list
of alternatives. For example, you could specify the color-coded part
numbers like this:

###RED###, ###G RE###, ###YEL###, ###BLU###

or, more succinctly,

###{RED,GRE,YEL,BLU}###

Both of these pictures have the same effect. In the second, the braces
have been used to group the alternatives.

As with bracketed options, literal characters at the beginning of an
alternative are not filled in automatically. For example, if the user
types 345 in the preceding example, the characters RED are not then
filled in. But if the user then presses Spacebar or types r, the ED is
filled in. Similarly, if the user types g, the RE is filled in, and so on.
Paradox always fills in the first matching alternative it finds; thafs
why RED is filled in when the user presses Space. To get one of the
other options, the user must type its first letter.

Example 5-3 Alternatives in a date picture

The following example lets you restrict input in a date field to dates falling
within the first week of a month:

#[#]/{1.2,3,4.5,6,7}/##[#][#]

Note the use of optional digits to permit months to have either one or two
digits and years to have two, three, or four. Again, since pictures are scanned
from left to right, the optional elements always come at the end of that part of
the picture.

The different alternatives need not be composed of literal characters;
they can be picture specifications of any kind (Example 5-3). For
example, here's another way of specifying a two- or three-digit
number:

###,##

Again, the picture ##,### wouldn't do the job, because once the first
two digits are typed, the first alternative will be selected and the
picture will be fully satisfied. If the user then types a third digit, a
beep sounds.

The following picture specifies that an alphanumeric value can either
be True or False:

True,False

Using this picture or variations on it, you can easily obtain the effect
of a logical value or create a field of type logical in a Paradox table.

As with other match characters, if you want to use a comma (,) as a
literal character in a picture, you must precede it with a semicolon (;).

Inhibiting automatic fill-in

Some users find automatic fill-in of literal characters annoying
particularly if they seldom look at the screen as they type. To inhibit
it, simply enclose the literal characters you don't want filled in within
braces I }. For example, this picture inhibits the fill-in of hyphens in
Social Security numbers:

###{-}##{-}####

When the user types the first three digits, the hyphen (-) is not filled
in. To enter it, the user can press - or Space.

Sometimes you must inhibit fill-in to get the effect you want. In the
color-coded part numbers in the previous section, suppose we had
the color code BRO in addition to RED, GRE, YEL, and BLU. Adding
BRO to the preceding picture gives

###{RED,GRE,YEL,BLU,BRO}###

Now suppose the user types three digits and then a b. Since BLU is
the first possible match (left to right), Paradox would fill in the LU
automatically. This could be wrong, since the user may have had
BRO in mind rather than BLU. To solve this problem, use either of
these pictures to inhibit automatic fill-in of the L:

###{RED,GRE,YEL,B{L}U,BRO}###

###{RED,GRE,YEL,B{LU,RO}}###

The second picture, in effect, factors the letter B out of both BLU and
BRO. This forces the user to type two characters to specify the blue or
brown color code. The (LU, RO} is a set of alternative choices that has
been nested within the larger set of choices.

Going a step further, here's how you could inhibit all of the fill-in:

###(R{E}{D},G{R}{E},Y{E}{L},B{L}{U},B{R}{0}}###

Picture examples

By using PAL's regular and special match characters, you can create
an almost endless variety of picturesin effect, new data typesfor
your applications. Here are just a few examples:

(*#.##),*#.##             ; currency amounts, using parentheses for
                          ; negative quantities
#[#][#]*{;,###}           ; positive integers with commas separating
                          ; groups of three digits
{20,40,60,75,100}W        ; light bulbs in different wattages
{A,B,C.D,E,F,G,H}[R]##-## ; tire sizes
&*?                       ; initial capitalization of a single word
&. &. &*?                 ; two initials followed by a capitalized name
                          ; of any length
*[&[*?][@][ ]]            ; any number of capitalized words or initials
{##}:{##}:{##}            ; for time