The W$FONT routine provides general support for selecting fonts and determining their characteristics.
Usage
CALL "W$FONT" USING OP-CODE, FONT-HANDLE, WFONT-DATA GIVING WFONT-STATUS
Parameters
OP-CODE Numeric value
Selects the W$FONT function to perform. These op-codes are described below.
FONT-HANDLE USAGE HANDLE or HANDLE OF FONT
When retrieving a font from the system, the system stores a handle to the font in this item. With other operations, this value specifies the font to act on.
WFONT-DATA Group item as follows:
01 WFONT-DATA.
03 WFONT-FACE-DATA.
05 WFONT-DEVICE HANDLE, VALUE NULL.
88 WFDEVICE-CONSOLE VALUE NULL.
88 WFDEVICE-WIN-PRINTER VALUE 1.
05 WFONT-NAME PIC X(33).
05 WFONT-CHAR-SET PIC X COMP-X.
88 WFCHARSET-DONT-CARE VALUE 0.
88 WFCHARSET-DEFAULT VALUE 1.
88 WFCHARSET-WIN-OEM VALUE 2.
88 WFCHARSET-WIN-SYMBOL VALUE 3.
88 WFCHARSET-WIN-SHIFTJIS VALUE 4.
05 WFONT-SIZE PIC X COMP-X.
05 WFONT-BOLD-STATE PIC X COMP-X.
88 WFONT-BOLD VALUE 1, FALSE 0.
05 WFONT-ITALIC-STATE PIC X COMP-X.
88 WFONT-ITALIC VALUE 1, FALSE 0.
05 WFONT-UNDERLINE-STATE PIC X COMP-X.
88 WFONT-UNDERLINE VALUE 1, FALSE 0.
05 WFONT-STRIKEOUT-STATE PIC X COMP-X.
88 WFONT-STRIKEOUT VALUE 1, FALSE 0.
05 WFONT-PITCH-STATE PIC X COMP-X.
88 WFONT-FIXED-PITCH VALUE 1, FALSE 0.
05 WFONT-FAMILY PIC X COMP-X.
88 WFFAMILY-DONT-CARE VALUE 0.
88 WFFAMILY-MODERN VALUE 1.
88 WFFAMILY-ROMAN VALUE 2.
88 WFFAMILY-SWISS VALUE 3.
88 WFFAMILY-SCRIPT VALUE 4.
88 WFFAMILY-DECORATIVE VALUE 5.
03 WFONT-CHOOSE-DATA.
05 WFONT-CHOOSE-FLAGS PIC X COMP-X.
05 WFONT-CHOOSE-MIN-SIZE PIC X COMP-X.
05 WFONT-CHOOSE-MAX-SIZE PIC X COMP-X.
05 WFONT-CHOOSE-RED PIC X COMP-X.
05 WFONT-CHOOSE-GREEN PIC X COMP-X.
05 WFONT-CHOOSE-BLUE PIC X COMP-X.
05 WFONT-CHOOSE-COLOR-NUM PIC X COMP-X.
WFONT-DATA contains parameters that are used by the various W$FONT operations. The descriptions below detail how each operation uses this data item.
WFONT-STATUS Signed numeric data item
WFONT-STATUS returns the status of the operation. Unless otherwise specified below, a value of "1" indicates success and "0" or a negative value indicates failure.
W$FONT performs a variety of operations depending on the specified OP-CODE. The operations are as follows:
WFONT-SUPPORTED (OP-CODE value "1")
This operation returns a value that indicates whether the host system supports W$FONT. If it does not, WFONT-STATUS is set to WFONTERR-UNSUPPORTED (value "0"). This indicates that the host system does not use fonts (as would be normal for a non-graphical host). A return value of WFONT-FONT-SUPPORT (value "1") indicates that fonts are supported, but the WFONT-CHOOSE-FONT operation is not available. Finally, a value of WFONT-FULL-SUPPORT (value "2") indicates that all W$FONT operations are supported on the system.
The FONT-HANDLE and WFONT-DATA parameters are not used with this op-code and should be omitted.
WFONT-GET-FONT (OP-CODE value "101")
This operation returns a font on the system that matches the specifications in WFONT-DATA. If a matching font is found, its handle is returned in FONT-HANDLE and WFONT-STATUS is set to "1". If no matching font is found, FONT-HANDLE is set to NULL and WFONT-STATUS returns the WFONTERR-FONT-NOT-FOUND error condition.
If you do not specify WFONT-NAME, WFONT-CHAR-SET, or WFONT-SIZE, the corresponding aspect of the font will be arbitrary. In general, you should always specify WFONT-NAME and WFONT-SIZE to get useful results.
WFONT-GET-CLOSEST-FONT (OP-CODE value "102")
This operation is identical to WFONT-GET-FONT, except that it doesn't fail if it cannot find the specified font. Instead, it returns the closest matching font. Note that only Windows systems are capable of performing this operation. On other systems, this call is treated as being identical to WFONT-GET-FONT. You should specify WFONT-CHAR-SET with this function to ensure that the returned font is useful. Also, specifying WFONT-FAMILY can help in locating a suitable font.
WFONT-DESCRIBE-FONT (OP-CODE value "106")
This operation returns the characteristics of the font described by FONT-HANDLE in WFONT-DATA. All of the fields contained in the subgroup WFONT-FACE-DATA are returned, within the capabilities of the host system.
WFONT-CHOOSE-FONT (OP-CODE value "2")
This operation presents the user with a dialog box that allows for the direct selection of a font. If the user cancels the dialog box, W$FONT returns a status of WFONTERR-CANCELLED. Otherwise, W$FONT returns a status of "1" and sets WFONT-FACE-DATA to a description of the chosen font. FONT-HANDLE is not used and should be passed as "NULL". To generate a font handle for the user's choice, take the WFONT-FACE-DATA values returned by this operation and pass them to the WFONT-GET-FONT operation.
Values contained in WFONT-CHOOSE-DATA modify the behavior of the dialog box and return additional information. These fields are described below. You should always INITIALIZE the group item WFONT-DATA prior to filling any fields. This ensures that you have the correct default values for unused fields.
Not all systems that support fonts support this function. See the WFONT-SUPPORTED operation above for details.
WFONT-DATA
The fields of WFONT-DATA are used as follows:
WFONT-DEVICE This item identifies the device that a font is associated with. When a font is associated with a particular device, it should not be used on another device, because these results are undefined. Under Windows, fonts can be shared between devices, but the size is incorrect, because Windows fonts are internally stored with their sizes represented in pixels/device-units instead of points. For example, using a screen font that is 15 pixels high on a laser printer (with 300 or 600 dpi) produces tiny letters. All settings of WFONT-DEVICE are machine-dependent except for the following:
WFDEVICE-CONSOLE This setting (default value "NULL") associates the font with the user's screen.
WFDEVICE-WIN-PRINTER This setting (default value "1") is only meaningful under Windows and Windows NT systems. It associates the font with the currently selected printer for the Windows spooler. If you are using WIN$PRINTER, this item must be set to "true" before you call W$FONT.
WFONT-NAME This item holds the face name of the font. This name is case-sensitive and may contain internal spaces. When asking for a font, you must match its name exactly. If this item is set to spaces, then any font is allowed to match. Under Windows, some common True Type font names are "Courier New", "Times New Roman", and "Arial".
WFONT-CHAR-SET This item defines the character set to use. A font's character set includes the internal representations used for each character. The possible settings are as follows:
WFCHARSET-DONT-CARE This allows for any character set. When returned by a call to WFONT-DESCRIBE-FONT, it indicates that the font's character set is unknown or does not correspond to one of the following settings. When requesting a specific font, use this setting only if you are certain that the face name you are requesting uses the character set you want. This may be necessary when you are asking for a font that uses a character set other than any of the following (as might be true for some oriental character sets).
WFCHARSET-DEFAULT This setting corresponds to a host-dependent default character set. This is the character set most commonly used by the host system. Under Windows, this is the ANSI character set. If you are not certain which setting of WFONT-CHAR-SET to use, use this one.
WFCHARSET-WIN-OEM This setting is meaningful only under Windows. It corresponds to the host hardware's "OEM" character set. For IBM-style PCs, this is the traditional MS-DOS character set. This is the same character set used by the built-in font "TRADITIONAL-FONT".
WFCHARSET-WIN-SYMBOL This setting is meaningful only under Windows. It indicates that the font should contain symbols and special characters.
WFCHARSET-WIN-SHIFTJIS This setting is meaningful only under Windows. It corresponds to the Shift-JIS character set for encoding Japanese characters.
WFONT-SIZE This item holds the size, in points, of the font's characters. A value of zero allows for any size font. In that case, the size chosen by the system may or may not be useful. If you are not certain which size to choose, start with "10" and adjust from there.
WFONT-BOLD When this item is set to TRUE, the font is a boldface font.
WFONT-ITALIC When this item is set to TRUE, the font is italic. Note that under Windows, most controls have difficulty displaying italic fonts correctly.
WFONT-UNDERLINE When this item is set to TRUE, the font is underlined.
WFONT-STRIKEOUT When this item is set to TRUE, the font is struck-out (i.e., has a line running horizontally through the middle of the characters).
WFONT-FIXED-PITCH When this item is set to TRUE, the font is fixed-pitch. This means that each character in the font is the same width.
WFONT-FAMILY This item describes the look of the font in very general terms. It is used to aid in selecting a font when WFONT-NAME is not specified or not found. No font is ever rejected because it does not match the requested family. Usually this field can be set to WFFAMILY-DONT-CARE, but specifying other choices can be useful when you don't know what fonts are on a system and you want to find one close to a specific font. Some graphical systems do not have the concept of font families. On these systems, the value of this field is ignored. The possible values of WFONT-FAMILY are:
WFFAMILY-DONT-CARE This setting allows for any font family. When set by WFONT-DESCRIBE-FONT, it indicates that the font family is unknown or does not match any of the following possibilities.
WFFAMILY-MODERN This setting indicates a font with a constant stroke width. These fonts are typically fixed-pitch, but need not be. Example fonts are "Courier" and "Elite".
WFFAMILY-ROMAN This setting indicates a font with variable stroke width and serifs. Example fonts include "Times Roman" and "New Century Schoolbook".
WFFAMILY-SWISS This setting indicates a font with variable stroke width and no serifs. Example fonts include "Helvetica" and "MS Sans Serif".
WFFAMILY-SCRIPT This setting indicates a font designed to look like handwriting. Example fonts are "Script" and "Comic Sans MS".
WFFAMILY-DECORATIVE This setting indicates a font for decorative or novelty purposes. "Old English" is an example of such a font.
The following fields are part of the subgroup WFONT-CHOOSE-DATA and are used only with the WFONT-CHOOSE-FONT operation.
WFONT-CHOOSE-FLAGS This item modifies the behavior of WFONT-CHOOSE-FONT based on the following settings. You can set any combination of these by adding together the corresponding values (all contained in "fonts.def"):
WFCHOOSE-FIXED-ONLY This setting allows the user to select only a fixed-pitch font. Otherwise, any font can be chosen.
WFCHOOSE-INITIALIZE This setting causes the various fields of the dialog box to be initialized based on the values contained in WFONT-FACE-DATA. Otherwise, the fields will have no initial value.
WFCHOOSE-EFFECTS-OK This setting causes the special-effects section of the dialog box to appear. This section allows the user to select the following traits: underline, strike-out, and color. If it's not set, then this section does not appear in the dialog box.
WFONT-CHOOSE-MIN-SIZE This item, when set to a positive value, specifies the minimum font size (in points) that the user can choose.
WFONT-CHOOSE-MAX-SIZE This item, when set to a positive value, specifies the maximum font size (in points) that the user can choose. When it's set to zero, no maximum is established.
WFONT-CHOOSE-RED This item is used only when the WFCHOOSE-EFFECTS-OK flag is set. It returns the red component of the color chosen. This is a number in the range of "0" to "255". See the W$PALETTE routine for ways to use this value. On systems that do not support palettes, this value is always zero.
WFONT-CHOOSE-GREEN This item is similar to WFONT-CHOOSE-RED, except it returns the green component of the color.
WFONT-CHOOSE-BLUE This item is similar to WFONT-CHOOSE-RED, except it returns the blue component of the color.
WFONT-CHOOSE-COLOR-NUM This item is used only when the WFCHOOSE-EFFECTS-OK flag is set. It returns the ACUCOBOL-GT color number (in the range of "1" to "16") if the color chosen by the user corresponds to a color in the current window's palette. If it does not, then this value is set to zero. Non-zero values can be used directly in the COLOR phrase of a screen item to get the correct color.
Error Handling
The following values are returned by various operations when an error occurs. All error values are less than or equal to zero.
WFONTERR-UNSUPPORTED This error indicates that the current host system does not use fonts and the W$FONT routine is not supported.
WFONTERR-CANCELLED This error indicates that the dialog box used by WFONT-CHOOSE-FONT was canceled by the user.
WFONTERR-FONT-NOT-FOUND This error indicates that no font was found that matched the requested font.
WFONTERR-INVALID-HANDLE This error indicates that the value in FONT-HANDLE does not correspond to an existing font.