NAME

SET TEXT ALIGNMENT − create a structure element to set the current text alignment attribute

SYNOPSIS

C Syntax

void
pset_text_align ( text_align )
Ptext_align∗text_align;text alignment

Required PHIGS Operating States

(PHOP, ∗, STOP, ∗)

DESCRIPTION

Purpose

SET TEXT ALIGNMENT creates a structure element containing a value for the current text alignment attribute, which positions the text string in relation to the text position.  This attribute applies to the output primitives:

• TEXT

• TEXT 3

If the current edit mode is INSERT, a SET TEXT ALIGNMENT element is inserted into the currently open structure after the element pointed to by the current element pointer.  If the edit mode is REPLACE, then the new SET TEXT ALIGNMENT element replaces the element pointed to by the element pointer.  In either case, the element pointer is updated to point to the new element. 

C Input Parameters

text_align
A pointer to the text alignment structure, defined as follows:

typedef struct {
Phor_text_align  hor; /∗ horizontal component ∗/
Pvert_text_align  vert; /∗ vertical component ∗/
} Ptext_align;

text_align->hor is the horizontal component.  This is an enumerated value, and may be one of:

PHOR_NORMNormal
PHOR_LEFTLeft
PHOR_CTRCenter
PHOR_RIGHTRight

text_align->vert is the vertical component.  This is an enumerated value, and may be one of:

PVERT_NORM Normal
PVERT_TOPTop
PVERT_CAPCap
PVERT_HALFHalf
PVERT_BASEBase
PVERT_BOTTOM Bottom

Execution

When the SET TEXT ALIGNMENT element is traversed, the current text alignment entry in the traversal state list is set to text alignment.  This attribute is used to position text strings from text output primitives that follow in the structure network, in relation to the text position provided with each text output primitive.  The two components of the alignment can be considered individually. 

Imagine first rendering the text string using all other text attributes, and then moving the entire text string to place the text extent parallelogram that surrounds the character bodies in the correct position in relation to the text position.  (The size and shape of the text is entirely specified by the other attributes.)  This movement is oriented by the character up and character base vectors; consider the direction of the character up vector to be vertical, and that of the character base vector to be horizontal. 

The horizontal alignment of Left or Right requires the corresponding side of the parallelogram to pass through the text position.  The horizontal alignment of Center causes the text position to lie midway between the left and right sides of the parallelogram. 

The vertical alignment corresponds to one of the 5 horizontal lines through the definition of a character.  (These lines are in the same location for every character in a single font.)  The vertical alignment of Top or Bottom requires the corresponding side of the parallelogram to pass through the text position.  The vertical alignment of Cap causes the text position to lie on the cap line of the string (when the text path is Left or Right), or on the cap line of the topmost character in the string (text path is Up or Down).  The vertical alignment of Base causes the text position to lie on the base line of the entire string (when the text path is Left or Right) or on the base line of the bottom character in the string (text path is Up or Down).  The vertical alignment of Half causes the text position to lie on the half line of the entire string (when the text path is Left or Right) or on a line midway between the half lines of the top and bottom characters (text path is Up or Down). 

The Normal value of either text alignment component causes an effect equivalent to one of the other values of the same component.  PHIGS defines which other value is used to be the natural alignment for the text path value used:

Text Path ValueEquivalent (Horizontal, Vertical) Alignment
RIGHT(Left, Base)
LEFT(Right, Base)
UP(Center, Base)
DOWN(Center, Top)

The default text alignment is (Normal, Normal); the default text path is Right. 

Example

(Center, Top) text alignment might be used with text path Right to center a chart’s x-axis label under the x-axis, without calculating the combined size of the characters in the string.  (Right, Center) might be used with text path Down to center the right edge of a chart’s y-axis label along the y-axis.  Each character faces normally, but the characters in the string would proceed down the display, to the left of the y-axis. 

ERRORS

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

SEE ALSO

SET TEXT PATH (3P)
SET ANNOTATION TEXT ALIGNMENT (3P)

September 02, 1992