6 CGDB key user interface

The Key User Interface is how CGDB receives input from the user. It is usually referred to as the KUI. CGDB simply asks the KUI for the next key the user typed and the KUI will provide it.

The KUI has 2 major responsibilities besides reading normal user input and providing it to CGDB. It needs to detect when the user has typed a user defined map or when the user has hit a special key on the keyboard.

A user defined map, or simply map, is used to change the meaning of typed keys. Some users may refer to this type of functionality as a macro. An example would be map a b. If the user then typed the a character, the KUI would detect that it was mapped to b and return b to CGDB.

When the user types a special key on the keyboard, a key code is sent to CGDB. Typically, keys like HOME, DEL, F1, etc, when pressed will send several characters to the application instead of just one character like a normal key does. These characters combined are called a key sequence. The KUI is responsible for assembling the key sequences back together and reporting to CGDB that a particular key was typed by the user. The ESC key is special because typically most key codes start with that key. This usually gives all key codes a common first key in its key sequence. The KUI uses the terminfo database to determine what key sequences are sent by which keycodes. There are a few commonly used key sequences that are hard coded into CGDB.

A major challenge the KUI has to overcome is determining when a map or a key sequence is received. The KUI sometimes will need to read more than one character to determine this. For example, if the user has 2 maps, map abc def and map abd def, the KUI would have to buffer at least the characters a and b before it could determine if the user was going to type a map. After the next key press, if the user types c or d then a map was received and the KUI will return d e f to CGDB. Otherwise, no map was received and the KUI must return a b to CGDB.

The options timeout, ttimeout, timeoutlen and ttimeoutlen can be used to tell the KUI if it should timeout on partial mappings or key sequences, and if so, how long it should wait before timing out.