SET ANNOTATION TEXT ALIGNMENT(3P) — SUNPHIGS LIBRARY

NAME

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

SYNOPSIS

C Syntax

void
psetannotationalign ( text_align )
Ptxalign∗text_align;annotation text alignment

FORTRAN Syntax

SUBROUTINE psatal ( TXALH, TXALV )
INTEGERATALHannotation text alignment horizontal
INTEGERATALVannotation text alignment vertical

Required PHIGS Operating States

(PHOP, ∗, STOP, ∗)

DESCRIPTION

Purpose

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

• ANNOTATION TEXT RELATIVE
• ANNOTATION TEXT RELATIVE 3

If the current edit mode is INSERT, a SET ANNOTATION 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, the new SET ANNOTATION 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 Parameter

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

typedef struct {
Ptxhor hor;/∗ horizontal component ∗/
Ptxver ver;/∗ vertical component ∗/
} Ptxalign;

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

PAH_NORMAL“Normal”
PAH_LEFT“Left”
PAH_CENTRE“Center”
PAH_RIGHT“Right”

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

PAV_NORMAL“Normal”
PAV_TOP“Top”
PAV_CAP“Cap”
PAV_HALF“Half”
PAV_BASE“Base”
PAV_BOTTOM“Bottom”

FORTRAN Input Parameters

ATALH
The text alignment horizontal component. This is an enumerated value, and may be one of:

PAHNOR“Normal”
PALEFT“Left”
PACENT“Center”
PARITE“Right”

ATALV
The text alignment vertical component. This is an enumerated value, and may be one of:

PAVNOR“Normal”
PATOP“Top”
PACAP“Cap”
PAHALF“Half”
PABASE“Base”
PABOTT“Bottom”

Execution

When the SET ANNOTATION TEXT ALIGNMENT element is traversed, the “current annotation text alignment” entry in the PHIGS traversal state list is set to annotation text alignment. This attribute is used to position text strings from annotation text output primitives which follow in the structure network, in relation to the “text position” provided with each text output primitive. The horizontal component has 4 values; the vertical component, 6. 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 into 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 “annotation text character up and 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 capline of the string (when the “annotation text path” is “Left” or “Right”), or on the capline of the topmost character in the string (“annotation text path” is “Up” or “Down”). The vertical alignment of “Base” causes the text position to lie on the baseline of the entire string (when the “annotation text path” is “Left” or “Right”) or on the baseline of the bottom character in the string (“annotation text path” is “Up” or “Down”). The vertical alignment of “Half” causes the text position to lie on the halfline of the entire string (when the “annotation text path” is “Left” or “Right”) or on a line midway between the halflines of the top and bottom characters (“annotation text path” is “Up” or “Down”).

The “Normal” value of either annotation 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 “annotation text path” value used:

Annotation Text Path ValueEquivalent (Horizontal, Vertical) Alignment
“Right”(“Left”, “Base”)
“Left”(“Right”, “Base”)
“Up”(“Center”, “Base”)
“Down”(“Center”, “Top”)

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

Example

(“Center”, “Top”) annotation text alignment might be used with annotation 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 annotation 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, ∗)

Museum