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 set of push buttons or picture push buttons.

Parameters

row, column
 Row and column are numeric expressions with values of 0 or greater that determine where the first button in a set of push buttons 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 first button in a set of push buttons 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 first button in a set of push buttons 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 choose a push button, your choice is stored to the memory variable or array element memvar or to the field field. memvar or field must be of numeric or character type.

 If memvar or field is of numeric type, a number corresponding to the push button choice is stored to the memory variable, array element or field specified with memvar or field. For example, if you create four push buttons and choose the third button, 3 is stored. If memvar or field is of character type, the prompt of the push button you choose is stored to the memory variable, array element or field specified with memvar or field.

FUNCTION expC1 | PICTURE expC2
 When creating push buttons, you must include the FUNCTION clause, the PICTURE clause or both. There is no advantage to any of the three methods. The FUNCTION or PICTURE clause contains the push button specification code, an asterisk (*), and the text for the individual push button prompts.

 The FUNCTION character expression expC1 must begin with *. To create the push button prompts, include a space after the asterisk followed by a list of the prompts separated by semicolons. One button is created for each prompt. For example, the following FUNCTION clause creates push buttons with the prompts OK and Cancel:

 ... FUNCTION '* OK;Cancel' SIZE 1, 8 ...

 The PICTURE character expression expC2 uses the same syntax as the FUNCTION character expression except the PICTURE character expression must begin with @ followed by an asterisk (*). For example, the following PICTURE clause creates push buttons with the prompts OK and Cancel:

 .. PICTURE '@* OK;Cancel' SIZE 1, 8 ...

 You can also include both the FUNCTION and PICTURE clauses to create push buttons. If both are included, the FUNCTION character expression expC1 must contain * to create the push buttons followed by a space and the push button prompts. The PICTURE character expression expC2 can include prompts to create additional push buttons.

 The following examples illustrate the various forms of syntax you can use to create push buttons. Two push buttons are created: OK and Cancel. The first button (OK) is placed in the second row and second column. A number corresponding to the button chosen is stored to the memory variable MCHOICE.

 FUNCTION clause only:

 STORE 1 TO mchoice
 @ 2,2 GET mchoice FUNCTION '* OK;Cancel' SIZE 1, 8
 READ

 STORE 1 TO mchoice
 STORE '* OK;Cancel' TO mprompts
 @ 2,2 GET mchoice FUNCTION mprompts SIZE 1, 8
 READ

 PICTURE clause only:

 STORE 1 TO mchoice
 @ 2,2 GET mchoice PICTURE '@* OK;Cancel' SIZE 1, 8
 READ

 STORE 1 TO mchoice
 @ 2,2 GET mchoice PICTURE '@*' + ' OK;Cancel' SIZE 1, 8
 READ

 FUNCTION and PICTURE clauses:

 STORE 1 TO mchoice
 @ 2,2 GET mchoice FUNCTION '*' ;
  PICTURE ' OK;Cancel' SIZE 1, 8
 READ

Push Buttons with Picture Prompts
 In FoxPro for Windows and FoxPro for Macintosh, the prompt for a push button can also be the name of a picture file. In FoxPro for Windows, the picture file can be a bitmap file with a .BMP extension. In FoxPro for Macintosh, you can use a picture file of PICT type or a .BMP bitmap file.

 When a push button uses a picture file for a prompt, the push button mimics the behavior of a push button with a text prompt. For example, the picture file appears on a button but the push button isn't displayed. Like choosing a push button, choosing the picture prompt stores the push button's value to memvar or field.

 To use a picture file in a push button, add B to the push button specification code. The FUNCTION and PICTURE clause specification codes that create a push button are * and @*, respectively. To create a push button with picture prompts, use the codes *B and @*B, 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 push button. Use the SIZE clause to adjust the size of the push buttons to accommodate the pictures.
 -------------------------------
 
 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 Push Buttons
 In FoxPro for Windows and FoxPro for Macintosh, a picture push button has three states: up, down and disabled. FoxPro automatically controls the appearance of a picture push button 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 push button. 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 or your picture file has a white background, the picture push button will appear as desired in the up, down and disabled states.

 When a picture push button has a mask and is in the up or down state, any white areas in the picture file 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 file 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 appears, the background is red to match the button face but the dog's eyes are white.

 When a picture push button 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, H, V, 2 and 3
 Additional options can be combined with the * specification code to modify the behavior (N and T) and appearance (H, V, 2 and 3) of push buttons.

 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 a push button is chosen.

  T Terminates the READ when a push button is chosen. This is the default behavior.

  H Position the push buttons in a horizontal row.

  V Position the push buttons in a vertical column. This is the default orientation.

  2 Creates flat (two-dimensional) black-and-white push buttons identical to push buttons in Macintosh dialogs.

  3 Creates three-dimensional push buttons identical to push buttons in FoxPro for Macintosh dialogs. This is the default push button type in FoxPro for Macintosh.

 You can combine the T or N option with the H, V and 2 or 3 options. For example, the following clause creates a horizontal row of buttons and doesn't cause the READ to terminate when one of the buttons is chosen:

 ... FUNCTION '*NH ... '

 In FoxPro for Macintosh, the following clause creates a horizontal row of two-dimensional buttons and doesn't cause the READ to terminate when one of the buttons is chosen:

 ... FUNCTION '*NH2 ... '

