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()
