DEFINE BUTTON statement

The DEFINE BUTTON statement defines a push button that is created at compile time for use within the current procedure or class.

Note: Does not apply to SpeedScript programming.

Syntax

DEFINE [ PRIVATE ] BUTTON button
  [ AUTO-GO | AUTO-ENDKEY ]
  [ DEFAULT ]
  [ BGCOLOR expression]
  [ CONTEXT-HELP-ID expression]
  [ DCOLOR expression]
  [ DROP-TARGET ]
  [ FGCOLOR expression]
  [ FONT number]
  [ IMAGE-DOWN image-phrase]
  [{ IMAGE | IMAGE-UP } image-phrase ]
  [ IMAGE-INSENSITIVE image-phrase]
  [ MOUSE-POINTER name]
  [ LABEL label]
  [ LIKE button]
  [ PFCOLOR expression]
  [ size-phrase ]
  [ NO-FOCUS [ FLAT-BUTTON ]]
  [ NO-CONVERT-3D-COLORS ]
  [ TOOLTIP tooltip]
  {[ trigger-phrase ]}
[ PRIVATE ] BUTTON button

Defines and identifies a button widget as a class-scoped object. A class-scoped handle-based object is not a member of a class, but provides a resource that is privately available to the class definition similar to a non-shared data element in a procedure definition. The option to specify the PRIVATE access mode is provided for readability. You cannot specify PRIVATE when defining a button widget as a data element in a method or procedure.

Note: This option is applicable only when defining a class-scoped button widget in a class definition (.cls) file.
BUTTON button
Defines and identifies a button widget for access only within the current procedure, class, or method of a class.
AUTO-END-KEY
Specifies that when you choose this button, the AVM applies the ENDKEY event to the frame.
AUTO-GO
Specifies that when you choose this button, the AVM applies the GO event to the frame.
DEFAULT

Specify DEFAULT to indicate that the button is a default button. A default button is one that handles all RETURN events when no other RETURN-enabling widget in the frame or dialog box has focus. RETURN-enabling widgets include any field-level widget for which a RETURN trigger is defined, or any button, whether or not it has a trigger defined. Thus, if a button has focus, that button handles the next RETURN event. If any other field-level widget without a RETURN trigger has focus, the default button handles the next RETURN event.

To make the button the default button for the frame in which it resides, you must also set the frame's DEFAULT-BUTTON option.

BGCOLOR expression
Supported only for backward compatibility.
CONTEXT-HELP-ID expression
An integer value that specifies the identifier of the help topic for this button in a help file specified at the session, window or dialog box level using the CONTEXT-HELP-FILE attribute.
DCOLOR expression
Specifies the display color for the button in character interfaces. This option is ignored in graphical interfaces.
FGCOLOR expression
Supported only for backward compatibility.
FONT number
Specifies the font for the button label. The value number must be an expression that resolves to an integer value. That integer must be associated with a specific font in your system environment files.
{IMAGE | IMAGE-UP } image-phrase

An image that you want to appear within the button when the button is in its up state. If the image does not have a down state, for code readability you might want to use the IMAGE option instead of the IMAGE-UP option.

The IMAGE | IMAGE-UP image-phrase option is ignored in character interfaces.

The syntax of image-phrase is as follows:

FILE name
  [{ IMAGE-SIZE | IMAGE-SIZE-CHARS | IMAGE-SIZE-PIXELS }
      width BY height
  ]
  [ FROM {{ X n Y n}|{ ROW n COLUMN n}}]

For more information on this syntax, see the Image phrase reference entry.

IMAGE-DOWN image-phrase

An image that you want to appear within the button when the button is in its down state. The IMAGE-DOWN option is ignored in character interfaces.

For more information, see the Image phrase reference entry.

Note: The AVM draws the 3D effect only if a button has an up image, but no down image.
IMAGE-INSENSITIVE image-phrase

An image you want to appear within the button when the button is in its insensitive (disabled) state. This option is ignored in character interfaces.

For more information, see the Image phrase reference entry.

MOUSE-POINTER name
Specifies the mouse pointer for the button. The character value name is either the name of a predefined ABL pointer, or the name of a Windows .cur file that defines a pointer or an .ani file that contains an animated cursor.
LABEL label

The label displayed on the button. The name should describe the action invoked when the button is chosen. The value of label must be a string enclosed in quotes. The default label is the button name. If you use the LIKE button option and you do not use the LABEL option, the button inherits the label of the button you name.

You can indicate a character within the label to be used as a navigation mnemonic in Windows. Indicate the character by preceding it with an ampersand (&). When the button is displayed, the mnemonic is underlined. The user can choose the button by pressing ALT and the underlined letter. If you specify more than one button with the same mnemonic, the AVM transfers focus to each of these in tab order when you make a selection.

To include a literal ampersand within a label, specify a double ampersand (&&).

LIKE button
Indicates the name of a defined button whose characteristics you want to use for a new button. If you name a button with this option, you must have defined that button earlier in the procedure. You can override the label, image, and on phrase by using the LABEL, IMAGE, and on-phrase options. If you do not use these options, the button takes on the characteristics of the button you name.
PFCOLOR expression
Specifies the prompt-for color for the button in character interfaces. This option is ignored in graphical interfaces.
size-phrase

Specifies the outside dimensions of the button widget. Following is the syntax for size-phrase:

