XwcLookupString()														 XwcLookupString()

Name
  XwcLookupString - obtain composed wide-character input from an input method.

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

Arguments
  ic	       Specifies the input context.

  event        Specifies the keypress event to be used.

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

  wchars_buffer
	       Specifies the number of wide-characters in return buffer.

  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.

Returns
  The length, in wide characters, of the string returned in buffer_return, if any.

Availability
  Release 5 and later.

Description
  XwcLookupString()  passes a KeyPress event to an input context, returns composed text in the encoding of the locale of the input context if
  any is ready, and may return a keysym corresponding to the KeyPress event as well.

  There are several possible results of a call to XwcLookupString(), and a client should check the value returned in the status_return	argu-
  ment to determine which has occured.	The possible values are:

  XBufferOverflow
	    The input string to be returned is too large for the supplied buffer_return.  The required size in wide characters is returned as
	    the value of the function, and the contents of buffer_return and keysym_return are not modified.  The client should  re-call  the
	    function with the same event and a buffer of adequate size in order 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,  and	the  string  length  in  wide
	    characters	is  returned  as  the  value  of  the function.  The string is encoded in the locale bound to the input context.  The
	    contents 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 contents 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.

  When	XwcLookupString() returns a string, the return value of the function is the length, in wide characters, of that string.  The returned
  string is a wide-character string in the encoding of the locale of the input context.  If that  encoding  is	state-dependent,  the  string
  begins in the initial state of the encoding.

  When	both a keysym and a string are returned, the string does not necessarily correspond to the keysym.  An application that is not inter-
  ested in return keysyms can pass a NULL keysym_return

  Note that only KeyPress events should be passed to XwcLookupString().  When KeyRelease events are passed, the resulting behavior  is	unde-
  fined.   It  does  not make any difference if the input context passed as an argument to XmbLookupString() and XwcLookupString() 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() or XwcLookupString(), even though it no longer has any more keyboard focus.

See Also
  XLookupKeysym(), XmbLookupString().

Xlib - Internationalized Text Input												 XwcLookupString()