In graphical environments, you can customize the basic set of colors that you use in your programs.
ACUCOBOL-GT allows programs to reference 16 distinct colors (8 low-intensity and 8 high-intensity). For most machines, this set of colors is fixed (black, blue, green, cyan, red, magenta, brown, and white). On Windows machines, you can select which 16 colors you will be using. You are given access to a palette of 16 colors that defines which color corresponds to each color number.
You control the palette through the library routine W$PALETTE.
Usage
CALL "W$PALETTE" USING OP-CODE, WPALETTE-DATA GIVING RESULT
Parameters
OP-CODE Numeric value
Selects which palette function to perform. The op-codes are described below.
WPALETTE-DATA Group item as follows:
01 WPALETTE-DATA.
03 WPAL-COLOR-ID PIC X COMP-X.
03 WPAL-FLAGS REDEFINES
WPAL-COLOR-ID PIC X COMP-X.
03 WPAL-RED PIC X COMP-X.
03 WPAL-USER-COLOR-ID REDEFINES
WPAL-RED PIC X COMP-X.
03 WPAL-GREEN PIC X COMP-X.
03 WPAL-BLUE PIC X COMP-X.
This provides information and holds results for certain operations described below. It may be omitted from those operations that do not use it.
RESULT Signed numeric data item.
Returns the status of the operation. Unless otherwise stated below, "1" indicates success, and a zero or negative result indicates failure.
The WPALETTE-DATA group item and all of the level 78 symbolic names described below can be found in the COPY library "palette.def".
Description
W$PALETTE performs a variety of operations depending on the passed OP-CODE. These operations are as follows:
WPALETTE-SUPPORTED (OP-CODE value "1")
This determines the level of support the host machine provides for the W$PALETTE routine. Use this to determine if the host machine will allow you to perform certain operations.
WPALETTE-DATA is not used. The RESULT value will be one of the following:
WPAL-NO-SUPPORT (value "0") This value indicates that the host machine does not support palettes. Only the WPALETTE-SUPPORTED and WPALETTE-NUM-COLORS operations will function. Currently, this result is returned for all platforms other than Windows and Windows NT.
WPAL-PALETTE-SUPPORTED (value "1") This value indicates that all W$PALETTE functions are supported except for the WPALETTE-CHOOSE-COLOR function.
WPAL-FULL-SUPPORT (value "2") This value indicates that all W$PALETTE functions are available.
WPALETTE-NUM-COLORS (OP-CODE value "2")
This operation sets RESULT to the number of distinct solid colors that the host machine can display simultaneously.
WPALETTE-DATA is not used. For monochrome machines, the RESULT value will be "2". For color machines other than Windows, this value will be "16".
For Windows machines, this value will depend on the host hardware and drivers installed. For a standard VGA system, this value will be "16". For Super VGA systems with the proper driver installed, this value can be "256" or higher. If the machine supports more than 32,767 distinct colors, then "32767" will be returned.
For machines with 16 or fewer colors, the standard ACUCOBOL-GT palette represents the entire range of solid (pure) colors. In order to display any other color, that color must be simulated by dithering two or more colors together. Windows allows us to do this, but only for background colors. If you attempt to display a dithered color in the foreground, Windows will automatically substitute the nearest solid color. Dithered background colors can also make the foreground text look ragged, depending on the exact colors used. For this reason, you may want to limit yourself to solid colors. One way to do this is to allow the user to change the palette only when the machine supports 256 colors or more.
WPALETTE-GET-COLOR (OP-CODE value "3")
This operation retrieves the color that currently corresponds to a particular color number. Colors are numbered "1" through "16". The first 8 colors correspond to the low-intensity colors.
Their initial values are as follows:
| 1
| Black
|
| 2
| Blue
|
| 3
| Green
|
| 4
| Cyan
|
| 5
| Red
|
| 6
| Magenta
|
| 7
| Brown
|
| 8
| White |
When it returns, the WPAL-RED, WPAL-GREEN, and WPAL-BLUE fields of WPALETTE-DATA will be filled in with the current definition of that color number. Each of these fields will contain a value from "0" to "255" that indicates the intensity of the red, green, and blue components of the color. A red-green-blue (RGB) combination of "0", "0", "0" indicates black. A RGB value of "255", "255", "255" is bright white. Other values cover the entire range of colors possible under Windows.
WPALETTE-SET-COLOR (OP-CODE value "4")
This function complements WPALETTE-GET-COLOR; it lets you assign a new color to a particular color number. At entry, WPAL-COLOR-ID should contain the color number you want to change. WPAL-RED, WPAL-GREEN, and WPAL-BLUE should contain the RGB value of the new color (see WPALETTE-GET-COLOR for a description of RGB values).
For example, if you want to make color number "2" represent a dark blue-green, you could use the following values:
| WPAL-COLOR-ID
| 2
|
| WPAL-RED
| 0
|
| WPAL-GREEN
| 64
|
| WPAL-BLUE
| 64
|
ACUCOBOL-GT computes the high- or low-intensity version of a color by adding or subtracting "8" from its color number. This assumption also affects the rendering of "3-D" lines if you use them on a colored background. Although you are not required to maintain any of these assumptions, be aware of them so that you can anticipate the total effects of your changes.
WPALETTE-UPDATE (OP-CODE value "5")
In order to allow you to change several colors efficiently, W$PALETTE does not immediately apply the new palette after you change it. It waits until the next screen update (usually caused by either an ACCEPT or DISPLAY statement). In most cases this is adequate. If you want to force the screen to be updated immediately with the new palette, you can use the WPALETTE-UPDATE function. WPALETTE-DATA is not used. The effect is to update the screen with the new palette and return.
WPALETTE-CHOOSE-COLOR (OP-CODE value "6")
This operation provides a simple method for getting a color selection from the user. You can use this to simplify the process of constructing your color palette according to your user's desires. When this operation executes, a standard color selection box pops up over your application. This box is similar to the "Color Palette" portion of the Windows' Control Panel application. It should be familiar to most users.
This box contains a selection of pre-determined colors (called the "Basic Colors") that the user can choose from. Windows selects these colors. Typically, there are 48 of them drawn from the entire spectrum (there can be fewer on some systems).
The user can pick one of these by clicking the mouse on it or by using the arrow keys.
Beneath these colors is a set of 16 "Custom Colors". Initially, these colors are all white. The user can select the "Define Custom Colors" option to define new colors. This pulls up a color chart that the user can select from. After selecting a custom color, the user can add it to the set of 16 custom colors by selecting the "Add to Custom Colors" button. This color is then available for future selection.
The user selects the "OK" button (or presses <enter>) to complete selection of the color. The RGB value of the color selected is returned in WPAL-RED, WPAL-GREEN, and WPAL-BLUE.
Alternately, the user can select the "Cancel" button (or press <escape>). In this case, no color is returned and the value of RESULT is set to WPERR-CANCELLED (see below).
The initial default color selection is black (RGB value "0", "0", "0"). You may supply a different default value by moving the desired color into WPAL-RED, WPAL-GREEN, and WPAL-BLUE. You must also set WPAL-FLAGS to WPAL-USE-DEFAULT (value "1"). If you do not use this option, then you should set WPAL-FLAGS to zero before calling W$PALETTE.
The color selection box is a standard component of Windows and Windows NT.
This operation allows you to assign selected system colors to COBOL color numbers. It uses two fields in the WPALETTE-DATA group item.
WPAL-COLOR-ID contains the number of the COBOL color you want to change. Values range from "1" (low-intensity black) to "16" (high-intensity white).
WPAL-USER-COLOR-ID contains the number of the system color to use. You can use either WPUSER-COLOR-3D, which matches the system's color for the background of 3-D objects, or WPUSER-COLOR-BACKGROUND, which matches the system's color for window backgrounds. These values are defined in "palette.def".
The following example redefines the COBOL color number "8" (which is gray in the default palette) to be the same as the system's 3-D color:
MOVE 8 TO WPAL-COLOR-ID
MOVE WPUSER-COLOR-3D TO WPAL-USER-COLOR-ID
CALL "W$PALETTE" USING
WPALETTE-SET-USER-COLOR, WPALETTE-DATA
Errors are handled in the same manner as the WPALETTE-SET-COLOR function. Note that under some systems, such as Microsoft Windows, the system colors can change dynamically at runtime. If this occurs, the runtime will automatically remap the colors in the palette as needed to match the new system colors.
For additional color configuration options, see the USER-GRAY, USER-WHITE, and USER-COLORS options of the DISPLAY FLOATING WINDOW verb.
Error Handling
RESULT is set to a positive value if the call to W$PALETTE is successful. Except for the WPALETTE-SUPPORTED and WPALETTE-NUM-COLORS operations, the success value is always "1". A zero or negative value indicates a problem. The following values are possible:
WPERR-UNSUPPORTED (value "0")
Either the requested operation cannot be performed on the host system, or you passed an invalid operation code.
WPERR-BAD-ARG (value "-1")
Either you did not pass WPALETTE-DATA when it was required, or WPALETTE-DATA contains some invalid data.
WPERR-CANCELLED (value "-2")
The user selected the "cancel" operation of the color selection box, or the user closed the selection box.