{ SIZE | SIZE-CHARS | SIZE-PIXELS }width BY height

If you specify SIZE or SIZE-CHARS, the units are characters; if you specify SIZE-PIXELS, the units are pixels. For character units, the values width and height must be decimal constants; for pixel units, they must be integer constants. For more information, see the SIZE phrase reference entry.

If no size is specified, the AVM calculates a default size for the button. This calculation adds the button's border thickness (that is, the combination of 3D shadows and highlights, and the focus rectangle) to the up image size defined by the IMAGE | IMAGE-UP image-phrase option. However, the thickness of the border depends on whether the button has dual images (up and down images) and whether it is a FLAT-BUTTON or NO-FOCUS button.

The following table explains how many pixels the image size expands based on the button size.

Determining button border thickness
Button image NO-FOCUS status FLAT-​BUTTON status Border thickness
Up image only No No 7 pixels (2 pixels for the focus rectangle, 5 pixels for the 3D shading)
Up and down image No No 4 pixels (4 pixels for the focus rectangle, 0 pixels for the 3D shading)
Up image only Yes No 5 pixels (0 pixels for the focus rectangle, 5 pixels for the 3D shading)
Up and down image Yes No 0 pixels (ABL expects the specified image to include a border)
Up image only Yes Yes 2 pixels
Up and down image Yes Yes 2 pixels
NO-FOCUS [ FLAT-BUTTON ]

Specifies that the button should not accept focus. A button for which the NO-FOCUS attribute is defined will not take focus when the mouse is clicked on it, and it will not accept keyboard input. Also, the AVM will not generate ENTRY or LEAVE events for the button. NO-FOCUS buttons behave similarly to standard Windows toolbar buttons. The NO-FOCUS option is supported in Windows only.

A button with the NO-FOCUS attribute is not added to its parent frame's tab order. However, if the NO-FOCUS attribute is switched from TRUE to FALSE before the button is realized, the button is added to the end of its parent frame's tab order. Switching the NO-FOCUS attribute from FALSE to TRUE before realization removes the button from its parent frame's tab order.

Note: If a frame that contains a NO-FOCUS button does not itself have focus, the frame does not receive focus when the button is pushed. In this situation, frame entry or leave events are not generated. Focus stays on the current widget when a NO-FOCUS button is pushed, even across multiple frames in a window.
FLAT-BUTTON
A flat button is a new style of button which is two-dimensional until the mouse passes over it, at which time, a 3D border appears.
NO-CONVERT-3D-COLORS

Specifies that the colors of the button's images (that is, up, down, and insensitive) are not converted to the system 3D colors. By default, the AVM converts shades of gray in an image to the corresponding system 3D color. Using the NO-CONVERT-3D-COLORS option overrides this default behavior. The NO-CONVERT-3D-COLORS option is supported in Windows only.

The following table describes the conversion process.

3D-color conversions for buttons
If the color is . . . And the original Red-Green-Blue (RGB) color value is . . . Then the new converted system color is . . .
White (255, 255, 255) System button highlight color
Light Gray (192, 192, 192) System button face color
Dark Gray (128, 128, 128) System button shadow color
Black (0, 0, 0) System button text color

During a session, if Windows notifies the AVM that the system colors have changed, the button's images are re-loaded and converted to the new system colors, unless the NO-CONVERT-3D-COLORS option is specified.

TOOLTIP tooltip

Allows you to define a help text message for a button. The AVM automatically displays this text when the user pauses the mouse pointer over the button.

You can add or change the TOOLTIP option at any time. If TOOLTIP is set to "" or the Unknown value (?), then the ToolTip is removed from the button. No ToolTip is the default. ToolTips are supported in Windows only.

DROP-TARGET
Indicates whether you want to be able to drop a file onto the object.
trigger-phrase

Specifies application triggers for the button.

For more information, see the Trigger phrase reference entry.

Example

This procedure defines two buttons, positions the buttons within a form, assigns triggers to the buttons with ON statements, and enables the buttons by referencing them in an ENABLE statement:

r-button.p

DEFINE BUTTON more-button LABEL "More".
DEFINE BUTTON next-button LABEL "Next".

FORM more-button next-button
  WITH FRAME but-frame ROW 1.

FORM Customer.CustNum Customer.Name
  WITH FRAME brief ROW 4.

FORM Customer EXCEPT Customer.CustNum Customer.Name
  WITH FRAME full ROW 7.

ON CHOOSE OF more-button
  DISPLAY Customer EXCEPT Customer.CustNum Customer.Name WITH FRAME full.

ON CHOOSE OF next-button DO:
  HIDE FRAME full.
  FIND NEXT Customer NO-ERROR.
  DISPLAY Customer.CustNum Customer.Name WITH FRAME brief.
END.

FIND FIRST Customer.
DISPLAY Customer.CustNum Customer.Name WITH FRAME brief.

ENABLE more-button next-button WITH FRAME but-frame.
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

When the procedure is run, the first Customer's number and name are initially displayed. The user can choose either the MORE button to see the entire Customer record or the NEXT button to see the next Customer's number and name.

The following example sets up a browse that allows you to drop a file on the browse:

DEFINE BUTTON button-1 LABEL ''Drop Here'' DROP-TARGET. 

Notes

See also

Class-based data member access, FORM statement, Image phrase