Manpages - termkey_getkey.3

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
EXAMPLE
SEE ALSO

NAME

termkey_getkey, termkey_getkey_force - retrieve the next key event

SYNOPSIS

  #include <termkey.h>

  TermKeyResult termkey_getkey(TermKey *tk, TermKeyKey *key);
  TermKeyResult termkey_getkey_force(TermKey *tk, TermKeyKey *key);

Link with -ltermkey.

DESCRIPTION

*termkey_getkey*() attempts to retrieve a single keypress event from the *termkey*(7) instance buffer, and put it in the structure referred to by key. It returns one of the following values:

TERMKEY_RES_KEY: a complete keypress was removed from the buffer, and has been placed in the key structure.
TERMKEY_RES_AGAIN: a partial keypress event was found in the buffer, but it does not yet contain all the bytes required. An indication of what *termkey_getkey_force*() would return has been placed in the key structure.
TERMKEY_RES_NONE: no bytes are waiting in the buffer.
TERMKEY_RES_EOF: no bytes are ready and the input stream is now closed.
TERMKEY_RES_ERROR: called with terminal IO stopped, due to termkey_stop*(3). In this case errno will be set to *EINVAL.

termkey_getkey_force*() is similar to *termkey_getkey*() but will not return *TERMKEY_RES_AGAIN if a partial match is found. Instead, it will force an interpretation of the bytes, even if this means interpreting the start of an Escape-prefixed multi-byte sequence as a literal Escape key followed by normal letters.

Neither of these functions will block or perform any IO operations on the underlying filehandle. To use the instance in an asynchronous program, see *termkey_advisereadable*(3). For a blocking call suitable for use in a synchronous program, use *termkey_waitkey*(3) instead of *termkey_getkey*(). For providing input without a readable filehandle, use *termkey_push_bytes*(3).

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

RETURN VALUE

termkey_getkey*() returns an enumeration of one of *TERMKEY_RES_KEY, TEMRKEY_RES_AGAIN, TERMKEY_RES_NONE, TERMKEY_RES_EOF or TERMKEY_RES_ERROR. termkey_getkey_force*() returns one of the above, except for *TERMKEY_RES_AGAIN.

EXAMPLE

The following example program prints details of every keypress until the user presses Ctrl-C. It demonstrates how to use the termkey instance in a typical *poll*(2)-driven asynchronous program, which may include mixed IO with other file handles.

  // <poll.h> might need this for sigset_t
  #define _XOPEN_SOURCE 600

  #include <poll.h>
  #include <stdio.h>

  #include "termkey.h"

  static void on_key(TermKey *tk, TermKeyKey *key)
  {
    char buffer[50];
    termkey_strfkey(tk, buffer, sizeof buffer, key, TERMKEY_FORMAT_VIM);
    printf("%s\n", buffer);
  }

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

    TermKey *tk = termkey_new(0, 0);

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

    struct pollfd fd;

    fd.fd = 0; /* the file descriptor we passed to termkey_new() */
    fd.events = POLLIN;

    TermKeyResult ret;
    TermKeyKey key;

    int running = 1;
    int nextwait = -1;

    while(running) {
      if(poll(&fd, 1, nextwait) == 0) {
        // Timed out
        if(termkey_getkey_force(tk, &key) == TERMKEY_RES_KEY)
          on_key(tk, &key);
      }

      if(fd.revents & (POLLIN|POLLHUP|POLLERR))
        termkey_advisereadable(tk);

      while((ret = termkey_getkey(tk, &key)) == TERMKEY_RES_KEY) {
        on_key(tk, &key);

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

      if(ret == TERMKEY_RES_AGAIN)
        nextwait = termkey_get_waittime(tk);
      else
        nextwait = -1;
    }

    termkey_destroy(tk);
  }