Push Buttons with Special Features
 You can assign a hot key to a button, disable a button, or create a default or escape button. To assign these special features to a push button, you must include special characters when defining the prompt. The special characters are removed when the prompt is stored to memvar or field.

Hot Keys
 In FoxPro for MS-DOS, a hot key is a highlighted letter in the push button prompt that you can type to immediately choose a push button. Pressing the hot key selects the button and chooses it. To assign a hot key, place a backslash and a less-than sign (\<) before the desired character of the push button prompt.

 A hot key doesn't choose the push button if the current object is a GET field, a text-editing region, a pop-up or a list.

 If the current object is an @ ... GET input field or a text-editing region, pressing the hot key enters the character in the field or the text-editing region. If the current object is a popup or a list, pressing the hot key selects the first option on the popup or list whose prompt begins with the hot key character.

 In FoxPro for Windows, a hot key is an underlined letter in the push button prompt that you can type to immediately choose the button. If the current object is an @ ... GET input field, a text-editing region, a popup or a list and KEYCOMP is set to WINDOWS, you can press the Alt key and the hot key to choose the push button.

 In FoxPro for Macintosh, if KEYCOMP is set to MAC (the default), hot keys aren't highlighted or underlined. If KEYCOMP is set to DOS or WINDOWS, hot keys are underlined.

 The following example creates the OK and Cancel buttons with hot keys O and C, respectively:

 STORE 1 TO mchoice
 @ 2,8 GET mchoice FUNCTION '* \<OK;\<Cancel'
 READ

Disabled Push Buttons
 You can disable a push button so it can't be selected or chosen. Disabled push buttons are shown in disabled colors. To disable a single push button, place two backslashes (\\) before the button's prompt. To disable a set of push buttons, include the DISABLE keyword.

 The OK push button is disabled in the following example:

 STORE 1 TO mchoice
 @ 2,2 GET mchoice FUNCTION '* \\OK;Cancel'
 READ

Default Push Buttons
 A default push button is typically used to exit a data-entry screen, dialog or routine and accept any changes made in the screen, dialog or routine. To create a default push button, place a backslash and an exclamation point (\!) before the push button's prompt.

 The following example specifies the OK button as the default push button:

 STORE 1 TO mchoice
 @ 2,2 GET mchoice FUNCTION '* \!OK;Cancel'
 READ

 In FoxPro for MS-DOS, the default push button is enclosed in double angle brackets to distinguish it from other push buttons. The default push button is automatically chosen when you press Ctrl+Enter or Ctrl+W. You can specify only one default push button for each READ.

 In FoxPro for Windows, the default push button is surrounded by a thick border. Press Enter, Ctrl+Enter or Ctrl+W to choose the default push button. The KEYCOMP setting determines the behavior of default push buttons in FoxPro for Windows in the following ways:

  If you SET KEYCOMP TO DOS, the behavior of the default push button is the same as the behavior of a default push button in FoxPro for MS-DOS.

  If you SET KEYCOMP TO WINDOWS, the default push button changes as you move between buttons. The push button specified with \! is the default button when objects besides push buttons are active. When a push button is active, it becomes the default push button.

 In FoxPro for Macintosh, the default push button is surrounded by a thick border. The KEYCOMP setting determines the behavior of default push buttons in FoxPro for Macintosh in the following ways:

  If you SET KEYCOMP TO DOS, the default push button is always the same and is chosen by pressing Ctrl+Enter.

  If you SET KEYCOMP TO WINDOWS, the default button in a dialog is surrounded by a bold border and is always the same. It is chosen by pressing Enter or Ctrl+Enter. However, pressing Enter when a text editing region is the current control moves the cursor to the next line in the text editing region. In text editing regions, press Ctrl+Enter to chose the default button.

  If you SET KEYCOMP TO MAC, the default button in a dialog is surrounded by a bolder border and is always the same. It is chosen by pressing Enter. However, pressing Enter when a text editing region is the current control moves the cursor to the next line in the text editing region. In text editing regions, press Ctrl+Enter to chose the default button.

