This command is undocumented in the original VFP9 help file,
but the following documentation was found in the FoxPro for Windows 2.6 help, and may still be valid:

Creates a check box or a picture check box.

Parameters

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 in the main FoxPro window or a user-defined window. Rows are numbered from top to bottom. In FoxPro for Windows, row 0 is the row immediately under the FoxPro system menu bar. In FoxPro for Macintosh, row 0 is the row immediately under the FoxPro title bar. In FoxPro for MS-DOS, row 0 is the row the FoxPro system menu bar occupies. See SET SYSMENU for information about manipulating the system menu bar so you can place output on row 0 in FoxPro for MS-DOS.

 The first column is number 0 in the main FoxPro window or a user-defined window. Columns are numbered from left to right.

 When the check box is directed to a user-defined window, the row and column coordinates are relative to the user-defined window, not the main FoxPro window.

 In FoxPro for Windows and FoxPro for Macintosh, 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 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.

 In FoxPro for Windows and FoxPro for Macintosh, you can position the check box in a window with decimal fractions for row and column coordinates. 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 nonzero 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 field1 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 and FoxPro for Macintosh, the prompt for a check box can also be the name of a picture file. In FoxPro for Windows, the picture file can be a BMP bitmap file. In FoxPro for Macintosh, you can use a picture file of PICT type or a BMP bitmap file.

 When a check box uses a picture file for a prompt, the check box mimics the behavior of a check box with a text prompt. For example, the picture file 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 picture file 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 picture filename. If the picture file is not located in the default directory or folder, include the path to the picture file with the picture filename.

 -------------------------------
 Note 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.
 -------------------------------

 If you omit the extension for the picture file, FoxPro for Macintosh first looks for a picture file with the name you specified and a .BMP extension. If a picture file with a .BMP extension and the name you specified isn't found, FoxPro for Macintosh then looks for a file with the name you specified and a .PCT extension. If a picture file with a .PCT extension and the name you specified isn't found, FoxPro for Macintosh then looks for a picture file with the name you specified without an extension.

Picture Masks and Check Boxes
 In FoxPro for Windows and FoxPro for Macintosh, a picture check box has three states: up, down and disabled. FoxPro automatically controls the appearance of 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 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 picture file, are transparent.

 A mask is a monochrome picture file. In FoxPro for Windows, a mask is a .BMP with an .MSK extension. In FoxPro for Macintosh, a mask can be a .BMP with an .MSK extension or a PICT type file with a .PCM extension. The mask must have the same base name as the picture file and the appropriate extension. FoxPro automatically looks for a mask for a picture file in the same directory or folder where the picture file is located.

 In most cases, a mask isn't necessary. If you don't need anything in your picture to appear white and your picture file 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 picture 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 picture with a dog on a white background; the dog has 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 picture file 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 picture file appear transparent so the color of the button face shows through. Any non-white areas appear dark gray. If the button has a mask, all white areas in the mask are transparent so the color of the button face shows through, and all black areas appear dark gray.

PICTURE and FUNCTION Options N, T, 2 and 3
 Additional options can be combined with the *C specification codes in the FUNCTION or PICTURE clause to modify the behavior (N and T) and appearance (2 and 3) of check boxes.

 The 2 (two-dimensional) and 3 (three-dimensional) specification codes are only available in FoxPro for Macintosh.

 Option Description
 ------ -----------

  N Does not terminate the READ when the box is chosen. This is the default behavior.

  T Terminates the READ when the box is chosen.

  2 Creates a flat (two-dimensional) check box identical to check boxes in Macintosh dialogs. This is the default check box type in FoxPro for Macintosh.

  3 Creates a three-dimensional check box identical to check boxes in FoxPro for Macintosh dialogs.

 For example, the following clause creates a check box and doesn't cause the READ to terminate when the check box is chosen:

 ... FUNCTION '*CN ... '

 In FoxPro for Macintosh, the following clause creates a three-dimensional check box and doesn't cause the READ to terminate when the check box is chosen:

 ... FUNCTION '*CN3 ... '

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). In FoxPro for Macintosh, if KEYCOMP is set to MAC (the default), the hot key isn't highlighted or underlined; if KEYCOMP is set to DOS or WINDOWS the hot key is underlined.

 -------------------------------
 Note - 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.

 -------------------------------
 Note - Note 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 Courier font:

 @ 2,2 GET mchoice FUNCTION '*C Titles' DEFAULT 1 ;
  FONT 'Courier',16

 If you include the FONT clause but omit the font size expN1, a 10-point font is used.

 In FoxPro for Windows, if the font you specify is not available, a font with similar font characteristics is substituted.

 In FoxPro for Macintosh, if the font you specify is not available, the Chicago font is used.

 In FoxPro for MS-DOS, the FONT clause is ignored.

 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.

STYLE expC5
 In FoxPro for Windows and FoxPro for Macintosh, include the STYLE clause to specify a font style for a check box.

 The font style is specified with expC5.

 In FoxPro for Windows, if the font style you specify is not available, a font style with similar characteristics is substituted.

 In FoxPro for Macintosh, if the font you specify is not available, the normal font style is used.

 The STYLE clause is ignored in FoxPro for MS-DOS.

 Character Font Style
 --------- ----------
 
  B  Bold

  C  Condense*

  E  Extend*

  I  Italic

  N  Normal

  O  Outline

  Q  Opaque

  S  Shadow

  -  Strikeout*

  T  Transparent

  U  Underline

 * The Condense and Extend styles are only available in FoxPro for Macintosh. The Strikeout style is only available in FoxPro for Windows.

 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 are filled with the background color.

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.

 -------------------------------
 Note - If the DEFAULT clause is omitted and the memory variable memvar doesn't exist, the error message "Variable not found" appears.
 -------------------------------

 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 and FoxPro for Macintosh, 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 and FoxPro for Macintosh, 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 appears when a check box is selected. The message is centered by default on the last line of the main FoxPro window; the message location can be specified with SET MESSAGE.

 In FoxPro for Windows and FoxPro for Macintosh, the message is placed in the graphics status bar. If the graphical 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 user-defined function (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).

 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 false (.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 \ 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 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 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 SET COLOR Overview or Color Table by Color Pair.

 A color pair can also be specified with a set of six RGB (Red Green Blue) color values separated by commas. The first three color values specify the foreground color and the second three 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 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).

  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 white 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

Remarks

See Also