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` ] }

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.

Table 27 explains how many pixels the image size expands based on the button size.

Table 27: 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.

Table 28 describes the conversion process.

Table 28: 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.

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

When a frame receives a default RETURN event, it actually sends a CHOOSE event to the default button.

To create the compile-time defined button you are defining, you must define a compile-time defined frame that contains the button. Each frame you define that contains the same button creates an additional instance of that button. The handle for a compile-time defined button is not available until the button is created.

You must enable a button to make it available to the user. You can enable a button by setting its SENSITIVE attribute or by referencing it in an ENABLE or UPDATE statement.

On a character-based terminal, a button appears as the label enclosed in angle brackets (< >). The user can move the mouse pointer to the button by pressing TAB or arrow keys. The user can then choose the button by pressing SPACEBAR or RETURN.

You can specify an application-defined widget ID for a compile-time defined button widget using the form-item phrase in either the FORM statement or the DEFINE FRAME statement. See the FORM statement and DEFINE FRAME statement reference entries for more information.

To make an application portable between graphical and character environments, you can specify an image and a label for a button. In graphical environments, the image is used and the label is ignored; in character environments, the label is used and the image is ignored.

If you specify a size for a button, the button is not affected by changes to the size of any contained image. If you do not specify a size for the button, the button changes size to fit the image.

In Windows, ABL supplies the following prepackaged images for the up, down, left, and right arrows: btn-up-arrow, btn-down-arrow, btn-left-arrow, and btn-right-arrow. Specify one of these items in place of a filename.

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.

You can apply entry to a NO-FOCUS button programmatically. The AVM does not report an error. However, the button will not respond to keyboard activity.

The AVM draws the 3D effect only if a button has an up image, but no down image. If the button has both an up image and a down image, the AVM does not draw the 3D effect; the images, themselves, should be drawn with a 3D effect.

The AVM only performs the color conversion process on bitmaps (.bmp files) that contain 256 or fewer colors. However, you might consider using 16-color bitmaps because only the first sixteen entries in the bitmap’s color table will be converted.

Icon colors (.ico files) are not converted, even if CONVERT-3D-COLORS is TRUE. To ensure that an icon will be displayed properly on a button, draw icons with a transparent background.