{The S-Lang C Library Reference}: Keymap Functions

Next Previous Contents

## 11. Keymap Functions

## 11.1 SLkm_define_key

Synopsis

  Define a key in a keymap

Usage

  `int SLkm_define_key (char *seq, FVOID_STAR f, SLKeyMap_List_Type *km)`

Description

  `SLkm_define_key` associates the key sequence `seq` with the function pointer `f` in the keymap specified by `km`. Upon success, it returns zero, otherwise it returns a negative integer upon error.

See Also

  `SLkm_define_keysym, SLang_define_key`

## 11.2 SLang_define_key

Synopsis

  Define a key in a keymap

Usage

  `int SLang_define_key(char *seq, char *fun, SLKeyMap_List_Type *km)`

Description

  `SLang_define_key` associates the key sequence `seq` with the function whose name is `fun` in the keymap specified by `km`.

See Also

  `SLkm_define_keysym, SLkm_define_key`

## 11.3 SLkm_define_keysym

Synopsis

  Define a keysym in a keymap

Usage

  `int SLkm_define_keysym (seq, ks, km)`

  > `

  >           char *seq;
  >           unsigned int ks;
  >           SLKeyMap_List_Type *km;

  > `

Description

  `SLkm_define_keysym` associates the key sequence `seq` with the keysym `ks` in the keymap `km`. Keysyms whose value is less than or equal to `0x1000` is reserved by the library and should not be used.

See Also

  `SLkm_define_key, SLang_define_key`

## 11.4 SLang_undefine_key

Synopsis

  Undefined a key from a keymap

Usage

  `void SLang_undefine_key(char *seq, SLKeyMap_List_Type *km);`

Description

  `SLang_undefine_key` removes the key sequence `seq` from the keymap `km`.

See Also

  `SLang_define_key`

## 11.5 SLang_create_keymap

Synopsis

  Create a new keymap

Usage

  `SLKeyMap_List_Type *SLang_create_keymap (name, km)`

  > `

  >          char *name;
  >          SLKeyMap_List_Type *km;

  > `

Description

  `SLang_create_keymap` creates a new keymap called `name` by copying the key definitions from the keymap `km`. If `km` is `NULL`, the newly created keymap will be empty and it is up to the calling routine to initialize it via the `SLang_define_key` and `SLkm_define_keysym` functions. `SLang_create_keymap` returns a pointer to the new keymap, or `NULL` upon failure.

See Also

  `SLang_define_key, SLkm_define_keysym`

## 11.6 SLang_do_key

Synopsis

  Read a keysequence and return its keymap entry

Usage

  `SLang_Key_Type *SLang_do_key (kml, getkey)`

  > `

  >          SLKeyMap_List_Type *kml;
  >          int (*getkey)(void);

  > `

Description

  The `SLang_do_key` function reads characters using the function specified by the `getkey` function pointer and uses the key sequence to return the appropriate entry in the keymap specified by `kml`.

  `SLang_do_key` returns `NULL` if the key sequence is not defined by the keymap, otherwise it returns a pointer to an object of type `SLang_Key_Type`, which is defined in `slang.h` as

  > `

  >          #define SLANG_MAX_KEYMAP_KEY_SEQ 14
  >          typedef struct SLang_Key_Type
  >          {
  >            struct SLang_Key_Type *next;
  >            union
  >            {
  >               char *s;
  >               FVOID_STAR f;
  >               unsigned int keysym;
  >            }
  >            f;
  >            unsigned char type;             /* type of function */
  >          #define SLKEY_F_INTERPRET  0x01
  >          #define SLKEY_F_INTRINSIC  0x02
  >          #define SLKEY_F_KEYSYM     0x03
  >            unsigned char str[SLANG_MAX_KEYMAP_KEY_SEQ + 1];/* key sequence */
  >          }
  >     SLang_Key_Type;

  > `

  The `type` field specifies which field of the union `f` should be used. If `type` is `SLKEY_F_INTERPRET`, then `f.s` is a string that should be passed to the interpreter for evaluation. If `type` is `SLKEY_F_INTRINSIC`, then `f.f` refers to function that should be called. Otherwise, `type` is `SLKEY_F_KEYSYM` and `f.keysym` represents the value of the keysym that is associated with the key sequence.
See Also

  `SLkm_define_keysym, SLkm_define_key`

## 11.7 SLang_find_key_function

Synopsis

  Obtain a function pointer associated with a keymap

Usage

  `FVOID_STAR SLang_find_key_function (fname, km);`

  > `

  >         char *fname;
  >         SLKeyMap_List_Type *km;

  > `

Description

  The `SLang_find_key_function` routine searches through the `SLKeymap_Function_Type` list of functions associated with the keymap `km` for the function with name `fname`. If a matching function is found, a pointer to the function will be returned, otherwise `SLang_find_key_function` will return `NULL`.

See Also

  `SLang_create_keymap, SLang_find_keymap`

## 11.8 SLang_find_keymap

Synopsis

  Find a keymap

Usage

  `SLKeyMap_List_Type *SLang_find_keymap (char *keymap_name);`

Description

  The `SLang_find_keymap` function searches through the list of keymaps looking for one whose name is `keymap_name`. If a matching keymap is found, the function returns a pointer to the keymap. It returns `NULL` if no such keymap exists.

See Also

  `SLang_create_keymap, SLang_find_key_function`

## 11.9 SLang_process_keystring

Synopsis

  Un-escape a key-sequence

Usage

  `char *SLang_process_keystring (char *kseq);`

Description

  The `SLang_process_keystring` function converts an escaped key sequence to its raw form by converting two-character combinations such as `^A` to the single character `Ctrl-A` (ASCII 1). In addition, if the key sequence contains constructs such as `^(XX)`, where `XX` represents a two-character termcap specifier, the termcap escape sequence will be looked up and substituted.

  Upon success, `SLang_process_keystring` returns a raw key-sequence whose first character represents the total length of the key-sequence, including the length specifier itself. It returns `NULL` upon failure.

Example

  Consider the following examples:

  > `

  >          SLang_process_keystring ("^X^C");
  >          SLang_process_keystring ("^[[A");

  > `

  The first example will return a pointer to a buffer of three characters whose ASCII values are given by `{3,24,3}`. Similarly, the second example will return a pointer to the four characters `{4,27,91,65}`. Finally, the result of

  > `

  >          SLang_process_keystring ("^[^(ku)");

  > `

  will depend upon the termcap/terminfo capability `"ku"`, which represents the escape sequence associated with the terminal's UP arrow key. For an ANSI terminal whose UP arrow produces `"ESC [ A"`, the result will be `5,27,27,91,65`.
Notes

  `SLang_process_keystring` returns a pointer to a static area that will be overwritten on subsequent calls.

See Also

  `SLang_define_key, SLang_make_keystring`

## 11.10 SLang_make_keystring

Synopsis

  Make a printable key sequence

Usage

  `char *SLang_make_keystring (unsigned char *ks);`

Description

  The `SLang_make_keystring` function takes a raw key sequence `ks` and converts it to a printable form by converting characters such as ASCII 1 (ctrl-A) to `^A`. That is, it performs the opposite function of `SLang_process_keystring`.

Notes

  This function returns a pointer to a static area that will be overwritten on the next call to `SLang_make_keystring`.

See Also

  `SLang_process_keystring`

Next Previous Contents