NAME

TEXT − create structure element specifying 2D text primitive

SYNOPSIS

C Syntax

void
ptext ( text_pt, text )
Ppoint∗text_pt;text point
char∗text;text string

Required PHIGS Operating States

(PHOP, ∗, STOP, ∗)

DESCRIPTION

Purpose

The TEXT subroutine puts a structure element containing the full specification of a two-dimensional TEXT primitive into the currently open structure. 

The TEXT primitive is a character string. The location of the string in the display is controlled by the text point subroutine parameter, specified in Modelling Coordinates.  The z coordinate is assumed to be 0.  Aspects of the text display, such as the font, colour, spacing, height, and alignment, are controlled by the current values of the primitive attributes listed below. 

If the current edit mode is INSERT, the structure element created by the TEXT subroutine is inserted into the open structure after the element pointed to by the current element pointer.  If the current edit mode is REPLACE, the new TEXT element replaces the element in the structure pointed to by the element pointer.  In either case, the element pointer is updated to point to the new TEXT element. 

C Input Parameters

text_pt
A pointer to a Ppoint structure containing the x and y coordinates that locate the text string.  The Ppoint structure is defined in phigs.h as follows:

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

textA pointer to the character string to be written into the display. 

Execution

When the structure is traversed, the TEXT element draws the specified character string.  The position of the text is defined in relation to text point by the current values of the text primitive attributes CHARACTER UP VECTOR, TEXT PATH, and TEXT ALIGNMENT. 

Other aspects of the appearance of the text are controlled by the attributes TEXT FONT, TEXT PRECISION, CHARACTER HEIGHT, CHARACTER WIDTH, CHARACTER EXPANSION FACTOR, CHARACTER SPACING, and TEXT COLOUR INDEX. 

The text point is specified in Modelling Coordinates.  The text primitive is subject to the current transformations in the transformation pipeline from the Modelling Coordinate System to the workstation display. 

Attributes Applied

The attributes listed below are used to display the TEXT primitive when the structure is traversed. The Aspect Source Flags (ASFs) tell where to access the output display attributes.  These attributes can come directly from the traversal state list, or they can be accessed indirectly, using the appropriate index in the traversal state list and the corresponding bundled representation in the PHIGS workstation state list. 

text fonttext font ASF
text precisiontext precision ASF
character expansion factorcharacter expansion factor ASF
character spacingcharacter spacing ASF
text colourtext colour index ASF
character height
character up vector
text path
text alignment
text index
depth cue index
name set

ERRORS

005Ignoring function, function requires state (PHOP, ∗, STOP, ∗)

SEE ALSO

INQUIRE TEXT FACILITIES (3P)
INQUIRE TEXT EXTENT (3P)
TEXT 3 (3P)

September 02, 1992