.\"##
.\" $XConsortium: p216,v 5.3 94/04/17 20:56:56 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.
.ds f \s-2INQUIRE TEXT EXTENT\s+2
.TH "INQUIRE TEXT EXTENT" 3P "29 February 1991"
.SH NAME
INQUIRE TEXT EXTENT \- determine the extent rectangle for a text string
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pinq_text_extent ( wst, font, exp, sp, ht, path, hor, ver, str, error_ind, rect, offset )
Pint	wst;	\fIworkstation type\fP
Pint	font;	\fItext font\fP
Pfloat	exp;	\fIchar expansion factor\fP
Pfloat	sp;	\fIchar spacing\fP
Pfloat	ht;	\fIchar height\fP
Ptext_path	path;	\fItext path\fP
Phor_text_align	hor;	\fIhorizontal alignment\fP
Pvert_text_align	ver;	\fIvertical alignment\fP
char	*str;	\fItext string\fP
Pint	*error_ind;	\fIOUT error indicator\fP
Prect	*rect;	\fIOUT extent rectangle\fP
Ppoint	*offset;	\fIOUT concatenation offset\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
\*f calculates the extent (bounding rectangle) and concatenation offset for
a specified text string and set of \s-2PHIGS\s+2 text attributes.
.SS C Input Parameters
.IP \fIwst\fP
The workstation type to use to resolve the font.
.IP \fIfont\fP
The \fItext font\fP, specified as an index to the workstation's non-writable
table of available fonts.  
All the font indices have named constants defined in phigs.h,
as shown below.
.IP
The fonts available for \s-2PCS_ASCII\s+2 are:
.ta .5i +1i
.nf
	Constant	Value
.sp .3
	PFONT_MONO	1
.fi
.IP \fIexp\fP
A real value specifying the character expansion factor.
.IP \fIsp\fP
The character spacing, specified as a real
fraction of the font's nominal character height.
.IP \fIht\fP
A real value specifying the character height.
.IP \fIpath\fP
The text path is one of the following enumerated values:
.ta .5i +1.25i
.nf
.sp .4
typedef enum {
.sp .2
	PPATH_RIGHT,	   /* Right */
	PPATH_LEFT,	   /* Left */
	PPATH_UP,	   /* Up */
	PPATH_DOWN	   /* Down */
.sp .2
} Ptext_path;
.fi
.bp
.IP \fIhor\fP
The horizontal alignment.  This is an enumerated value defined in 
phigs.h, and may be one of:  
.ta .5i +1.25i
.nf
.sp .4
typedef enum {
.sp .2
	PHOR_NORM,	/* Normal */
	PHOR_LEFT,	/* Left */
	PHOR_CTR,	/* Center */
	PHOR_RIGHT	/* Right */
.sp .2
} Phor_text_align;
.fi
.IP \fIver\fP
The vertical alignment.  This is an enumerated value
defined in phigs.h, and may be one of:
.ta .5i +1.25i
.nf
.sp .4
typedef enum {
.sp .2
	PVERT_NORM,	/* Normal */
	PVERT_TOP,	/* Top */
	PVERT_CAP,	/* Cap */
	PVERT_HALF,	/* Half */
	PVERT_BASE,	/* Base */
	PVERT_BOTTOM,	/* Bottom */
.sp .2
} Pvert_text_align;
.fi
.IP \fIstr\fP
A pointer to the text string.
.SS C Output Parameters
.IP \fIerror_ind\fP
A pointer to the location to store the error number of any error detected by this function.
.IP \fIrect\fP
A pointer to a Prect structure in which to return the text extent.
Prect is defined in phigs.h as:
.sp .2
.ta .5i +\w'Ppoint	'u +\w'q;	'u
.nf
typedef struct {
.sp .2
	Ppoint	p;	/* point p */
	Ppoint	q;	/* point q */
.sp .2
} Prect;
.fi
.sp
Ppoint is defined in phigs.h as:
.sp .2
.ta .5i +\w'Pfloat	'u +\w'x;	'u
.nf
typedef struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
.sp .2
} Ppoint;
.fi
.IP \fIoffset\fP
A pointer to a Ppoint structure in which to return the concatenation offset.
See the \fIExecution\fP section below for its meaning.
.SS Execution
The extent of the specified character string in the local \s-2\&2D\s+2 text
coordinate system is computed using the specified text attributes for the
specified workstation type.  \s-2STROKE\s+2 precision is assumed.  The text
position is (0,0) in the text local coordinate system.  See \s-2TEXT 3\s+2
for a description of the text local coordinate system and how it is
defined.  The text extent encloses the entire text string with the
specified attributes applied.
.LP
The concatenation offset indicates the text position
for the concatenation of a subsequent text output primitive in the local 
\s-2\&2D\s+2
text coordinate system.  This includes, for \s-2TEXT PATH\s+2s
\s-2RIGHT\s+2 and \s-2LEFT\s+2, an adjustment to account for the
intercharacter spacing of the last character as specified by the character
spacing parameter.  It will be necessary for the application to apply a
suitable modelling transformation to account for the
\s-2CHARACTER UP VECTOR\s+2 if it is other than the default.
.LP
If an error is detected by this function the \fIerror indicator\fP will
indicate the error number of the error detected and no other output data
will be returned.  If no error is detected, the \fIerror indicator\fP will
be set to zero and the inquired information will be available in the output
parameters.  Since this is an inquiry function, \s-2ERROR HANDLING\s+2 is not
invoked when an error is detected by this function.
.SH ERRORS
.IP 002
Ignoring function, function requires state 
(\s-2PHOP\s+2, \s-2*\s+2, \s-2*\s+2, \s-2*\s+2)
.IP 051
Ignoring function, this information is
not yet available for this generic
workstation type; open a workstation of
this type and use the specific
workstation type
.IP 052
Ignoring function, workstation type not recognized by the implementation
type
.IP 062
Ignoring function, this information is not available for this
\s-2MO\s+2 workstation type
.IP 106
Ignoring function, the specified font is not available
for the requested text precision on the specified workstation
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "TEXT (3P)"
.SM "ANNOTATION TEXT RELATIVE (3P)"
.fi