[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface : Subroutine Reference

GPQAFC - Inquire Annotation Font Characteristics

GPQAFC (wsid, csid, font, start, num, errind, prec, nomh, nahsf, lahsf, lnfac, lmnfac, lmxfac)

Purpose

Use GPQAFC to inquire information concerning the annotation text capabilities for the specified character set and font on the specified workstation.

The information consists of the highest text precision supported by the specified workstation for the specified csid/ font, the number of supported annotation height scale factors, the nominal character height in Device Coordinates, a list indicating exact supported height scale factors and the number of character expansion factors, minimum expansion factor and maximum expansion factor, corresponding to each height scale factor.

If the inquired information is available, then the graPHIGS API sets the error indicator to zero and returns the values in the output parameters. If the error indicator is 543 (the start value exceeds the extent of the available data), then only the total number (totnum) parameter is set. If the inquired information is unavailable, then the error indicator (errind) contains an error number indicating the reason, and the values returned in the output parameters are unpredictable.

Annotation text capabilities are defined in terms of the following character box description:

 
 
       <----- width ------>  
      
      ---------------------- <------------------ top line
      |                    |                 ^
      |                    |                 |
      |- - - - - - - - - - | <--- cap line   |
      |                    |                 |^  
      |                    |                 | height
      |                    |                 |
      |                    |                 |
      |                    |                 |
      | - - - - - - - - - -| <--- base line  |
      |                    |                 |
      |                    |                 v
      ---------------------- <------------------ bottom line
Height is defined as the distance between the top line and bottom line.

Note:

This subroutine exists to maintain compatibility with previous graPHIGS API releases. Values of returned data are calculated with a different definition of character height than is used by the Inquire Extended Annotation Font Characteristics (GPQXAF) subroutine, and by the Inquire Font Characteristics (GPQFCH) subroutine.

Parameters

wsid -- specified by user, fullword integer

Workstation identifier.

csid -- specified by user, fullword integer

Character set identifier.

See Appendix A. "Character Set and Font Identifiers" for more information.

font -- specified by user, fullword integer

Font identifier (>=1)

start -- specified by user, fullword integer

Starting member of the list of supported height scale factors (>=1)

num -- specified by user, fullword integer

Number of list elements requested (>=0) This number refers to the number of list elements that are returned.

Note:

The four output arrays must be large enough to hold the requested number of elements.

errind -- returned by the graPHIGS API, fullword integer

Error indicator. If the error indicator is zero, the request has been completed. Otherwise, one of the following errors exists:
25
SPECIFIED WORKSTATION DOES NOT EXIST
35
WORKSTATION HAS ONLY INPUT CAPABILITIES
75
TEXT FONT VALUE IS INVALID
538
START VALUE < ONE
539
REQUESTED NUMBER < ZERO
542
CHARACTER SET IDENTIFIER IS INVALID
543
START EXCEEDS DATA EXTENT. TOTAL NUMBER AVAILABLE RETURNED
562
CHARACTER SET/FONT COMBINATION IS NOT AVAILABLE FOR ANNOTATION
571
INQUIRED INFORMATION IS NOT AVAILABLE

prec -- returned by the graPHIGS API, fullword integer

Highest available precision for the corresponding csid/ font (1=STRING_PREC, 2=CHAR_PREC, 3=STROKE_PREC ) If the highest precision supported is stroke, then the following parameters refer to the workstation's capabilities for character precision with annotation text.

nomh -- returned by the graPHIGS API, short floating-point number (DC)

The bottom to top size, (top - bottom), in Device Coordinates (DC) for the nominal height font is returned in this field.

nahsf -- returned by the graPHIGS API, fullword integer

The total number of annotation sizes that are supported. This also defines the number of entries in each of the next four parameter lists except when this value is zero. Zero means that a continuous range of annotation sizes is supported and each of the lists contains two entries.

lahsf -- returned by the graPHIGS API, array of short floating-point numbers

List of the annotation height scale factors that are supported. The first entry is 1.0 10 -30 and the second entry is 9.9 10 30 if the device supports a continuous range of annotation heights.

Note: This list has one entry for each annotation size supported. Its length is determined by the nahsf field except when that contains 0. In this case, this list has two entries. The first entry contains information for the minimum annotation height scale factor. The second contains information for the maximum.

lnfac -- returned by the graPHIGS API, array of fullword intergers

List of numbers of expansion factors that are supported. There is one entry for each of the supported annotation height scale factors. Zero means that a continuous range of expansion factors is supported for the font size.

Note: The length of this list is determined by the nahsf field except when that contains 0. In this case, there are two entries in this list. The first entry contains information for the minimum annotation height scale factor. The second contains information for the maximum.

lmnfac -- returned by the graPHIGS API, array of short floating-point numbers

List of minimum expansion factors that are supported. There is one entry for each of the supported annotation height scale factors. For devices which support all possible expansion factors, there is one entry for each of the supported annotation height scale factors. For devices which support all possible expansion factors, this parameter is a very small positive number (e.g. 10-30 )

Note: The length of this list is determined by thie nahsf field except when that contains 0. In this case, there are two entries in this list. The first entry contains information for the minimum annotation height scale factor. The second contains information for the maximum.

Note: The expansion factor is computed as follows: expf = (W/H) / generic where 'W' and 'H' are the width and height for the font with the corresponding scale factor and generic is the (W/H) ratio for a generic font and has the value 0.86667 (=65/75)

lmxfac -- returned by the graPHIGS API, array of short floating-point numbers

List of maximum expansion factors that are supported. There is one entry for each of the supported annotation height scale factors. For devices which support all possible expansion factors, this parameter should contain a very large positive number (e.g. 9.9 10 30 )

Note: The length of this list is determined by the nahsf field except when that contains 0. In this case, there are two entries in this list. The first entry contains information for the minimum annotation height scale factor. The second contains information for the maximum.

Note: The expansion factor is computed as follows: expf = (W/H) / generic where 'W' and 'H' are the width and height for the font with the corresponding scale factor and generic is the (W/H) ratio for a generic font and has the value 0.86667 (=65/75)

Error Codes

None

Related Subroutines

GPQXAF
Inquire Extended Annotation Font Characteristics

RCP code

201336589 (X'0C00270D')

[ Previous | Next | Contents | Glossary | Home | Search ]