XmStringParseText(3X)

     NAME
          XmStringParseText - A function that converts a character
          string to a compound string

     SYNOPSIS
          #include <Xm/Xm.h>
          XmString XmStringParseText(
          XtPointer text,
          XtPointer *text_end,
          XmStringTag tag,
          XmTextType type,
          XmParseTable parse_table,
          Cardinal parse_count,
          XtPointer call_data);

     VERSION
          This page documents Motif 2.1.

     DESCRIPTION
          XmStringParseText converts characters specified in text 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 XmString
          text components and other components. The conversion
          proceeds according to the parse information contained in
          parse_table. See the Motif Programmer's Guide for more
          information about parsing and parse tables.

             o  If type is XmCHARSET_TEXT, the associated tag is
                interpreted as a charset name.  If tag has a value of
                NULL, a charset component whose value is the result of
                mapping XmFONTLIST_DEFAULT_TAGis created.

             o  If type is XmMULTIBYTE_TEXT or XmWIDECHAR_TEXT, the
                associated tag is interpreted as a language
                environment name.  If tag has a value of NULL, a
                locale component with a value of _MOTIF_DEFAULT_LOCALE
                is created.  If type is XmMULTIBYTE_TEXT or
                XmWIDECHAR_TEXT, tag must be NULL or
                _MOTIF_DEFAULT_LOCALE.

          XmStringParseText also scans the string for characters that
          have matches in parse_table.  Whenever a match is found, the
          text up to that point is concatenated with the mapped
          component.

          text      Specifies the NULL-terminated string containing
                    characters of a type determined by type.  This is
                    updated to point to after the last character
                    scanned.

          text_end  Specifies a pointer into text. If a NULL is
                    supplied to the text_end parameter, then
                    XmStringParseText parses text until NULL is
                    encountered, or until it reaches a point in
                    textwhere it is directed to stop (for example, by
                    a parse_proc). Otherwise, the value supplied to
                    the text_end parameter is the pointer into text
                    where parsing is to stop, and the returned
                    character is the one where parsing did stop.

          tag       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 tag value.  If the tag value is NULL and if
                    type indicates that a charset string tag should be
                    created, the string tag has the value that is the
                    result of mapping XmFONTLIST_DEFAULT_TAG.  If type
                    indicates a locale string tag, the string tag has
                    the value _MOTIF_DEFAULT_LOCALE.

          type      Specifies the type of text and the tag type.  If a
                    locale tag should be created, type has a value of
                    either XmMULTIBYTE_TEXT or XmWIDECHAR_TEXT.  If
                    type has value of XmCHARSET_TEXT, a charset tag
                    will be created.

          parse_table
                    Specifies the parse table to be used in scanning
                    for characters to be converted to other compound
                    string components.

          parse_count
                    Specifies the number of entries in parse_table.

          call_data Specifies data to be passed to the parse
                    procedures.

     RETURN
          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 XmStringFree.

     RELATED
          XmString(3), XmStringFree(3), XmParseTable(3),
          XmParseMapping(3).