XmbLookupString(3X11)	       XLIB FUNCTIONS		XmbLookupString(3X11)



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

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

  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

  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 and XwcLookupString 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 returns the length of the string in bytes, and XwcLookup-
  String returns the length of the string in characters.  Both XmbLookup-
  String and XwcLookupString return text in the encoding of the locale bound
  to the input method of the specified input context.

  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 insure proper input processing, it is essential that the
       client pass only KeyPress events to XmbLookupString and XwcLook-
       upString.  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 two functions both return a value to status_return
  that indicates what has been returned in the other arguments.	 The possible
  values returned are: lw(1.5i) lw(4.3i).  T{ XBufferOverflow T}      T{ The
  input string to be returned is too large for the supplied buffer_return.
  The required size (XmbLookupString in bytes; 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.  T}
  T{ XLookupNone T}	 T{ No consistent input has been composed so far.
  The contents of buffer_return and keysym_return are not modified, and the
  function returns zero.  T} T{ XLookupChars T}	     T{ Some input characters
  have been composed.  They are placed in the buffer_return argument, and the
  string length is returned as the value of the function.  The string is
  encoded in the locale bound to the input context.  The content of the
  keysym_return argument is not modified.  T} T{ XLookupKeySym T}      T{ 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.  T} T{ XLookupBoth T}	    T{ Both a KeySym
  and a string are returned; XLookupChars and XLookupKeySym occur simultane-
  ously.  T}

  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 does not have
  any more keyboard focus.

SEE ALSO
  XLookupKeysym(3X11)
  Xlib - C Language X Interface