XmbLookupString() XmbLookupString()
Name
XmbLookupString - obtain composed multi-byte input from an input method.
Synopsis
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;
Arguments
ic Specifies the input context.
event Specifies the keypress event to be used.
buffer_return
Returns a multibyte string (if any) from the input method.
bytes_buffer
Specifies the number of bytes in the 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
Number of characters in the string in bytes_buffer.
Availability
Release 5 and later.
Description
XmbLookupString() 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 XmbLookupString(), and a client should check the value returned in the status_return argu-
ment to determine which has occurred. The possible values are:
XBufferOverflow
The input string to be returned is too large for the supplied buffer_return. The required size in bytes 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 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 XmbLookupString() returns a string, the return value of the function is the length in bytes of that string. The returned string is a
multi-byte string in the encoding of the locale of the input context. If that encoding is state-dependent, the string begins in the ini-
tial 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 XmbLookupString(). 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() 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 sub-
sequent calls to XmbLookupString() even though it no longer has any more keyboard focus.
See Also
XLookupKeysym(), XwcLookupString().
Xlib - Internationalized Text Input XmbLookupString()
