.\"##
.\" $XConsortium: p375,v 5.3 94/04/17 20:58:49 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 TEXT ALIGNMENT" 3P "29 February 1991"
.SH NAME
SET TEXT ALIGNMENT \- create a structure element to set the current text alignment attribute
.IX "Text Attributes" "SET TEXT ALIGNMENT"
.IX "Attributes, Text Attributes" "SET TEXT ALIGNMENT"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.5i 3i
.nf
void
pset_text_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 TEXT ALIGNMENT\s+2 creates a structure element
containing a value for the \fIcurrent text alignment\fP attribute,
which positions the text string in relation to the \fItext position\fP.  
This attribute applies to the output primitives:  
.sp .2
.RS
.LP
\(bu
.SM TEXT
.LP
\(bu
.SM "TEXT 3"
.RE
.LP
If the current edit mode is \s-2INSERT\s+2,
a \s-2SET 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 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 Parameters
.IP \fItext_align\fP
A pointer to the \fItext alignment\fP structure, defined as follows:
.sp .2
.nf
.ta .5i +\w'Pvert_slign  'u +\w'vert;    'u
typedef struct {
.sp .2
	Phor_text_align	 hor;		/* horizontal component */
	Pvert_text_align	 vert;		/* vertical component */
.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	\fIHalf\fP
	PVERT_BASE	\fIBase\fP
	PVERT_BOTTOM	\fIBottom\fP
.fi
.SS Execution
When the \s-2SET TEXT ALIGNMENT\s+2 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.  
.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
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 \fIcharacter up\fR and \fIcharacter base\fR vectors;  
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 \fILeft\fP or \fIRight\fP requires
the corresponding side of the parallelogram to pass through the text position.
The horizontal alignment of \fICenter\fP 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 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 \fITop\fP or \fIBottom\fP requires the
corresponding side of the parallelogram to pass through the text position.
The vertical alignment of \fICap\fP causes the
text position to lie on the cap line of the string
(when the text path is \fILeft\fP or \fIRight\fP),
or on the cap line of the topmost character in the string
(text path is \fIUp\fP or \fIDown\fP).
The vertical alignment of \fIBase\fP causes the
text position to lie on the base line of the entire string
(when the text path is \fILeft\fP or \fIRight\fP)
or on the base line of the bottom character in the string
(text path is \fIUp\fP or \fIDown\fP).
The vertical alignment of \fIHalf\fP causes the
text position to lie on the half line of the entire string
(when the text path is \fILeft\fP or \fIRight\fP) or on a line midway
between the half lines of the top and bottom characters
(text path is \fIUp\fP or \fIDown\fP).
.LP
The Normal value of either text alignment 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 to be the
natural alignment for the text path value used:
.sp .2
.ta .3i +\w'\fIText Path Value (Space)  \fP'u
.nf
	\fIText Path Value	Equivalent (Horizontal, Vertical) Alignment\fP
.sp .2
	RIGHT	(\fILeft\fP, \fIBase\fP)
	LEFT	(\fIRight\fP, \fIBase\fP)
	UP	(\fICenter\fP, \fIBase\fP)
	DOWN	(\fICenter\fP, \fITop\fP)
.fi
.LP
The default \fItext alignment\fP is (\fINormal\fP, \fINormal\fP);
the default text path is \fIRight\fP.
.SS Example
.LP
(\fICenter\fP, \fITop\fP) text alignment might be used
with text path \fIRight\fP 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.
(\fIRight\fP, \fICenter\fP) might be used with text path \fIDown\fP 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\s+2, \s-2*\s+2, \s-2STOP\s+2, \s-2*\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET TEXT PATH (3P)"
.SM "SET ANNOTATION TEXT ALIGNMENT (3P)"
.fi