NAME

INQUIRE TEXT EXTENT − determine the extent rectangle for a text string

SYNOPSIS

C Syntax

void
pinq_text_extent ( wst, font, exp, sp, ht, path, hor, ver, str, error_ind, rect, offset )
Pintwst;workstation type
Pintfont;text font
Pfloatexp;char expansion factor
Pfloatsp;char spacing
Pfloatht;char height
Ptext_pathpath;text path
Phor_text_alignhor; horizontal alignment
Pvert_text_alignver; vertical alignment
char∗str;text string
Pint∗error_ind;OUT error indicator
Prect∗rect;OUT extent rectangle
Ppoint∗offset;OUT concatenation offset

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

INQUIRE TEXT EXTENT calculates the extent (bounding rectangle) and concatenation offset for a specified text string and set of PHIGS text attributes. 

C Input Parameters

wstThe workstation type to use to resolve the font. 

fontThe text font, specified as an index to the workstation’s non-writable table of available fonts.  All the font indices have named constants defined in phigs.h, as shown below. 

The fonts available for PCS_ASCII are:

ConstantValue
PFONT_MONO 1

expA real value specifying the character expansion factor. 

spThe character spacing, specified as a real fraction of the font’s nominal character height. 

htA real value specifying the character height. 

pathThe text path is one of the following enumerated values:

typedef enum {
PPATH_RIGHT,    /∗ Right ∗/
PPATH_LEFT,   /∗ Left ∗/
PPATH_UP,   /∗ Up ∗/
PPATH_DOWN   /∗ Down ∗/
} Ptext_path;

horThe horizontal alignment.  This is an enumerated value defined in phigs.h, and may be one of:

typedef enum {
PHOR_NORM,/∗ Normal ∗/
PHOR_LEFT,/∗ Left ∗/
PHOR_CTR,/∗ Center ∗/
PHOR_RIGHT/∗ Right ∗/
} Phor_text_align;

verThe vertical alignment.  This is an enumerated value defined in phigs.h, and may be one of:

typedef enum {
PVERT_NORM, /∗ Normal ∗/
PVERT_TOP,/∗ Top ∗/
PVERT_CAP,/∗ Cap ∗/
PVERT_HALF,/∗ Half ∗/
PVERT_BASE,/∗ Base ∗/
PVERT_BOTTOM, /∗ Bottom ∗/
} Pvert_text_align;

strA pointer to the text string. 

C Output Parameters

error_ind
A pointer to the location to store the error number of any error detected by this function.

rectA pointer to a Prect structure in which to return the text extent.  Prect is defined in phigs.h as:

typedef struct {
Ppointp;/∗ point p ∗/
Ppointq;/∗ point q ∗/
} Prect;

Ppoint is defined in phigs.h as:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
} Ppoint;

offsetA pointer to a Ppoint structure in which to return the concatenation offset.  See the Execution section below for its meaning. 

Execution

The extent of the specified character string in the local 2D text coordinate system is computed using the specified text attributes for the specified workstation type.  STROKE precision is assumed.  The text position is (0,0) in the text local coordinate system.  See TEXT 3 for a description of the text local coordinate system and how it is defined.  The text extent encloses the entire text string with the specified attributes applied. 

The concatenation offset indicates the text position for the concatenation of a subsequent text output primitive in the local 2D text coordinate system.  This includes, for TEXT PATHs RIGHT and LEFT, an adjustment to account for the intercharacter spacing of the last character as specified by the character spacing parameter.  It will be necessary for the application to apply a suitable modelling transformation to account for the CHARACTER UP VECTOR if it is other than the default. 

If an error is detected by this function the error indicator will indicate the error number of the error detected and no other output data will be returned.  If no error is detected, the error indicator will be set to zero and the inquired information will be available in the output parameters.  Since this is an inquiry function, ERROR HANDLING is not invoked when an error is detected by this function. 

ERRORS

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

051Ignoring function, this information is not yet available for this generic workstation type; open a workstation of this type and use the specific workstation type

052Ignoring function, workstation type not recognized by the implementation type

062Ignoring function, this information is not available for this MO workstation type

106Ignoring function, the specified font is not available for the requested text precision on the specified workstation

SEE ALSO

TEXT (3P)
ANNOTATION TEXT RELATIVE (3P)

September 02, 1992