Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## DEFINE BUTTON statement

> The DEFINE BUTTON statement defines a static push button for use within the current procedure.

> 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 data member for a class, and optionally specifies an access mode for that data member. Do not specify the access mode when defining a button widget for a method within a class.

> PRIVATE data members can be accessed only by the defining class. The default access mode is PRIVATE.

> Note: This option is applicable only when defining a data member for a class in a class definition (`.cls`) file.

> `BUTTON `button``

> Specifies the name of the button. You can define the button widget in a procedure or a method within a class.

> `AUTO-END-KEY`

> Specifies that when you choose this button, Progress applies the ENDKEY event to the frame.

> `AUTO-GO`

> Specifies that when you choose this button, Progress 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.

> Specifies the background color for the button in a graphical user interface.

> `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.

> Specifies the foreground color for the button in a graphical user interface.

> `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 Progress 4GL 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 Progress predefined 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, Progress 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, Progress 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 23 explains how many pixels the image size expands based on the button size.

> Table 23: 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 (Progress 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, Progress 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, Progress 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 24 describes the conversion process.

> Table 24: 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 Progress 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. Progress 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.cust-num name
>        WITH FRAME brief ROW 4.

>     FORM customer EXCEPT cust-num name
>        WITH FRAME full ROW 7.

>     ON CHOOSE OF more-button
>        DISPLAY customer EXCEPT cust-num name WITH FRAME full.

>     ON CHOOSE OF next-button
>        DO:
>           HIDE FRAME full.
>           FIND NEXT customer NO-ERROR.
>           DISPLAY cust-num name WITH FRAME brief.
>        END.

>     FIND FIRST customer.
>     DISPLAY cust-num 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 static button you are defining, you must define a static frame that contains the button. Each frame you define that contains the same button creates an additional instance of that button. The widget handle for a static 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 static 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, Progress 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 Progress 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. Progress does not report an error. However, the button will not respond to keyboard activity.

> - The Progress 4GL 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, Progress does not draw the 3D effect; the images, themselves, should be drawn with a 3D effect.

> - Progress 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

> FORM statement, Image phrase

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095