Escape Push Buttons
 An escape push button is automatically chosen when you press the Esc key. An escape button is typically used to exit a data-entry screen, dialog or routine and discard any changes made in the screen, dialog or routine. You can specify only one escape push button for each READ.

 In the absence of an escape push button, pressing Esc when editing an @ ... GET input field ends the editing and restores the original value to the field. If the field has a VALID procedure, the procedure isn't executed. When an escape push button is present, pressing Esc saves the contents of the current @ ... GET input field contents and executes the VALID procedure.

 To create an escape push button, place a backslash and a question mark (\?) before the push button's prompt.

 The following example specifies the Cancel push button as the escape push button:

 STORE 1 TO mchoice
 @ 2,2 GET mchoice FUNCTION '* OK;\?Cancel'
 READ

Push Buttons with Combined Characteristics  
 You can create a push button with more than one special feature. In the following example, the OK button is the default button and is assigned O as its hot key character. The Cancel button is the escape button and is assigned C as its hot key character. The hot key designators immediately precede the desired hot key character.

 STORE 1 TO mchoice
 @ 2, 2 GET mchoice FUNCTION '* \!\<OK;\?\<Cancel'
 READ

FONT expC3 [, expN1]
 The character expression expC3 is the name of the font, and the numeric expression expN1 is the font size. For example, the following clause can be used to display the push button prompts in 16-point Courier font:

 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 push buttons are placed in the main FoxPro window, the main FoxPro window font is used. If the FONT clause is omitted and the push buttons are placed in a user-defined window, the user-defined window font is used.

STYLE expC4
 In FoxPro for Windows and FoxPro for Macintosh, include the STYLE clause to specify a font style for the push button prompts. If the font style you specify is not available, a font style with similar characteristics is substituted.

 The font style is specified with expC4. If the STYLE clause is omitted, the normal font style is used.

 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'

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

DEFAULT expr
 When you choose a push button, your choice is saved in the memory variable, array element or field you specify. If you specify a memory variable that doesn't exist, it is automatically created and initialized if you include DEFAULT. 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 isn't included and the memory variable you specify 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. expr must be of numeric or character type. The following are examples of DEFAULT clauses for push buttons:

 @ 2,2 GET mchoice FUNCTION '* OK;Cancel' DEFAULT 'OK'
 READ

 @ 2,2 GET mchoice FUNCTION '* OK;Cancel' DEFAULT 2
 READ

 STORE 'OK' TO button
 @ 2,2 GET mchoice FUNCTION '* OK;CANCEL' DEFAULT button
 READ

SIZE expN2, expN3 [, expN4]
 The numeric expression expN2 specifies the height in rows of the push buttons. In FoxPro for MS-DOS, a push button is always one line high, so the numeric expression expN2 is ignored.

 By default, the width of each individual button is determined by the length of the push button prompt text. The numeric expression expN3 specifies the width (in columns) of each push button. A push button will never be sized smaller than its prompt.

 By default, no rows are placed between vertical buttons and a single column is placed between horizontal buttons. The spacing between push buttons is specified with expN4. If you create vertical push buttons, expN4 specifies the number of rows between the buttons. If you create horizontal buttons, expN4 specifies the number of columns between the buttons.

 In FoxPro for Windows and FoxPro for Macintosh, the push button font determines the size of the push buttons. The push button font is specified with the FONT clause. If the FONT clause is omitted, the push buttons use the font of the parent window (the main FoxPro window or a user-defined window).

 The following example demonstrates how the SIZE clause controls the button spacing:

 CLEAR
 @ 2,2 GET mchoice FUNCTION '* OK;Cancel' ;
  DEFAULT 1 SIZE 2, 10, 1
 @ 2,16 GET mchoice FUNCTION '* OK;Cancel' ;
  DEFAULT 1 SIZE 2, 10, 2
 READ

 ENABLE | DISABLE

 Push buttons by default are enabled when READ or READ CYCLE is issued. You can prevent a set of buttons from being selected when READ or READ CYCLE is issued by including DISABLE.

 Disabled push buttons cannot be selected and are displayed in the disabled colors. To disable individual push buttons instead of the entire set, see "Disabled Push Buttons" earlier in this section. Use SHOW GET ENABLE to enable a set of disabled push buttons.

