.\"##
.\" $XConsortium: p282,v 5.3 94/04/17 20:57:41 hersh Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.TH "SET ANNOTATION TEXT ALIGNMENT" 3P "29 February 1991"
.SH NAME
SET ANNOTATION TEXT ALIGNMENT \- create a structure element to set the \fIcurrent 
text alignment\fP attribute
.IX "Attributes, Text Attributes" "SET ANNOTATION TEXT ALIGNMENT"
.IX "Text Attributes" "SET ANNOTATION TEXT ALIGNMENT"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_anno_align ( text_align )
Ptext_align	*text_align;	\fItext alignment\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET ANNOTATION TEXT ALIGNMENT\s+2 creates a structure element
containing a value for the current annotation text alignment attribute,
which positions the annotation text string in relation to the 
\fIannotation text position\fP.
This attribute applies to the output primitives:
.RS
.sp .2
.nf
\(bu ANNOTATION TEXT RELATIVE
.LP
\(bu ANNOTATION TEXT RELATIVE 3
.RE
.fi
.LP
If the current edit mode is \s-2INSERT\s+2, 
a \s-2SET ANNOTATION TEXT ALIGNMENT\s+2 element is inserted into the 
currently open structure after the element pointed to by the current element 
pointer.  If the edit mode is \s-2REPLACE\s+2, then the new 
\s-2SET ANNOTATION TEXT ALIGNMENT\s+2 element replaces the element pointed 
to by the element pointer.  In either case, the element pointer is updated 
to point to the new element.
.SS C Input Parameter
.IP \fItext_align\fP
A pointer to the \fItext alignment\fP structure, defined as follows:
.sp .2
.nf
.ta .5i +\w'Pvert_align       'u +\w'vert;	'u
typedef struct {
.sp .2
	Phor_text_align	hor;	\fI horizontal component \fP
	Pvert_text_align	vert;	\fI vertical component \fP
.sp .2
} Ptext_align;
.fi
.IP
\fItext_align->hor\fP is the horizontal component.
This is an enumerated value, and may be one of:
.sp .2
.ta .3i +1.2i
.nf
	PHOR_NORM	\fINORMAL\fP
	PHOR_LEFT	\fILEFT\fP
	PHOR_CTR	\fICENTER\fP
	PHOR_RIGHT	\fIRIGHT\fP
.fi
.IP
\fItext_align->vert\fP is the vertical component.
This is an enumerated value, and may be one of:
.sp .2
.nf
	PVERT_NORM	\fINORMAL\fP
	PVERT_TOP		\fITOP\fP
	PVERT_CAP		\fICAP\fP
	PVERT_HALF	\fIHAFL\fP
	PVERT_BASE	\fIBASE\fP
	PVERT_BOTTOM	\fIBOTTOM\fP
.fi
.SS Execution
When the \s-2SET ANNOTATION TEXT ALIGNMENT\s+2 element is traversed,
the current annotation text alignment entry in the traversal state list
is set to annotation text alignment.  
This attribute is used to position text strings
from annotation 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.  
.LP
Imagine first rendering the text string using all other text attributes,
and then moving the entire text string
to place the \fItext extent parallelogram\fP 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 \fIannotation text character up vector\fP and 
the \fIannotation text character base vector\fP.  
(Consider the direction of the character up vector to be vertical
and that of the character base vector to be horizontal.) 
.LP
The horizontal alignment of \s-2LEFT\s+2 or \s-2RIGHT\s+2 requires
the corresponding side of the parallelogram to pass through the text position.   
The horizontal alignment of \s-2CENTER\s+2 causes the text position to lie
midway between the left and right sides of the parallelogram.  
.LP
The vertical alignment corresponds to one of the five 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 \s-2TOP\s+2 or \s-2BOTTOM\s+2 requires the
corresponding side of the parallelogram to pass through the text position.  
The vertical alignment of \s-2CAP\s+2 causes the
text position to lie on the capline of the string
(when the annotation text path is \s-2LEFT\s+2 or \s-2RIGHT\s+2) 
or on the cap line of the topmost character in the string
(when the annotation text path is \s-2UP\s+2 or \s-2DOWN\s+2).  
The vertical alignment of \s-2BASE\s+2 causes the
text position to lie on the base line of the entire string
(when the annotation text path is \s-2LEFT\s+2 or \s-2RIGHT\s+2)
or on the base line of the bottom character in the string
(when annotation text path is \s-2UP\s+2 or \s-2DOWN\s+2).  
The vertical alignment of \s-2HALF\s+2 causes the
text position to lie on the half line of the entire string
(when the annotation text path is \s-2LEFT\s+2 or \s-2RIGHT\s+2) 
or on a line midway
between the half lines of the top and bottom characters
(when annotation text path is \s-2UP\s+2 or \s-2DOWN\s+2).  
.LP
The Normal value of either \fIannotation text alignment\fP component 
causes an effect equivalent to one of the other values of the same component.  
\s-2PHIGS\s+2 defines which other value is used as the natural alignment for 
the annotation text path value used:  
.sp .2
.ta .3i +\w'\fIAnnotation Text Path Value (Space)  \fP'u
.nf
	\fIAnnotation Text Path Value	Equivalent (Horizontal, Vertical) Alignment\fP
.sp .2
	\fRRIGHT\fP	\fILeft, Base\fP
	\fRLEFT\fP	\fIRight, Base\fP
	\fRUP\fP	\fICenter, Base\fP
	\fRDOWN\fP	\fICenter, Top\fP
.fi
.LP
The default annotation text alignment is (\s-2NORMAL\s+2, \s-2NORMAL\s+2);  
the default annotation text path is \s-2RIGHT\s+2.  
.SS Example
.LP
(\s-2CENTER\s+2, \s-2TOP\s+2) annotation text alignment might be used
with annotation text path \s-2RIGHT\s+2 to center a
chart's \fIx-axis\fP label under the \fIx-axis\fP, without
calculating the combined size of the characters in the string.   
(\s-2RIGHT\s+2, \s-2CENTER\s+2) might be used with annotation 
text path \s-2DOWN\s+2 to
center the right edge of a chart's \fIy-axis\fP label along the \fIy-axis\fP.  
Each character faces normally, but the characters in the string
would proceed down the display, to the left of the \fIy-axis\fP.  
.SH ERRORS
.IP 005
Ignoring function, function requires state (\s-2PHOP, *, STOP, *\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
ANNOTATION TEXT RELATIVE 3 (3P)
SET TEXT ALIGNMENT (3P)
.fi