.\"##
.\" $XConsortium: p382,v 5.2 94/04/17 20:58:55 rws 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 REPRESENTATION" 3P "29 February 1991"
.SH NAME
SET TEXT REPRESENTATION \- define a text attribute bundle on a workstation
.IX "Fonts" "SET TEXT REPRESENTATION"
.IX "Attribute Representations" "SET TEXT REPRESENTATION"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.5i 3i
.nf
void
pset_text_rep ( ws, index, rep )
Pint	ws;	\fIworkstation identifier\fP
Pint	index;	\fItext bundle index\fP
Ptext_bundle	*rep;	\fItext representation pointer\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET TEXT REPRESENTATION\s+2 defines a bundle of text attributes for
a specified entry in the workstation's text bundle table.  
Depending on the \s-2ASF\s+2 for each of the text attributes,
the bundled attributes may apply to the following primitives:  
.RS
.LP
\(bu
.SM TEXT
.LP
\(bu
.SM "TEXT 3
.LP
\(bu
.SM "ANNOTATION TEXT RELATIVE"
.LP
\(bu
.SM "ANNOTATION TEXT RELATIVE 3"
.RE
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation for which the text
representation is being defined.  
.IP \fIindex\fP
The \fItext index\fP of the entry being defined.  
.IP \fIrep\fP
A pointer to a structure containing the 
attribute values defining the text representation, defined as follows:  
.nf
.ta .5i +\w'Ptext_prec 'u +\w'char_expan;    'u
.sp .2
typedef struct {
.sp .2
	Pint	font;	/* text font */
	Ptext_prec	prec;	/* text precision */
	Pfloat	char_expan;	/* character char_expansion factor */
	Pfloat	char_space;	/* character spacing */
	Pint	colr_ind;	/* text colour index */
.sp .2
} Ptext_bundle;
.sp .2
.fi
.RE
.IP
\fIrep->font\fP is a \fItext font index\fP.
.IP
\fIrep->prec\fP is a \fItext precision\fP enumeration value, one of:
.nf
.ta .5i +2.0i
.sp .2
	PPREC_STRING	\fIString Precision\fP
	PPREC_CHAR	\fICharacter Precision\fP
	PPREC_STROKE	\fIStroke Precision\fP
.sp .2
.fi
.RE
.IP
\fIrep->char_expan\fP is the \fIcharacter expansion factor\fP value.
.IP
\fIrep->char_space\fP is the \fIcharacter spacing factor\fP value.
.IP
\fIrep->colr_ind\fP is the \fItext colour\fP,
which selects a colour value from the workstation's colour table.
.SS Execution
When \s-2SET TEXT REPRESENTATION\s+2 is called, the text index entry in
the table of defined text representations on the workstation is set
to the text font index, text precision, character expansion factor, 
character spacing factor, and text colour values.  
.LP
When text output primitives are displayed, the text
representation specified by the current text index entry in the
traversal state list provides the text attributes
for which the Aspect Source Flag (\s-2ASF\s+2) is \s-2BUNDLED\s+2.  
For example, when the current text font \s-2ASF\s+2 is set to \s-2BUNDLED\s+2,
the effective text font is
the text font attribute in the text representation selected by
the current text index.  The current text index
is set by \s-2SET TEXT INDEX\s+2 structure elements.  
.\"PHIGS+:	.LP
.\"PHIGS+:	The source for text colour is determined by a combination
.\"PHIGS+:	of the text Colour Source Flag (CSF) and the text colour
.\"PHIGS+:	index ASF. While the text CSF is set to \s-2DIRECT\s+2,
.\"PHIGS+:	text colour is determined by a direct colour specification
.\"PHIGS+:	set with the \s-2SET TEXT COLOUR\s+2 subroutine, and the
.\"PHIGS+:	text colour index ASF has no effect. When the text
.\"PHIGS+:	colour CSF is set to \s-2INDEXED\s+2, the text colour
.\"PHIGS+:	index ASF determines whether the attribute is defined by a
.\"PHIGS+:	bundled or individual specification in the same way as the
.\"PHIGS+:	other attributes.
.LP
The text precision specifies the level of precision
used to draw the text characters in relation to the font definition
and applicable text attributes.  
.LP
The character expansion factor is used to scale the standard width
of the characters established by the width-to-height ratio specified by
the font design.  An expansion factor of less than one produces narrower
characters;  an expansion factor of greater than one produces wider
characters, relative to their height.  
.LP
The character spacing factor is specified as a fraction of the
current character height.  A positive value inserts additional space
between adjacent character bodies in the text string;  a negative value
causes the adjacent character bodies to overlap.  The default value is 0.0,
so the character bodies are placed adjacent to one another
with no additional space beyond that already in the font's design.  
.LP
The text bundle table is numbered from 1.
.SH ERRORS
.IP 003
Ignoring function, function requires state 
(\s-2PHOP\s+2, \s-2WSOP\s+2, \s-2*\s+2, \s-2*\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 059
Ignoring function, the specified workstation does not have output capability
(that is, the workstation category is neither 
\s-2OUTPUT\s+2, \s-2OUTIN\s+2, nor \s-2MO\s+2)
.IP 100
Ignoring function, the bundle index value is less than one
.IP 103
Ignoring function, setting this bundle table entry would exceed
the maximum number of entries allowed in the workstation bundle table
.IP 106
Ignoring function, the specified font is not available
for the requested text precision on the specified workstation
.IP 113
Ignoring function, the colour index value is less than zero
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET TEXT INDEX (3P)"
.SM "SET INDIVIDUAL ASF (3P)"
.SM "INQUIRE TEXT REPRESENTATION (3P)"
.SM "INQUIRE TEXT REPRESENTATION PLUS (3P+)"
.SM "INQUIRE TEXT FACILITIES (3P)"
.SM "SET TEXT FONT (3P)"
.SM "SET TEXT PRECISION (3P)"
.SM "SET CHARACTER EXPANSION FACTOR (3P)"
.SM "SET CHARACTER SPACING (3P)"
.SM "SET TEXT COLOUR (3P+)"
.SM "SET TEXT COLOUR INDEX (3P)"
.SM "SET TEXT REPRESENTATION PLUS (3P+)"
.fi