The DEFINE BUTTON statement defines a push button that is created at compile time for use within the current procedure or class.
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 ]}
|
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.
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.
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.
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.
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.
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 (&&).
Specifies the outside dimensions of the button widget. Following is the syntax for size-phrase:
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.
| 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 |
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.
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.
| 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.
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.
Specifies application triggers for the button.
For more information, see the Trigger phrase reference entry.
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:
Use these values for the IMAGE-UP option. Doing so makes the prepackaged image available to ABL in its up, down, and insensitive state, without specifying the IMAGE-DOWN and the IMAGE-INSENSITIVE options. You will also get appropriately sized arrows based on your screen resolution.