NAME

       XmbLookupString,  XwcLookupString, Xutf8LookupString - obtain composed input from an input
       method

SYNTAX

       int  XmbLookupString(XIC   ic,   XKeyPressedEvent   *event,   char   *buffer_return,   int
              bytes_buffer, KeySym *keysym_return, Status *status_return);

       int   XwcLookupString(XIC   ic,   XKeyPressedEvent  *event,  wchar_t  *buffer_return,  int
              wchars_buffer, KeySym *keysym_return, Status *status_return);

       int  Xutf8LookupString(XIC  ic,  XKeyPressedEvent   *event,   char   *buffer_return,   int
              bytes_buffer, KeySym *keysym_return, Status *status_return);

ARGUMENTS

       buffer_return
                 Returns  a  multibyte  string  or  wide character string (if any) from the input
                 method.

       bytes_buffer
       wchars_buffer
                 Specifies space available in the return buffer.

       event     Specifies the key event to be used.

       ic        Specifies the input context.

       keysym_return
                 Returns the KeySym computed from the event if this argument is not NULL.

       status_return
                 Returns a value indicating what kind of data is returned.

DESCRIPTION

       The XmbLookupString, XwcLookupString and Xutf8LookupString  functions  return  the  string
       from  the input method specified in the buffer_return argument.  If no string is returned,
       the buffer_return argument is unchanged.

       The KeySym into  which  the  KeyCode  from  the  event  was  mapped  is  returned  in  the
       keysym_return  argument  if it is non-NULL and the status_return argument indicates that a
       KeySym was returned.  If both a string and a KeySym are returned, the  KeySym  value  does
       not necessarily correspond to the string returned.

       XmbLookupString  and  Xutf8LookupString  return  the  length  of  the string in bytes, and
       XwcLookupString returns the length of the string in characters.  Both XmbLookupString  and
       XwcLookupString return text in the encoding of the locale bound to the input method of the
       specified input context, and Xutf8LookupString returns text in UTF-8 encoding.

       Each string returned by XmbLookupString and XwcLookupString begins in the initial state of
       the encoding of the locale (if the encoding of the locale is state-dependent).

       Note:  To  ensure  proper  input  processing,  it  is  essential that the client pass only
       KeyPress events to XmbLookupString, XwcLookupString and Xutf8LookupString.  Their behavior
       when a client passes a KeyRelease event is undefined.

       Clients  should  check  the status_return argument before using the other returned values.
       These three functions each return a value to status_return that indicates  what  has  been
       returned in the other arguments.  The possible values returned are:

       XBufferOverflow   The input string  to  be  returned  is  too
                         large  for the supplied buffer_return.  The
                         required   size    (for    XmbLookupString,
                         Xutf8LookupString     in     bytes;     for
                         XwcLookupString in characters) is  returned
                         as  the  value  of  the  function,  and the
                         contents of buffer_return and keysym_return
                         are not modified.  The client should recall
                         the function with  the  same  event  and  a
                         buffer  of  adequate  size  to  obtain  the
                         string.
       XLookupNone       No consistent input has  been  composed  so
                         far.   The  contents  of  buffer_return and
                         keysym_return are  not  modified,  and  the
                         function returns zero.
       XLookupChars      Some  input  characters have been composed.
                         They  are  placed  in   the   buffer_return
                         argument,   using  the  encoding  described
                         above, and the string length is returned as
                         the  value of the function.  The content of
                         the keysym_return argument is not modified.
       XLookupKeySym     A KeySym has been  returned  instead  of  a
                         string  and  is  returned in keysym_return.
                         The content of the  buffer_return  argument
                         is  not  modified, and the function returns
                         zero.
       XLookupBoth       Both a KeySym and a  string  are  returned;
                         XLookupChars    and   XLookupKeySym   occur
                         simultaneously.

       It does  not  make  any  difference  if  the  input  context  passed  as  an  argument  to
       XmbLookupString,  XwcLookupString and Xutf8LookupString is the one currently in possession
       of the focus or not.  Input may have been composed within an input context before it  lost
       the  focus,  and  that  input  may  be  returned  on  subsequent calls to XmbLookupString,
       XwcLookupString or Xutf8LookupString even though it does not have any more keyboard focus.

       The function Xutf8LookupString is an extension introduced by The XFree86 Project, Inc., in
       their 4.0.2 release.  Its presence is indicated by the macro X_HAVE_UTF8_STRING.

SEE ALSO

       XLookupKeysym(3), Compose(5)
       Xlib - C Language X Interface