XmbLookupString(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
XmbLookupString(3)                                          XmbLookupString(3)




NAME

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


SYNTAX

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

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

       int   Xutf8LookupString(XIC   ic,   XKeyPressedEvent    *event,    char
              *buffer_return,  int bytes_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, XwcLookupString  and  Xutf8LookupString  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  and  Xutf8LookupString return the length of the string
       in bytes, and XwcLookupString returns the length of the string in char-
       acters.   Both  XmbLookupString  and XwcLookupString return text in the
       encoding of the locale bound to the input method of the specified input
       context, and Xutf8LookupString returns text in UTF-8 encoding.

       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  ensure  proper  input  processing,  it is essential that the
       client pass only KeyPress events  to  XmbLookupString,  XwcLookupString
       and  Xutf8LookupString.   Their  behavior when a client passes a KeyRe-
       lease event is undefined.

       Clients should check the status_return argument before using the  other
       returned  values.   These  three  functions each return a value to sta-
       tus_return that indicates what has been returned  in  the  other  argu-
       ments.  The possible values returned are:

       lw(1.3i)  lw(4.3i).   T{ XBufferOverflow T}   T{ The input string to be
       returned is too large for the  supplied  buffer_return.   The  required
       size  (for  XmbLookupString, Xutf8LookupString in bytes; for XwcLookup-
       String 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 con-
       sistent 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, using the encoding described
       above, and the string length is returned as the value of the  function.
       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 simultaneously.  T}

       It does not make any difference if the input context passed as an argu-
       ment  to  XmbLookupString, XwcLookupString and Xutf8LookupString 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,
       XwcLookupString  or  Xutf8LookupString even though it does not have any
       more keyboard focus.

       The function  Xutf8LookupString  is  an  extension  introduced  by  The
       XFree86  Project,  Inc., in their 4.0.2 release.  Its presence is indi-
       cated by the macro X_HAVE_UTF8_STRING.


SEE ALSO

       XLookupKeysym(3), Compose(5)
       Xlib - C Language X Interface



XLIB FUNCTIONS                   X Version 11               XmbLookupString(3)