The set of push button common properties includes:
A push button appears centered in the button. The TITLE phrase is used to specify the title. A key letter may be specified in the title. See Common Screen Options in the ACUCOBOL-GT Reference Manual for more information.
Push buttons do not use values.
The LINES and SIZE values describe the size of the button's title area. The LINES value describes the height of the title area. The SIZE value is the width of the title area, using the width of the 0 (zero) character as the base unit. Added to the title area is overhead for the push button's border. The exact size of the border area is system-dependent. Note that the title area may be larger than the actual title. The title itself is centered both vertically and horizontally in the title area.
When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, are used in place of the values specified by the LINES and SIZE phrases.
The default LINES value is 1. The default SIZE value is 8.
When the BITMAP style is used, the LINES and SIZE values have a different meaning. The values are the number of pixels in the height and width of the bitmap image. If omitted, the default values depend on the host system. Under Windows, the default LINES value is 15 and the default SIZE value is 16. These correspond to the size of buttons typically found on a toolbar. See Bitmap Buttons for more information.
Push buttons support colors. Use the COLOR property to specify a color. The focus rectangle is the same color as the text on the push-button. Note that this ability depends on using native controls, by setting WIN32_NATIVECTLS to TRUE. The actual colors used are system-dependent. Under Windows, the user selects the colors in the Control Panel.
Push buttons can appear and behave like an HTML link. Use the ISLINK property to do this. These push buttons are drawn as plain text without any button-style frame. When moving the mouse over this type of push button, the cursor changes to a hand, indicating that the link is clickable. Upon clicking, the runtime sends a message to the COBOL program as if a push button is clicked. Specifying this style automatically implies the NOTAB and SELF-ACT styles.
EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.
Push buttons with bitmaps support text along with the bitmap. The text displayed is the value of the TITLE property. The TITLE-POSITION property value determines the location of the text. Valid values include:
Any other value results in text not displaying. The COLOR property of the push button determines the text color. Adjust the size of the button to display the text as well as the bitmap. otherwise the text or the bitmap may be cropped, based on the TITLE-POSITION.
If the TITLE-POSITION is LEFT or TOP, then the text displays first, with any remaining space used for the bitmap. If the TITLE-POSITION is RIGHT or BOTTOM, then the bitmap displays first, with any remaining space used for text.
Use this property to designate transparent regions in a bitmap. This is done by reserving one of the colors in the bitmap as the transparent color. Any points in the bitmap that contain this color will not be displayed when the bitmap is drawn, allowing the background to show through. This can be useful if you want to integrate a logo onto a screen in a way that accommodates the user's choice of desktop colors.
To designate a transparent region, choose one color in the bitmap to be the transparent color. Then, set the TRANSPARENT-COLOR property to the RGB color value of this color. The RGB color value is computed by the following formula:
(red * 65536) + (green * 256) + blue
where red, green, and blue are values between 0 and 255. You can use a hexadecimal numeric literal to express this value, because each component of the color occupies one byte in a binary value. For example, the following literal expresses an orange color with red at 255, green at 128, and blue at 0:
78 orange value x#FF8000.
The first byte (x 'FF') is the red value, the second byte (x'80') is the green value, and the last byte (x'00') is the blue value.
If you set TRANSPARENT-COLOR to -1 (the default), the transparency property is turned off and all colors display normally.
Setting TRANSPARENT-COLOR to the hex value x#1000000 automatically specifies the pixel in the upper-left corner of a bitmap as the transparent color. (This is the level 78 constant BM-CORNER-COLOR in acugui.def.) You don't need to know the exact color of that pixel to use this value.
To avoid flashing, the runtime does not update the region under a transparent bitmap once it is in place. One effect of this is that if you animate a bitmap with transparent regions, you must ensure that those regions are the same in each frame of the animation, or the image will blur.
| DEFAULT-BUTTON | This style indicates that this button is the default push button. The user can push (activate) the default button by typing
a termination key that has a termination code of
13. Under the default runtime configuration, this is the
Return (or
Enter) key. When this occurs, the run-time generates a button pushed event instead of the normal termination event. This ensures
that the program treats the
Return key and the default push button in the same manner (since they both generate the same event). For related information, see
the
TERMINATION-VALUE special property.
Push buttons with the DEFAULT-BUTTON style are typically displayed differently by the host system. Under Microsoft Windows, default push buttons have a thicker border. Only one button should have the DEFAULT-BUTTON style at any one time. If more than one button has the DEFAULT-BUTTON style, the meaning is ambiguous. Note that the DEFAULT-BUTTON style is implied by the OK-BUTTON style |
| ESCAPE-BUTTON | Similar to the DEFAULT-BUTTON style, this style indicates that the push button corresponds to the Escape key. The user can push this button by typing a key that has an exception value of 27 (that is, the Escape key in the default configuration). When this occurs, the run-time generates a button pushed event instead of the normal exception event. This ensures that your program handles the Escape key and the escape button in the same manner. Note that only one enabled button should have the ESCAPE-BUTTON style at any one time. See the EXCEPTION-VALUE property below for related information. |
| NO-AUTO-DEFAULT | Normally, when a push button is activated, it becomes the default push button. The run-time accomplishes this by giving the DEFAULT-BUTTON style to the activated push button and removing it from any other push button in the same floating window. This allows the user to press the Return key to push the active button. If you specify NO-AUTO-DEFAULT, this behavior is not applied when this button is made active. The default push button, if any, remains unchanged. |
| SELF-ACT | Normally, when the user clicks a
CMD-GOTO event is sent to your to your program. After being activated, the button can then return that it has been pushed. Buttons
with the
SELF-ACT style are self-activated instead. This means that they do not send the
CMD-GOTO event to your program when clicked. Instead they activate themselves and then send the appropriate button pushed termination
status to the program. If you also assign an exception value to the button, it will act just like the equivalent function
key. For example, the following statement fragment builds a push button that behaves just like function key 1 (usually marked
F1).
DISPLAY PUSH-BUTTON, SELF-ACT, EXCEPTION-VALUE=1 Self-activating buttons behave differently in some additional, subtle, ways. Normally, if the user down-clicks on a push button and then moves the mouse away before releasing the button, the push button remains active (shown in Windows by a thicker border around the button). But the button is not clicked. Self-activating buttons do not remain active. Instead, they re-activate the previous control. This is done because self-activating controls don't tell the program about the down-click event. To ensure that the program and screen states are consistent, the previous control is re-activated. Also, self-activating buttons do not automatically become the default push button when clicked on with the mouse. Generally speaking, there is rarely a need to use this style for push buttons defined in a group within the Screen Section. The Screen Section handler performs all the button activation needed when the group is accepted. The SELF-ACT style is mostly useful when you define individual push buttons using the DISPLAY verb (or as elementary Screen Section items) and you do not want to program the activation of those buttons. A common use would be to add push buttons to an existing application where the push buttons will perform the same operation as some function key. In this case, you can simply create the push button with the SELF-ACT style and an exception value that is the same as the function key. Usually, no other coding is needed, because the button will perform all of its own activation and simulate the function key when it is clicked Note: The
SELF-ACT style performs automatic activation only when the user clicks on the button with the mouse or uses its key letter. You must
still program your own activation if you want the user to be able to visit the button in some other fashion (for example,
by using the
Tab key to move to the button).
Also note that this style makes the button self-activating, but not any associated Screen Section entry. This means that any BEFORE or AFTER procedures named in an associated Screen Section entry will not automatically execute when the button is clicked. They will function only when you ACCEPT the Screen Section entry in your program. |
| OK-BUTTON | This style is used only when the button is created. It has the effect of changing several of the button's default values.
It is equivalent to specifying the following:
TITLE "OK" DEFAULT-BUTTON TERMINATION-VALUE = 13You may override the TITLE and TERMINATION-VALUE settings by providing your own. The net effect of the OK-BUTTON style is that it provides a convenient way of creating a typical OK button. |
| CANCEL-BUTTON | This style is similar to the
OK-BUTTONstyle, but it produces a Cancel button instead. It is equivalent to specifying the following defaults when the button is created: TITLE "Cancel" ESCAPE-BUTTON EXCEPTION-VALUE = 27You may override the TITLE and EXCEPTION-VALUE defaults by providing your own. |
| BITMAP | This style causes the push button to be drawn using a bitmap instead of its default appearance. See Bitmap Buttons for a complete description. |
| FRAMED | This style is used only with bitmap buttons. It requests that a thin frame be drawn around the button. Typically this appears as a thin black line. Not all systems support frames, in which case the request is ignored. By default, buttons are framed under Windows NT/Windows 2000. |
| UNFRAMED | This style is used only with bitmap buttons. It requests that the button be drawn without a frame. Not all systems support unframed buttons, in which case the request is ignored. By default, buttons are not framed under Windows 98. |
| SQUARE | This style is used only with framed bitmap buttons. It forces the button to have square corners. Without this style, the button will have slightly rounded corners. |
| FLAT | On graphical systems, and only when a bitmap is used, this style creates a button without visible borders. On character-based system, this style has no effect. |
| MULTILINE | On graphical systems, this style causes the push button to have a multiline title. When the MULTILINE style is applied, the push button's title text is automatically word wrapped to fit the push button's size. You can force a line break in the text by embedding an ASCII line feed character (h"0A"). The MULTILINE style is ignored in character-based environments. |