XLookupString

Syntax

int XLookupString(event_struct, buffer_return, bytes_buffer, keysym_return, status_in_out)
      XKeyEvent *event_struct;
      char *buffer_return;
      int bytes_buffer;
      KeySym *keysym_return;
      XComposeStatus *status_in_out;

Arguments

event_struct Specifies the key event structure to be used. You can pass XKeyPressedEvent or XKeyReleasedEvent .
buffer_return Returns the translated characters.
bytes_buffer Specifies the length of the buffer. No more than bytes_buffer of translation are returned.
keysym_return Returns the KeySym computed from the event if this argument is not NULL.
status_in_out Specifies or returns the XComposeStatus structure or NULL.

Description

The XLookupString() function translates a key event to a KeySym and a string. The KeySym is obtained by using the standard interpretation of the Shift, Lock, group, and numlock modifiers as defined in the X Protocol specification. If the KeySym has been rebound (see XRebindKeysym()), the bound string will be stored in the buffer. Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character or (if the Control modifier is on) to an ASCII control character, and that character is stored in the buffer. XLookupString() returns the number of characters that are stored in the buffer.

If present (non-NULL), the XComposeStatus structure records the state, which is private to Xlib, that needs preservation across calls to XLookupString() to implement compose processing. The creation of XComposeStatus structures is implementation dependent; a portable program must pass NULL for this argument.

XLookupString() depends on the cached keyboard information mentioned in the previous section, so it is necessary to use XRefreshKeyboardMapping() to keep this information up-to-date.

See also

XLookupKeysym(), XRebindKeysym(), XRefreshKeyboardMapping(), XStringToKeysym() XButtonEvent, XMapEvent, "Latin-1 Keyboard Event Functions".
Christophe Tronche, ch@tronche.com