NAME

       termkey_waitkey - wait for and retrieve the next key event

SYNOPSIS

       #include <termkey.h>

       TermKeyResult termkey_waitkey(TermKey *tk, TermKeyKey *key);

       Link with -ltermkey.

DESCRIPTION

       termkey_waitkey()  attempts  to retrieve a single keypress event from the termkey(7) instance buffer, and
       put it in the structure referred to by key. If successful it will return TERMKEY_RES_KEY to indicate that
       the  structure  now contains a new keypress event. If nothing is in the buffer it will block until one is
       available. If no events are ready and the input stream is now closed, will return TERMKEY_RES_EOF. If  no
       filehandle is associated with this instance, TERMKEY_RES_ERROR is returned with errno set to EBADF.

       Before  returning,  this  function  canonicalises  the  key  structure  according  to the rules given for
       termkey_canonicalise(3).

       Some keypresses generate multiple bytes from the terminal. Because there may be network or  other  delays
       between  the  terminal  and  an application using termkey, termkey_waitkey() will attempt to wait for the
       remaining bytes to arrive if it detects the start of a multibyte sequence. If no more bytes arrive within
       a  certain  time,  then  the bytes will be reported as they stand, even if this results in interpreting a
       partially-complete Escape sequence as a literal Escape key followed  by  some  normal  letters  or  other
       symbols. The amount of time to wait can be set by termkey_set_waittime(3).

RETURN VALUE

       termkey_waitkey() returns one of the following constants:

       TERMKEY_RES_KEY
              A key event as been provided.

       TERMKEY_RES_EOF
              No key events are ready and the terminal has been closed, so no more will arrive.

       TERMKEY_RES_ERROR
              An  IO  error  occurred.  errno  will  be  preserved. If the error is EINTR then this will only be
              returned if TERMKEY_FLAG_EINTR flag is not set; if it is then the IO  operation  will  be  retried
              instead. If this is called with terminal IO stopped, due to termkey_stop(3) then errno will be set
              to EINVAL.

EXAMPLE

       The following example program prints details of every keypress until the user presses Ctrl-C.

           // we want optarg
           #define _XOPEN_SOURCE 600

           #include <stdio.h>
           #include <unistd.h>
           #include <errno.h>

           #include "termkey.h"

           int main(int argc, char *argv[])
           {
             TERMKEY_CHECK_VERSION;

             int mouse = 0;
             int mouse_proto = 0;
             TermKeyFormat format = TERMKEY_FORMAT_VIM;

             char buffer[50];
             TermKey *tk;

             int opt;
             while((opt = getopt(argc, argv, "m::p:")) != -1) {
               switch(opt) {
               case 'm':
                 if(optarg)
                   mouse = atoi(optarg);
                 else
                   mouse = 1000;

                 break;

               case 'p':
                 mouse_proto = atoi(optarg);
                 break;

               default:
                 fprintf(stderr, "Usage: %s [-m]\n", argv[0]);
                 return 1;
               }
             }

             tk = termkey_new(0, TERMKEY_FLAG_SPACESYMBOL|TERMKEY_FLAG_CTRLC);

             if(!tk) {
               fprintf(stderr, "Cannot allocate termkey instance\n");
               exit(1);
             }

             if(termkey_get_flags(tk) & TERMKEY_FLAG_UTF8)
               printf("Termkey in UTF-8 mode\n");
             else if(termkey_get_flags(tk) & TERMKEY_FLAG_RAW)
               printf("Termkey in RAW mode\n");

             TermKeyResult ret;
             TermKeyKey key;

             if(mouse) {
               printf("\033[?%dhMouse mode active\n", mouse);
               if(mouse_proto)
                 printf("\033[?%dh", mouse_proto);
             }

             while((ret = termkey_waitkey(tk, &key)) != TERMKEY_RES_EOF) {
               if(ret == TERMKEY_RES_KEY) {
                 termkey_strfkey(tk, buffer, sizeof buffer, &key, format);
                 if(key.type == TERMKEY_TYPE_MOUSE) {
                   int line, col;
                   termkey_interpret_mouse(tk, &key, NULL, NULL, &line, &col);
                   printf("%s at line=%d, col=%d\n", buffer, line, col);
                 }
                 else if(key.type == TERMKEY_TYPE_POSITION) {
                   int line, col;
                   termkey_interpret_position(tk, &key, &line, &col);
                   printf("Cursor position report at line=%d, col=%d\n", line, col);
                 }
                 else if(key.type == TERMKEY_TYPE_MODEREPORT) {
                   int initial, mode, value;
                   termkey_interpret_modereport(tk, &key, &initial, &mode, &value);
                   printf("Mode report %s mode %d = %d\n", initial ? "DEC" : "ANSI", mode, value);
                 }
                 else if(key.type == TERMKEY_TYPE_UNKNOWN_CSI) {
                   long args[16];
                   size_t nargs = 16;
                   unsigned long command;
                   termkey_interpret_csi(tk, &key, args, &nargs, &command);
                   printf("Unrecognised CSI %c %ld;%ld %c%c\n", (char)(command >> 8), args[0], args[1], (char)(command >> 16), (char)command);
                 }
                 else {
                   printf("Key %s\n", buffer);
                 }

                 if(key.type == TERMKEY_TYPE_UNICODE &&
                    key.modifiers & TERMKEY_KEYMOD_CTRL &&
                    (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
                   break;

                 if(key.type == TERMKEY_TYPE_UNICODE &&
                    key.modifiers == 0 &&
                    key.code.codepoint == '?') {
                   // printf("\033[?6n"); // DECDSR 6 == request cursor position
                   printf("\033[?1$p"); // DECRQM == request mode, DEC origin mode
                   fflush(stdout);
                 }
               }
               else if(ret == TERMKEY_RES_ERROR) {
                 if(errno != EINTR) {
                   perror("termkey_waitkey");
                   break;
                 }
                 printf("Interrupted by signal\n");
               }
             }

             if(mouse)
               printf("\033[?%dlMouse mode deactivated\n", mouse);

             termkey_destroy(tk);
           }

COMPATIBILITY

       This function is not available on Windows.

SEE ALSO

       termkey_getkey(3), termkey_set_waittime(3), termkey(7)

                                                                                              TERMKEY_WAITKEY(3)