| Paul Pedersen 2005-12-01, 8:25 pm |
| ÖÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
º @ ... GET - Check Boxes º
ÓÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄĽ
@ <row, column>
GET <memvar> | <field>
FUNCTION <expC1> | PICTURE <expC2>
[FONT <expC3> [, <expN1>]]
[STYLE <expC4>]
[DEFAULT <expr>]
[SIZE <expN2>, <expN3>]
[ENABLE | DISABLE]
[MESSAGE <expC5>]
[VALID <expL1> | <expN4>]
[WHEN <expL2>]
[COLOR SCHEME <expN5>
| COLOR <color pair list>]
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Creates a check box or a picture check box.
Picture check boxes - FoxPro for Windows only.
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
With this variation of @ ... GET you can create a check box or a picture
check box. A check box is used to toggle between two states, such as true
(.T.) and false (.F.) or yes and no.
If you use the Screen Builder to create your data entry screens, you may not
have to use this command at all. The Screen Builder automatically generates
the commands that create check boxes and picture check boxes.
A check box is box with descriptive text to its right. The string of text,
called a prompt, indicates what the check box controls. The text of the
prompt is specified by the FUNCTION or PICTURE clause. When a condition is
true, an X is displayed. Only one check box may be created in a single @
.... GET. Issue READ or READ CYCLE to activate a check box.
You can create a picture check box in FoxPro for Windows. A .BMP (bitmap
picture) on a button replaces the check box and the check box prompt.
In FoxPro for MS-DOS, pressing the Spacebar or Enter or clicking the check
box toggles the check box from one state to the other.
In FoxPro for Windows, pressing the Spacebar or Enter or clicking the check
box toggles the check box from one state to the other if KEYCOMP is set to
DOS. If KEYCOMP is set to WINDOWS, which is the default, you can toggle the
check box state by pressing the Spacebar or clicking on the check box.
Press Enter to move to the next object.
<row, column>
Row and column are numeric expressions with values 0 or greater that
determine where the check box appears.
The first row is number 0 on the desktop, main FoxPro window or a
user-defined window. In FoxPro for MS-DOS, row 0 is the row the FoxPro
system menu bar occupies. See SET SYSMENU in this online help facility for
information about manipulating the system menu bar so you can place output
on row 0. In FoxPro for Windows, row 0 is the row immediately under the
FoxPro system menu bar. Rows are numbered from top to bottom.
The first column is number 0 on the desktop, main FoxPro window or a
user-defined window. Columns are numbered from left to right.
When a check box is placed in a user-defined window, the row and column
coordinates are relative to the user-defined window, not the desktop in
FoxPro for MS-DOS or the main FoxPro window in FoxPro for Windows.
In FoxPro for Windows, a position in the main FoxPro window or in a
user-defined window is determined by the font of the main FoxPro window or
the user-defined window. Most fonts Microsoft Windows uses can be displayed
in a wide variety of sizes, and some are proportionally spaced. A row
corresponds to the height of the current font; a column corresponds to the
average width of a letter in the current font. See the Fonts topic in this
online help facility for additional information about fonts.
To facilitate precise positioning of a check box in the main FoxPro window
or in a user-defined window, you can use decimal fractions for row and
column coordinates in FoxPro for Windows. In FoxPro for MS-DOS, decimal
fractions used for row and column coordinates are rounded to the nearest
integer value.
<memvar> | <field>
When you check or uncheck a check box, your choice is stored to a memory
variable, an array element or a field, which you specify with <memvar> or
<field>. The <memvar> or <field> must be of numeric or logical type.
When a check box is initially displayed on the screen or in a window, the
box is checked if <memvar> or <field> contains a non-zero numeric value or a
true (.T.) value. The box isn't checked if <memvar> or <field> is zero or
false (.F.).
READ or READ CYCLE activates the check box. The state of the check box
when the READ is terminated determines the value stored to the memory
variable, array element or field - 1 or .T. if checked and 0 or .F. if
unchecked.
FUNCTION <expC1> | PICTURE <expC2>
When creating a check box, you must include the FUNCTION clause, the
PICTURE clause or both. There is no advantage for any of the three methods.
The FUNCTION clause or the PICTURE clause contains the check box
specification code *C.
The FUNCTION clause character expression <expC1> must begin with *C. To
create the prompt, include a space after *C followed by the text of the
prompt. For example, this clause creates a check box with the prompt
Titles:
... FUNCTION '*C Titles' ...
The PICTURE clause character expression <expC2> uses the same syntax as the
FUNCTION clause character expression, except the PICTURE clause expression
must begin with @ followed by *C. For example, this clause creates a check
box with the prompt Titles:
... PICTURE '@*C Titles' ...
You can also include both the FUNCTION and PICTURE clauses to create a
check box. If both are included, the FUNCTION character expression <expC1>
must contain *C to create the check box. The PICTURE character expression
<expC2> must include the prompt. For example:
... FUNCTION '*C' PICTURE 'Titles' ...
The following examples illustrate the various forms of syntax you can use
to create a check box. In all the examples the check box is placed in the
second row and column. The state of the box (checked or unchecked) is
stored to the memory variable MCHOICE. Each example creates the same check
box.
FUNCTION clause only
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
STORE 1 TO mchoice
@ 2,2 GET mchoice FUNCTION '*C Titles'
READ
STORE 1 TO mchoice
STORE '*C Titles' TO mprompt
@ 2,2 GET mchoice FUNCTION mprompt
READ
PICTURE clause only
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
STORE 1 TO mchoice
@ 2,2 GET mchoice PICTURE '@*C Titles'
READ
STORE 1 TO mchoice
@ 2,2 GET mchoice PICTURE '@*C' + ' Titles'
READ
FUNCTION and PICTURE clauses
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄ
STORE 1 TO mchoice
@ 2,2 GET mchoice FUNCTION '*C' PICTURE ' Titles'
READ
Picture Check Boxes
In FoxPro for Windows, a check box can also be a .BMP (bitmap picture)
displayed on a button. A picture check box mimics the behavior of a check
box with a text prompt. The .BMP is displayed but the check box isn't
displayed. Like checking a check box, choosing the picture toggles the
value of <memvar> or <field> between .T. and .F. or 1 and 0.
To use a .BMP in a check box, add B to the check box specification code.
The FUNCTION and PICTURE clause specification codes that create a check box
are *C or @*C, respectively. To create a check box with picture prompts,
use the codes *CB and @*CB, followed by a space and the .BMP file name. If
the .BMP file is not located in the default directory, include the directory
with the .BMP file name.
Caution
The pictures aren't clipped, reduced or enlarged to fit the check box
button. Use the SIZE clause to adjust the size of the check box button to
accommodate the picture.
You can use SHOW GET to specify different .BMPs that are displayed when a
picture check box is selected, enabled or disabled. See SHOW GET in this
online help facility for further information about displaying different
..BMPs for each check box state.
Picture Masks and Check Boxes
In FoxPro for Windows, a picture check box has three states: up, down and
disabled. FoxPro automatically controls the appearance a picture check box
when it is in each of these three states, but you can override the default
appearance by using a picture mask. A mask is a monochrome .BMP file with
an .MSK extension. FoxPro automatically looks for a mask for a .BMP file in
the same directory where the .BMP file is located. The mask must have the
same base name as the .BMP file and an extension of .MSK.
A mask is used to control the transparent areas of a picture check box. By
default, the white areas are transparent. If a mask is present, the white
areas of the mask, not the .BMP, are transparent.
In most cases, a mask isn't necessary. If you don't need anything in your
picture to appear white and your .BMP has a white background, the picture
check box will appear as desired in the up, down and disabled states.
When a picture check box has a mask and is in the up or down state, any
white areas in the .BMP appear transparent, allowing the color of the button
face to show through. However, you can maintain the white color of certain
areas.
Suppose that you have a .BMP of a dog on a white background and white eyes,
and the button face is red. You want the background of the button to appear
red but you want the dog's eyes to be white, not red. Make a mask that is
the same size as the .BMP but includes only two colors, black and white.
Leave the background of the mask white but make the dog - including his
eyes - completely black. When the button is displayed, the background is
red to match the button face but the dog's eyes are white.
When a picture check box is disabled, any white areas in the .BMP appear
transparent so the color of the button face shows through. Any non-white
areas appear dark grey. If the button has a .MSK, all white areas in the
mask are transparent so the color of the button face show through, and all
black areas appear dark grey.
PICTURE and FUNCTION Options N and T
Two options can be placed after the specification code *C in the FUNCTION
or PICTURE clause to specify whether the READ is terminated when a check box
is chosen:
Option Description
ÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄ
N Do not terminate the READ when the box is chosen. This is the
default behavior.
T Terminate the READ when the box is chosen.
Check Boxes with Special Features
You can assign a hot key to the check box or disable the check box by
including special characters when defining the prompt.
Hot Keys
A hot key allows you to immediately choose or change the state of the check
box. To assign a hot key, place a backslash and a less than sign (\< )
before the desired character of the check box prompt. The hot key is a
highlighted character (FoxPro for MS-DOS) or an underlined character (FoxPro
for Windows).
HOT TIP
A hot key doesn't choose the check box if the current object is an @ ...
GET input field, a text editing region, a popup or a list.
If the current object is an @ ... GET input field or a text editing region,
pressing the hot key enters the corresponding letter in the field or the
text editing region. If the current object is a popup or a scrollable list,
pressing the hot key selects the first option in the popup or list whose
prompt begins with the letter corresponding to the hot key.
HOT TIP
In FoxPro for Windows, if the current object is an @ ... GET input field,
text editing region, popup or list and KEYCOMP is set to WINDOWS, you can
press Alt and the hot key to move to the check box and choose it. If you
create a picture check box, you cannot create a hot key for the picture
check box.
The following example creates a check box with the prompt Titles and
assigns the hot key T to it:
STORE 1 TO mchoice
@ 2,2 GET mchoice FUNCTION '*C' PICTURE ' \<Titles'
READ
Disabled Check Boxes
A disabled check box cannot be selected or chosen and is displayed in
disabled colors. To disable a check box, place two backslashes (\\) before
the check box prompt or use the DISABLE clause. The following example
disables the check box created earlier:
STORE 1 TO mchoice1, mchoice2, mchoice3
@ 2,2 GET mchoice1 FUNCTION '*C \\Titles'
@ 4,2 GET mchoice2 FUNCTION '*C Titles' DISABLE
@ 6,2 GET mchoice3 FUNCTION '*C Titles'
READ
FONT <expC3> [, <expN1>]
Include FONT to specify a font and font size for the check box prompt. The
character expression <expC3> is the name of the font, and the numeric
expression <expN1> is the font size. For example, the following command
displays the prompt in 16 point Roman font
@ 2,2 GET mchoice FUNCTION '*C Titles' DEFAULT 1 ;
FONT 'ROMAN',16
If you include the FONT clause but omit the font size <expN1>, a 10 point
font is used.
If the FONT clause is omitted and the check box is placed in the main
FoxPro window, the main FoxPro window font is used. If the FONT clause is
omitted and the check box is placed in a user-defined window, the
user-defined window font is used.
If the font you specify is not available, Windows substitutes a font with
similar font characteristics.
The FONT clause is ignored in FoxPro for MS-DOS.
STYLE <expC5>
In FoxPro for Windows, include the STYLE clause to specify a font style for
a check box. The styles that are available for a font are determined by
Windows. If the font style you specify is not available, Windows
substitutes a font style with similar characteristics.
The font style is specified with <expC5>. If the STYLE clause is omitted,
the standard font style is used.
Character Font Style
ÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄ
B Bold
I Italic
N Normal
O Outline
Q Opaque
S Shadow
- Strikeout
T Transparent
U Underline
You can include more than one character to specify a combination of font
styles. For example, the following clause specifies Bold Italic:
STYLE 'BI'
If T is included to create a transparent check box, the check box is filled
with the background color. If Q is included, the check box and the check
box prompt is filled with the background color.
The STYLE clause is ignored in FoxPro for MS-DOS.
DEFAULT <expr>
When you check or uncheck a check box, the state of the box is saved in a
memory variable, an array element or a field. If you specify a memory
variable that doesn't exist, it is automatically created and initialized if
the DEFAULT clause is included. However, an array element isn't created if
you specify an array element in a DEFAULT clause. The DEFAULT clause is
ignored if the memory variable already exists or you specify a field.
Caution
If the DEFAULT clause is omitted and the memory variable <memvar> doesn't
exist, the error message "Variable not found" is displayed.
The DEFAULT expression <expr> determines the type of memory variable
created and its initial value. It must be a numeric or logical expression.
Here are examples of DEFAULT clauses for check boxes:
@ 2,2 GET mchoice FUNCTION '*C Titles' DEFAULT .T.
READ
STORE .T. TO button
@ 2,2 GET mchoice FUNCTION '*C Titles' DEFAULT button
READ
SIZE <expN2>, <expN3>
The numeric expression <expN2> specifies the height of a check box. For
check boxes in FoxPro for MS-DOS, this expression is ignored because a check
box is always one line high. However, you must include <expN2> if you
include <expN3> to specify the width of the prompt.
In FoxPro for Windows, you can specify a height for the check box. If
<expN2> is 1, the focus rectangle around the check box prompt will be
clipped. In this case, include a larger value for <expN2>.
By default, the width of a check box is determined by the length of the
prompt text. You can use <expN3> to make the check box prompt wider than
the default. The numeric expression <expN3> specifies the width (in
columns) of a check box.
In FoxPro for Windows, the check box font determines the size of the check
box. The check box font is specified with the FONT clause. If the FONT
clause is omitted, the check box uses the font of its parent window (the
main FoxPro window or a user-defined window).
ENABLE | DISABLE
By default, a check box is enabled when READ is issued. You can prevent a
check box from being activated when READ is issued by including DISABLE. A
disabled check box cannot be selected and is displayed in disabled colors.
Use SHOW GET ENABLE to enable a disabled check box.
MESSAGE <expC5>
The MESSAGE clause character expression <expC5> is displayed when a check
box is selected. The message is centered by default on the last line of the
desktop in FoxPro for MS-DOS; the message location can be specified with SET
MESSAGE.
In FoxPro for Windows, the message is placed in the Windows-style status
bar. If the Windows-style status bar has been turned off with SET STATUS
BAR OFF, the message is centered on the last line of the main FoxPro window.
VALID <expL1> | <expN4>
You can include an optional VALID expression <expL1> or <expN4> that is
evaluated when a check box is chosen (checked or unchecked). That is, VALID
isn't evaluated when you select (move to) the check box, but when you
actually choose the check box.
Typically, <expL1> or <expN4> is a user-defined function. With
user-defined functions you can select, enable or disable other objects, open
a Browse window, open another data entry screen or move to a new record.
CLEAR READ can be included in a user-defined function to terminate the READ.
<expL1>
When a logical value <expL1> is returned to the VALID clause, the logical
value is ignored and the check box remains the active control. However, you
can specify a UDF that returns a logical value to the VALID clause and
activates another object.
The following example demonstrates how a VALID clause UDF is executed when
a check box is chosen. The check box remains the current control when the
VALID clause UDF is executed because a logical false (.F.) is returned by
the UDF.
CLEAR
STORE 1 TO mchoice1, mchoice2, mchoice3
@ 2,2 GET mchoice2
@ 4,2 GET mchoice1 FUNCTION '*C \<Titles' ;
VALID showmes() ;
MESSAGE 'Execute the VALID. ' + ;
'Select this check box using {Spacebar}.'
@ 6,2 GET mchoice3
READ CYCLE && Press {Esc} to exit the READ
FUNCTION showmes
WAIT WINDOW NOWAIT 'The VALID clause was executed.'
RETURN .F.
<expN4>
A VALID clause that includes a numeric expression <expN4> is used to
specify which object is activated after a check box is chosen. Objects are
@ ... GET input fields, check boxes, lists, popups, spinners, text editing
regions and each individual button in a set of push, radio and invisible
buttons.
The numeric expression has one of three effects:
When <expN4> is 0, the check box remains the active control.
When <expN4> is positive, <expN4> specifies the number of objects to
advance. For example, when the check box is selected and VALID returns 1,
the next object is activated. If <expN4> is greater than the number of
objects remaining, the READ is terminated (unless READ CYCLE is issued to
activate the objects).
When <expN4> is negative, <expN4> specifies the number of objects to move
back. For example, when the check box is selected and VALID returns -1, the
previous object is activated. If <expN4> moves back past the first object,
the READ is terminated (unless READ CYCLE is issued to activate the
objects).
ÖÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
º Example º
ÓÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄĽ
The following example demonstrates how a VALID clause UDF can activate
another object by returning a numeric value. When the VALID clause UDF is
executed, the UDF returns 2. The second object after the check box is
activated. Since READ CYCLE was issued, the READ isn't terminated even
though there are less than two objects remaining.
CLEAR
STORE 1 TO mchoice1, mchoice2
STORE 0 TO m.choice3
@ 2,2 GET mchoice1
@ 4,2 GET mchoice2
@ 6,2 GET m.choice3 FUNCTION '*C \<Titles' ;
VALID showmes() ;
MESSAGE 'Execute the VALID. ' + ;
'Select this check box using {Spacebar}.'
READ CYCLE && Press {Esc} to exit the READ
FUNCTION showmes
WAIT WINDOW NOWAIT 'The VALID clause was executed.'
RETURN 2
WHEN <expL2>
The optional WHEN clause allows or prohibits selection of a check box based
on the logical value of <expL2>, which must evaluate to a logical true (.T.)
before a check box can be selected. If <expL2> evaluates to a logical false
(.F.), the check box cannot be selected and is skipped over if placed
between other objects.
In the following example, the check box WHEN clause returns a logical
(.F.). The check box is skipped even though it isn't disabled.
CLEAR
STORE 1 TO mchoice1, mchoice2
STORE 0 TO mchoice3
@ 2,2 GET mchoice1
@ 4,2 GET mchoice2 FUNCTION '*C \<Titles' ;
WHEN showmes()
@ 6,2 GET mchoice3
READ CYCLE && Press {Esc} to exit the READ
FUNCTION showmes
WAIT WINDOW NOWAIT 'The WHEN clause was executed.'
RETURN .F.
COLOR SCHEME <expN5>
| COLOR <color pair list>
If you do not include a COLOR clause, check box colors are determined by
the color scheme for the desktop or the main FoxPro window; if a check box
is placed in a user-defined window, the window's color scheme determines the
check box colors.
The color of a check box can be specified by including the number of an
existing color scheme in the COLOR SCHEME clause or a set of color pairs in
the COLOR clause.
A color scheme is a set of 10 predefined color pairs. The color pairs in a
color scheme can be changed with SET COLOR OF SCHEME. In FoxPro for MS-DOS
the color pairs in a color scheme can also be changed in the Color Picker.
A color pair is a set of two letters separated by a forward slash. The
first color letter specifies the foreground color and the second letter
specifies the background color.
For example, this color pair specifies a red foreground on a white
background:
R/W
For a list of colors and their corresponding color letters, see the SET
COLOR commands or the Color Table by Color Pair topic in this online help
facility.
A color pair can also be specified with a set of 6 RGB (Red Green Blue)
color values separated by commas. The first 3 color values specify the
foreground color and the second 3 color values specify the background color.
The color values can range from 0 through 255.
The R/W color pair in the example above can also be specified with this RGB
color pair:
RGB(255,0,0,255,255,
255)
Only color pairs 5, 6, 7, 9 and 10 in a color scheme or color pair list
affect the check box colors. The color of picture check boxes is controlled
by Windows.
Color Pair Check Box
Number Attribute
ÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄ
5 Message
6 Selected check box prompt - FoxPro for MS-DOS only
7 Hot keys - FoxPro for MS-DOS only
9 Enabled check box prompt
10 Disabled check box prompt
The following example shows how to override the color scheme of the desktop
or main FoxPro window with another predefined color scheme:
ACTIVATE SCREEN
STORE 1 TO mchoice
@ 2,2 GET mchoice FUNCTION '*C Titles' COLOR SCHEME 4
READ
The following example creates check boxes with the prompt Titles, the hot
key T and the following color characteristics:
A selected box is shown with a bright white prompt on a blue background
(W+/B). In FoxPro for Windows, a focus rectangle is used to indicate the
current object.
Hot key characters are shown in red on a blue background (R/B) in FoxPro
for MS-DOS. In FoxPro for Windows, the hot key character is underlined.
An enabled check box is shown with a yellow prompt on a blue background
(GR+/B).
A disabled check box is shown with a gray prompt on a blue background
(W/B).
When you skip a color pair, you must include a comma where the color pair
is omitted.
Here are the commands:
CLEAR
SET COLOR TO W/B
STORE 1 TO mchoice
@ 2,2 GET mchoice FUNCTION '*C \<Titles';
COLOR ,,,,,W+/B,R/B,,GR+/B,W/B
@ 4,2 GET mchoice FUNCTION '*C \\Titles';
COLOR ,,,,,W+/B,R/B,,GR+/B,W/B
@ 6,2 GET mchoice FUNCTION '*C \<Titles';
COLOR ,,,,,W+/B,R/B,,GR+/B,W/B
READ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
See Also: Fonts, @ ... SAY, @ ... GET, Controls, _CUROBJ, OBJNUM(),
READ, SET KEYCOMP, SHOW GET, USER-DEFINED FUNCTIONS (UDFs)
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
|