Previous Next

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:
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:
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:
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 28 explains how many pixels the image size expands based on the button size.
 
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:
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 29 describes the conversion process.
 
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:
 
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 
*
*
*
*
*
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.
*
*
*
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.
*
*
*
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.
See also 
Class-based data member access, FORM statement, Image phrase

Previous Next
© 2013 Progress Software Corporation and/or its subsidiaries or affiliates.