'\" t
.\" StrPar.sgm /main/8 1996/09/08 21:06:36 rws $
.de P!
.fl
\!!1 setgray
.fl
\\&.\"
.fl
\!!0 setgray
.fl			\" force out current output buffer
\!!save /psv exch def currentpoint translate 0 0 moveto
\!!/showpage{}def
.fl			\" prolog
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
\!!psv restore
.
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
.TH "XmStringParseText" 3
.SH "NAME"
\fBXmStringParseText\fP \(em A function that converts a character string to a compound string
"XmStringParseText"
"compound string functions" "XmStringParseText"
.SH "SYNOPSIS"
.PP
.nf
#include <Xm/Xm\&.h>
\fBXmString \fBXmStringParseText\fP\fR(
\fBXtPointer \fBtext\fR\fR,
\fBXtPointer *\fBtext_end\fR\fR,
\fBXmStringTag \fBtag\fR\fR,
\fBXmTextType \fBtype\fR\fR,
\fBXmParseTable \fBparse_table\fR\fR,
\fBCardinal \fBparse_count\fR\fR,
\fBXtPointer \fBcall_data\fR\fR);
.fi
.SH "DESCRIPTION"
.PP
\fBXmStringParseText\fP converts characters specified in \fItext\fP to
corresponding components in the returned compound string\&. The
resulting compound string consists of at least one locale or charset
tag component and a series of \fBXmString\fR text components and other
components\&. The conversion proceeds according to the parse information
contained in \fIparse_table\fP\&. See the \fIMotif Programmer\&'s Guide\fP for more information
about parsing and parse tables\&.
.IP "   \(bu" 6
If \fItype\fP is \fBXmCHARSET_TEXT\fP, the associated \fItag\fP is
interpreted as a charset name\&.
If \fItag\fP has a value of NULL, a charset component whose value
is the result of mapping
\fBXmFONTLIST_DEFAULT_TAG\fP
is created\&.
.IP "   \(bu" 6
If \fItype\fP is \fBXmMULTIBYTE_TEXT\fP or \fBXmWIDECHAR_TEXT\fP, the
associated \fItag\fP is interpreted as a language environment name\&.
If \fItag\fP has a value of NULL, a locale component with a value of
\fB_MOTIF_DEFAULT_LOCALE\fP is created\&.
If \fItype\fP is \fBXmMULTIBYTE_TEXT\fP or \fBXmWIDECHAR_TEXT\fP,
\fItag\fP must be NULL or \fB_MOTIF_DEFAULT_LOCALE\fP\&.
.PP
\fBXmStringParseText\fP also scans the string for characters that have
matches in \fIparse_table\fP\&.
Whenever a match is found, the text up to that point is concatenated
with the mapped component\&.
.IP "\fItext\fP" 10
Specifies the NULL-terminated string containing characters of a type
determined by \fItype\fP\&.
This is updated to point to after the last character scanned\&.
.IP "\fItext_end\fP" 10
Specifies a pointer into \fItext\fP\&. If a NULL is supplied to the
\fItext_end\fP parameter, then \fBXmStringParseText\fP parses
\fItext\fP until NULL is encountered, or until it reaches a point in
\fItext\fP
where it is directed to stop
(for example, by a \fBparse_proc\fP)\&. Otherwise, the value supplied
to the \fItext_end\fP parameter is the pointer into \fItext\fP where
parsing is to stop, and the returned character is the one where
parsing did stop\&.
.IP "\fItag\fP" 10
Specifies the tag to be used in creating the result\&.
The type of string tag created (charset or locale) depends on the text
type and the passed in \fItag\fP value\&.
If the \fItag\fP value is NULL and if \fItype\fP indicates that a
charset string tag should be created, the string tag has the value
that is the result of mapping
\fBXmFONTLIST_DEFAULT_TAG\fP\&.
If \fItype\fP indicates a locale string tag, the string tag has the
value \fB_MOTIF_DEFAULT_LOCALE\fP\&.
.IP "\fItype\fP" 10
Specifies the type of text and the tag type\&.
If a locale tag should be created, \fItype\fP has a value of either
\fBXmMULTIBYTE_TEXT\fP or \fBXmWIDECHAR_TEXT\fP\&.
If \fItype\fP has value of
\fBXmCHARSET_TEXT\fP, a charset tag will be created\&.
.IP "\fIparse_table\fP" 10
Specifies the parse table to be used in scanning for characters to be
converted to other compound string components\&.
.IP "\fIparse_count\fP" 10
Specifies the number of entries in \fIparse_table\fP\&.
.IP "\fIcall_data\fP" 10
Specifies data to be passed to the parse procedures\&.
.SH "RETURN"
.PP
Returns a new compound string\&.
The function allocates space to hold the returned compound string\&.
When the application no longer needs the returned compound string,
the application should call \fBXmStringFree\fP\&.
.SH "RELATED"
.PP
\fBXmString\fP(3),
\fBXmStringFree\fP(3), \fBXmParseTable\fP(3), \fBXmParseMapping\fP(3)\&.
.\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:31