graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPQXAF - Inquire Extended Annotation Font Characteristics

GPQXAF (wsid, csid, font, start, num, errind, prec, nomh, nahsf, lahsf, lnfac, lmnfac, lmxfac, proportional, top, bottom, nomaspect)

Note:

This subroutine is a Workstation State List (WSL) inquiry. For an overview, see "WSL Inquiries"

Purpose

Use GPQXAF to inquire the annotation text capabilities for the requested character set and font on the specified workstation.

This information consists of the highest text precision for this csid/ font that is supported by the specified workstation ( prec), the nominal character height in Device Coordinates (DC) (nomh), the number of supported annotation height scale factors (nahsf), a list indicating the exact supported height scale factors ( lahsf), and the number of character expansion factors (lnfac), minimum expansion (lmnfac) and maximum ( lmxfac) expansion factors corresponding to each height scale factor, whether the font is fixed or proportional (proportional), and ratios describing the character box ( top, bottom, and nomaspect)

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
      |                    |   |
      |                    |   |  
      |                    |   v       
      |- - - - - - - - - - | <--- base line
      |                    |
      |                    |
      ---------------------- <--- bottom line

Height is defined as the distance between the base line and the cap line.

Note:

The definition of height is different from that used by the Inquire Annotation Font Characteristics (GPQAFC) subroutine.

Parameters

wsid -- specified by user, fullword integer

Workstation identifier.

csid -- specified by user, fullword integer

Character set identifier.

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 3=STROKE_PREC , 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 base to cap size, (cap - base), in Device Coordinates (DC) for the nominal height font.

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 values is zero. A value of 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 supported. If the device supports a continuous range of annotation heights, then the first entry is 1.0 [default] 10 (-30) and the second is 9.9 [default] 10 (30)

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

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

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, this parameter is a very small positive number (e.g.10 (-30))

Note: The expansion factor is computed as follows: expf = (W/H) / nomaspect where 'W' and 'H' are the width and the height for that font.

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.

Note:

For devices which support all possible expansion factors, this parameter contains a very large positive number (e.g. 9.9 [default] 10 (30))

Note: The length of this list is determined by the nahsf field except when this 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) / nomaspect where 'W' and 'H' are the width and height for that font.

proportional -- returned by the graPHIGS API, fullword integer

Indicates whether the font definition contains per character positioning information so that proportional spacing can be performed (1=FIXED, 2=PROPORTIONAL )

top -- returned by the graPHIGS API, short floating-point number

Top ratio, (top-cap)/ nomh, is returned in this field (>=0) This is a constant for all sizes of a font.

bottom -- returned by the graPHIGS API, short floating-point number

Bottom ratio, (base-bot)/ nomh, is returned in this field (>=0) This is a constant for all sizes of a font.

nomaspect -- returned by the graPHIGS API, short floating-point number

Aspect ratio, (width/height), of the nominal size font.

Error Codes

None

Related Subroutines

GPAH: Set Annotation Height
GPAHSC: Set Annotation Height Scale Factor
GPQAFC: Inquire Annotation Font Characteristics

RCP code

201336591 ( X'0C00270F')