Click above to get retro games delivered to your door ever month!

 @...GET PUSHBUTTON
 Create a new push button Get object and display it to the screen
------------------------------------------------------------------------------
 Syntax

     @ <nRow>, <nCol>
        GET <lVar>
        PUSHBUTTON
           [CAPTION<cCaption>]
           [MESSAGE <cMessage>]
           [WHEN <lPreExpression>]
           [VALID <lPostExpression>]
           [COLOR <cColorString>]
           [FOCUS <fblock>
           [STATE <bBlock>]
           [STYLE <cStyle>]
           [SEND <msg>]
           [GUISEND <guimsg>]
           [SIZE X <nSizeX> Y <nSizeY>]
           [CAPOFF X <nCapXOff> Y <nCapYOff>]
           [BITMAP <cBitmap>]
           [BMPOFF X <nBmpXOff> Y <nBmpYOff>]

 Arguments

     <nRow> and <nCol> specify the row and column coordinates for the
     push button and its caption.  Output which extends beyond the visible
     extent of the display is clipped and does not appear.

     GET <lVar> specifies the name of the variable associated with the
     GET.  <lVar> may contain a value of any type, but upon return from the
     READ, will always contain logical false (.F.).  The purpose of <lVar> is
     to provide a place holder in the GetList for the push button.

     CAPTION <cCaption> specifies a character string that concisely
     describes the GET on the screen.  caption differs from the SAY argument
     in two ways.  The first is that the caption is displayed each time the
     GET is shown on the screen.  The other difference is that the caption,
     along with its screen position, is maintained within the Get object.
     This allows the GET to receive input when the mouse's left button is
     clicked and its cursor is on the caption.  By default, the caption
     appears within the push button's border.  Use the Get object's capRow or
     capCol variable to change the screen position of the caption.

     When present, the & character specifies that the character
     immediately following it in the caption is the push button's accelerator
     key. The accelerator key provides a quick and convenient mechanism for
     the user to move input focus from one data input control to the push
     button.  The case of an accelerator key is ignored.

     MESSAGE <cMessage> specifies a character string that is displayed on
     the Get system's status bar line when the GET has input focus.
     Typically, it describes the anticipated contents or user response of the
     GET.  Refer to the READ command for details pertaining to the Get
     system's status bar.

     WHEN <lPreExpression> specifies an expression that must be satisfied
     before the cursor can enter the GET during a READ.  The expression can
     optionally be a code block.  The Get object is passed as a parameter to
     the code block.

     VALID <lPostExpression> specifies an expression that must be
     satisfied before the cursor can leave the GET during a READ.  The
     expression can optionally be a code block.  The Get object is passed as
     a parameter to the code block.

     COLOR <cColorString> defines the color settings for the push button.
     <cColorString> is a character expression containing exactly four color
     settings.

     PushButton Color Attributes
     ------------------------------------------------------------------------
     Position     Applies To                             Default Value from
     in colorSpec                                        System Color Setting
     ------------------------------------------------------------------------
     1            The push button when it does not have    Unselected
                  input focus
     2            The push button when it has input focus  Enhanced
                  and is not pressed
     3            The push button when it has input focus  Standard
                  and is pressed
     4            The push button caption's accelerator    Background
                  key
     ------------------------------------------------------------------------

     Note:  The background colors of the PushButton Color Attributes are
     ignored in graphic mode.

     FOCUS <fblock> specifies a code block that is evaluated each time
     the push button recieves focus.  The code block takes no implicit
     arguments.  Use the PushButton:hasFocus instance variable to determine
     if the push button has focus.

     STATE <bBlock> specifies a code block that is evaluated each time
     the push button object's state changes.  The code block takes no
     implicit arguments.  Use the PushButton:buffer instance variable to
     determine if the push button is pressed or released.  A value of true
     (.T.) indicates that it is being pressed; otherwise, a value of false
     (.F.) indicates that it is being released.

     STYLE <cStyle> specifies a character string that indicates the
     delimiter characters that are used by the push button's display()
     method.  When specified, the string must contain either zero, two, or
     eight characters.  The default is two characters.  The first is the left
     delimiter.  Its default value is the less than (<) character.  The
     second character is the right delimiter.  Its default value is the
     greater than (>) character.

     When the style string is empty, the button has no delimiters.  When the
     string length is two, the button has left and right delimiters and
     occupies one row on the screen.  The first character is the left
     delimiter.  The second character is the right delimiter.  When the
     string length is eight, the button is contained within a box that
     occupies three rows on the screen.

     Standard Box Types
     ------------------------------------------------------------------------
     Constant            Description
     ------------------------------------------------------------------------
     B_SINGLE            Single-line box
     B_DOUBLE            Double-line box
     B_SINGLE_DOUBLE     Single-line top/bottom, double-line sides
     B_DOUBLE_SINGLE     Double-line top/bottom, single-line sides
     ------------------------------------------------------------------------

     Box.ch contains manifest constants for the PushButton:style value.

     The default style for the @...GET PUSHBUTTON is "<>".

     Note:  The Style clause is ignored in graphic mode.

     SEND <msg> sends the specified message to the Get object.  <msg> is
     sent before the GET is displayed.  Any message can be sent, including
     method calls and instance variable assignments.  Method calls must
     include parentheses even if no arguments are passed.

     GUISEND <guimsg> can be used to send a message (such as the
     display() method) to a GUI object.  The GUI objects available in
     CA-Clipper are check boxes, list boxes, push buttons, and radio button
     groups.  To send a message to a non-GUI object, such as standard GETs
     and TBrowses, use the SEND clause.

     SIZE X <nSizeX> Y <nSizeY> defines the size of the button to be
     displayed.  The coordinates are in pixels.  <nSizeX> represents the
     number of pixels in the x direction (horizontally) and <nSizeY>
     represents the number of pixels in the y direction (vertically).  This
     argument only affects applications running in graphic mode and is
     ignored in text mode.

     CAPOFF X <nCapXOff> Y <nCapYOff> defines the offset where the
     caption is displayed.  The coordinates are in pixels.  <nCapXOff>
     represents the number of pixels in the x direction (horizontally) from
     the left edge of the button where the caption will be displayed.
     <nCapYOff> represents the number of pixels in the y direction
     (vertically) from the top edge of the button where the caption will be
     displayed.  If the CAPOFF clause is not supplied, the caption will be
     centered on the button.  This argument only affects applications running
     in graphic mode and is ignored in text mode.

     BITMAP <cBitmap> defines a bitmap file to be displayed on the
     button.  Drive and directory names are not allowed; the file name
     extension is required.  A bitmap file can be stored as a file on disk or
     in a bitmap library.  If stored as a file, the file must reside in the
     same directory as the application.  If stored in a bitmap library, the
     library must reside in the same directory as the application and it also
     must have the same name as the application with a .bml extension.

     CA-Clipper will search for the file name first and, if it is not found,
     search in the bitmap library second.  If no file is found either on disk
     or in the library, no bitmap will be displayed.

     BMPOFF X <nBmpXOff> Y <nBmpYOff> defines the offset where the bitmap
     is displayed.  The coordinates are in pixels.  <nCapXOff> represents the
     number of pixels in the x direction (horizontally) from the left edge
     where the bitmap will be displayed.  <nCapYOff> represents the number of
     pixels in the y direction (vertically) from the top edge where the
     bitmap will be displayed.  If the BMPOFF clause is not supplied, the
     bitmap will be placed at the upper-left corner of the button.  This
     argument only affects applications running in graphic mode and is
     ignored in text mode.

 Examples

     .  This example demonstrates how to add a push button to a data
        entry screen:

        @ 5, 20 GET lCancel PUSHBUTTON ;
                CAPTION "&Cancel"
                STATE { || ReadKill( .T. ) }

 Files   Libraries are CLIPPER.LIB and LLIBG.LIB.