MESSAGE expC5
 The MESSAGE clause character expression expC5 appears when a push button is selected. In FoxPro for MS-DOS, the message is centered by default on the last line of the main FoxPro window. The message location can be changed with SET MESSAGE.

 In FoxPro for Windows and FoxPro for Macintosh, the message is placed in the graphics-based status bar. If the graphics-based status bar has been turned off with SET STATUS BAR OFF, the message is placed on the last line of the main FoxPro window.

VALID expL1 | expN5
 You can include an optional VALID expression expL1 or expN5 that is evaluated when a push button is chosen. That is, VALID isn't evaluated when you select (move to) a button, but when you actually choose a button by pressing Enter or Spacebar or clicking the button.

 Typically, expL1 or expN5 is a user-defined function (UDF). With a user-defined function 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 the user-defined function to terminate the READ.

 expL1
  When a logical value is returned to the VALID clause, the logical value is ignored and the push buttons remain the active control. However, you can specify a UDF that returns a logical value to the VALID clause and activates another object.

 expN5
  A VALID clause that includes a numeric expression is used to specify which object is activated after a push button 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 expression expN5 has one of three effects:

  When expN5 = 0, the push button you choose remains the active button.

  When expN5 is positive, expN5 indicates the number of objects to advance. For example, when the last button in a set of push buttons is selected and VALID returns 1, the next object is activated. If expN5 is greater than the number of objects remaining, the READ is terminated (unless READ CYCLE is issued to activate the objects).

  When expN5 is negative, expN5 indicates the number of objects to move back. For example, when the first button in a set of push buttons is selected and VALID returns -1, the previous object is activated. If expN5 moves back past the first object, the READ is terminated (unless READ CYCLE is issued to activate the objects).

 The following is an example of what you can do with a user-defined function. Five buttons are displayed vertically. The button choices are used to position the record pointer. The N option is included so the READ isn't terminated when you choose a button. When you choose a button, the user-defined function GOREC is executed.

 CLOSE DATABASES
 USE customer

 SET TALK OFF
 DEFINE WINDOW one FROM 3,5 TO 18,20 FLOAT DOUBLE COLOR SCHEME 5
 ACTIVATE WINDOW one
 @ 1,2 GET mchoice FUNCTION '*NV Next;Prior;Top;Bottom;Quit';
  SIZE 2, 10, 1 VALID GOREC() DEFAULT 1
 READ CYCLE
 CLEAR WINDOW

 PROCEDURE gorec
 DO CASE
  CASE mchoice = 1
   SKIP
   IF EOF()
    SKIP -1
   ENDIF
  CASE mchoice = 2
   SKIP -1
   IF BOF()
     SKIP
   ENDIF
  CASE mchoice = 3
   GO TOP
  CASE mchoice = 4
   GO BOTTOM
  CASE mchoice = 5
   CLEAR READ
 ENDCASE
 @ 12,6 SAY ALLTRIM(STR(RECNO()))
 RETURN

WHEN expL2
 The WHEN clause allows or prohibits selection of a set of push buttons based on the logical value of expL2, which must evaluate to a logical true (.T.) before the push buttons can be selected. If expL2 evaluates to a logical false (.F.), the push buttons cannot be selected and are skipped over if placed between other objects.

COLOR SCHEME expN6 | COLOR color pair list
 If you do not include a COLOR clause, push button colors are determined by the color scheme for the main FoxPro window; if push buttons are placed in a user-defined window, the window's color scheme determines the push button colors.

 The colors of push buttons 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)

 In FoxPro for Windows and FoxPro for Macintosh, the COLOR clause does not affect the color of push buttons. Only the message color (if the message is not displayed in the status bar) is affected by the COLOR clause.

 The following table lists the color pairs and what each color pair in the list controls.

 Color Pair  Push Button
  Number   Attribute
 ----------  -----------

  5   Message

  6   Selected button prompt - FoxPro for MS-DOS only

  7   Hot keys - FoxPro for MS-DOS only

  9   Enabled button prompt - FoxPro for MS-DOS only

  10   Disabled button prompt - FoxPro for MS-DOS only

 The following example creates OK and Cancel push buttons with the hot keys O and C respectively. In addition, the buttons have the following color characteristics:

  The selected button 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).

  Enabled buttons are shown with a yellow prompt on a blue background (GR+/B).

  Disabled buttons are 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:

 STORE 1 TO mchoice
 @ 2,2 GET mchoice FUNCTION '* \<OK;\<CANCEL;\\DISABLED';
  COLOR ,,,,,W+/B,R/B,,GR+/B,W/B
 READ

Remarks

See Also