// Keyboard layouts.
//
// A layout answers one question: given a scancode and the modifiers held,
// which Unicode codepoint was typed? Everything else about the keyboard --
// which port to read, when a key is a release, what the terminal-switch chord
// is -- belongs to kernel/dev/kbd.c and is the same whatever the layout.
//
// Codepoints, not bytes. A layout that can only produce bytes can produce
// `ó` (U+00F3, which fits in Latin-1) but not `ą` (U+0105, which does not),
// and half a Polish alphabet is not a Polish layout. kbd.c encodes the
// codepoint to UTF-8 on the way to the console.
//
// **No dead keys.** On a German layout the acute and circumflex keys are dead
// -- pressed, they wait for the next key and combine -- and here they simply
// produce the accent character on its own. That is wrong, it is visibly
// wrong, and it needs somewhere to hold "a dead key is pending", which is
// per-keyboard state this interface has no room for. Layouts that need it are
// not shipped rather than shipped broken; see keymap_layouts[] for which.

#ifndef KEYMAP_H
#define KEYMAP_H

#include "core/types.h"

// Which of a layout's four tables a set of modifiers selects. Plain, Shift,
// AltGr, and Shift+AltGr -- Ctrl is not one of them, because a control
// character is derived from the plain codepoint rather than looked up, which
// is what makes Ctrl+Z still be Ctrl+Z on a layout that moved the Z key.
#define KM_PLAIN        0
#define KM_SHIFT        1
#define KM_ALTGR        2
#define KM_SHIFTALTGR   3
#define KM_LEVELS       4

struct keylayout {
  const char   *name;                   // "us", "pl", "de" -- what you type
  const char   *desc;                   // what it is, for `loadkeys -l`
  const uint32 *level[KM_LEVELS];       // 256 entries each; NULL falls back
};

// The active layout, and the catalogue.
const struct keylayout *keymap_active(void);
const struct keylayout *keymap_by_index(int i);   // NULL past the end
int  keymap_set(const char *name);                // 0, or -1 if unknown

// Scancode plus modifier bits (SHIFT/CTL/ALT/RALT/CAPSLOCK from kbd.h) to a
// Unicode codepoint, or one of the KBD_* specials, or 0 for "no character".
uint32 keymap_lookup(uint scancode, uint mods);

#endif /* KEYMAP_H */