.\" @(#)PEXQueryTextExtents.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXQueryTextExtents 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXQueryTextExtents - Query Text Extents
.SH SYNTAX
.HP
PEXTextExtent *PEXQueryTextExtents\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, unsigned int \fIfont_table_index\fP\^, int \fIpath\fP\^, double \fIexpansion\fP\^, double \fIspacing\fP\^, double \fIheight\fP\^, int \fIhalign\fP\^,
int \fIvalign\fP\^, unsigned long \fIcount\fP\^, PEXStringData *\fItext\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIresource_id\fP 1i
The resource identifier of either a renderer, a workstation or a text font
table.
.IP \fIfont_table_index\fP 1i
The text font table index.
.IP \fIpath\fP 1i
The text path (
.B PEXPathRight,
.B PEXPathLeft,
.B PEXPathUp,
.B PEXPathDown
).
.IP \fIexpansion\fP 1i
The text character expansion factor.
.IP \fIspacing\fP 1i
The text character spacing factor.
.IP \fIheight\fP 1i
The text character height.
.IP \fIhalign\fP 1i
The text horizontal text alignment (
.B PEXHAlignNormal,
.B PEXHAlignLeft,
.B PEXHAlignCenter,
.B PEXHAlignRight
).
.IP \fIvalign\fP 1i
The text vertical text alignment (
.B PEXVAlignNormal,
.B PEXVAlignTop,
.B PEXVAlignCap,
.B PEXVAlignHalf,
.B PEXVAlignBase,
.B PEXVAlignBottom).
.IP \fIcount\fP 1i
The number of text strings.
.IP \fItext\fP 1i
An array of text strings.
.SH RETURNS
.LP
An array of text extents; a null pointer if unsuccessful.
.SH DESCRIPTION
.\" indexing
.IX PEXQueryTextExtents
.LP
This function returns the text extents, in the local 2D text coordinate system,
of each specified text string.
If the resource identifier is a renderer or PHIGS workstation, then the
text font table associated with the renderer or workstation is used.
If the resource identifier is a text font lookup table,
it is used directly.  The specified font group
provides the index of the entry that is to be used to obtain the
font group.  The first character set in the font will be used.
.LP
Stroke precision is assumed.  The text position is (0,0) in
the local 2D text coordinate system.
The extent of each string is computed independent of the other strings.
.LP
If a specified font has no defined default glyph, then undefined glyphs
are taken to have all zero metrics.
.LP
The extent data is returned in memory allocated by PEXlib.
.B XFree
should be called to deallocate the memory.
.SH DATA STRUCTURES
.LP
.nf
typedef struct {
	unsigned short		length;
	char			*ch;
.br
} PEXStringData;
.sp
typedef struct {
	PEXCoord2D		lower_left;
	PEXCoord2D		upper_right;
	PEXCoord2D		concat_point;
.br
} PEXTextExtent;
.sp
typedef struct {
	float	x;
	float	y;
.br
} PEXCoord2D;
.fi
.SH ERRORS
.TP
.SB BadMatch
The specified resource identifier identifies a table of type other than a
text font table.
.TP
.SB BadValue
A specified value for one or more text attributes is invalid, or the specified
resource identifier does not identify a valid renderer, workstation or
lookup table resource.
.SH SEE ALSO
.LP
.nf
.BR PEXQueryEncodedTextExtents (3)
.fi