manpagez: man pages & more
man XwcLookupString(3)
Home | html | info | man
XmbLookupString(3)              XLIB FUNCTIONS              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:

       XBufferOver-    The input string  to  be  returned  is  too
       flow            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.
       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 argu-
                       ment, 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.
       XLookupKeySym   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.
       XLookupBoth     Both a KeySym and a  string  are  returned;
                       XLookupChars and XLookupKeySym occur simul-
                       taneously.

       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



X Version 11                     libX11 1.6.9               XmbLookupString(3)

xorg-libX11 1.6.9 - Generated Wed Oct 23 18:43:41 CDT 2019
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.