1\function{SLkm_define_key}
2\synopsis{Define a key in a keymap}
3\usage{int SLkm_define_key (char *seq, FVOID_STAR f, SLKeyMap_List_Type *km)}
4\description
5  \var{SLkm_define_key} associates the key sequence \var{seq} with the
6  function pointer \var{f} in the keymap specified by \var{km}.  Upon
7  success, it returns zero, otherwise it returns a negative integer
8  upon error.
9\seealso{SLkm_define_keysym, SLang_define_key}
10\done
11
12\function{SLang_define_key}
13\synopsis{Define a key in a keymap}
14\usage{int SLang_define_key(char *seq, char *fun, SLKeyMap_List_Type *km)}
15\description
16  \var{SLang_define_key} associates the key sequence \var{seq} with
17  the function whose name is \var{fun} in the keymap specified by
18  \var{km}.
19\seealso{SLkm_define_keysym, SLkm_define_key}
20\done
21
22\function{SLkm_define_keysym}
23\synopsis{Define a keysym in a keymap}
24\usage{int SLkm_define_keysym (seq, ks, km)}
25#v+
26      char *seq;
27      unsigned int ks;
28      SLKeyMap_List_Type *km;
29#v-
30\description
31  \var{SLkm_define_keysym} associates the key sequence \var{seq} with
32  the keysym \var{ks} in the keymap \var{km}.  Keysyms whose value is
33  less than or equal to \exmp{0x1000} is reserved by the library and
34  should not be used.
35\seealso{SLkm_define_key, SLang_define_key}
36\done
37
38\function{SLang_undefine_key}
39\synopsis{Undefined a key from a keymap}
40\usage{void SLang_undefine_key(char *seq, SLKeyMap_List_Type *km);}
41\description
42  \var{SLang_undefine_key} removes the key sequence \var{seq} from the
43  keymap \var{km}.
44\seealso{SLang_define_key}
45\done
46
47\function{SLang_create_keymap}
48\synopsis{Create a new keymap}
49\usage{SLKeyMap_List_Type *SLang_create_keymap (name, km)}
50#v+
51     char *name;
52     SLKeyMap_List_Type *km;
53#v-
54\description
55  \var{SLang_create_keymap} creates a new keymap called \var{name} by
56  copying the key definitions from the keymap \var{km}.  If \var{km}
57  is \var{NULL}, the newly created keymap will be empty and it is up
58  to the calling routine to initialize it via the
59  \var{SLang_define_key} and \var{SLkm_define_keysym} functions.
60  \var{SLang_create_keymap} returns a pointer to the new keymap, or
61  \var{NULL} upon failure.
62\seealso{SLang_define_key, SLkm_define_keysym}
63\done
64
65\function{SLang_do_key}
66\synopsis{Read a keysequence and return its keymap entry}
67\usage{SLang_Key_Type *SLang_do_key (kml, getkey)}
68#v+
69     SLKeyMap_List_Type *kml;
70     int (*getkey)(void);
71#v-
72\description
73  The \var{SLang_do_key} function reads characters using the function
74  specified by the \var{getkey} function pointer and uses the
75  key sequence to return the appropriate entry in the keymap specified
76  by \var{kml}.
77
78  \var{SLang_do_key} returns \var{NULL} if the key sequence is not
79  defined by the keymap, otherwise it returns a pointer to an object
80  of type \var{SLang_Key_Type}, which is defined in \exmp{slang.h} as
81#v+
82     #define SLANG_MAX_KEYMAP_KEY_SEQ 14
83     typedef struct SLang_Key_Type
84     {
85       struct SLang_Key_Type *next;
86       union
87       {
88          char *s;
89	  FVOID_STAR f;
90	  unsigned int keysym;
91       }
92       f;
93       unsigned char type;	       /* type of function */
94     #define SLKEY_F_INTERPRET  0x01
95     #define SLKEY_F_INTRINSIC  0x02
96     #define SLKEY_F_KEYSYM     0x03
97       unsigned char str[SLANG_MAX_KEYMAP_KEY_SEQ + 1];/* key sequence */
98     }
99SLang_Key_Type;
100
101#v-
102  The \var{type} field specifies which field of the union \var{f}
103  should be used.  If \var{type} is \var{SLKEY_F_INTERPRET}, then
104  \var{f.s} is a string that should be passed to the interpreter for
105  evaluation.  If \var{type} is \var{SLKEY_F_INTRINSIC}, then
106  \var{f.f} refers to function that should be called.  Otherwise,
107  \var{type} is \var{SLKEY_F_KEYSYM} and \var{f.keysym} represents the
108  value of the keysym that is associated with the key sequence.
109\seealso{SLkm_define_keysym, SLkm_define_key}
110\done
111
112\function{SLang_find_key_function}
113\synopsis{Obtain a function pointer associated with a keymap}
114\usage{FVOID_STAR SLang_find_key_function (fname, km);}
115#v+
116    char *fname;
117    SLKeyMap_List_Type *km;
118#v-
119\description
120  The \var{SLang_find_key_function} routine searches through the
121  \var{SLKeymap_Function_Type} list of functions associated with the
122  keymap \var{km} for the function with name \var{fname}.
123  If a matching function is found, a pointer to the function will
124  be returned, otherwise \var{SLang_find_key_function} will return
125  \var{NULL}.
126\seealso{SLang_create_keymap, SLang_find_keymap}
127\done
128
129\function{SLang_find_keymap}
130\synopsis{Find a keymap}
131\usage{SLKeyMap_List_Type *SLang_find_keymap (char *keymap_name);}
132\description
133  The \var{SLang_find_keymap} function searches through the list of
134  keymaps looking for one whose name is \var{keymap_name}.  If a
135  matching keymap is found, the function returns a pointer to the
136  keymap.  It returns \var{NULL} if no such keymap exists.
137\seealso{SLang_create_keymap, SLang_find_key_function}
138\done
139
140\function{SLang_process_keystring}
141\synopsis{Un-escape a key-sequence}
142\usage{char *SLang_process_keystring (char *kseq);}
143\description
144  The \var{SLang_process_keystring} function converts an escaped key
145  sequence to its raw form by converting two-character combinations
146  such as \var{^A} to the \em{single} character \exmp{Ctrl-A} (ASCII
147  1).  In addition, if the key sequence contains constructs such as
148  \exmp{^(XX)}, where \exmp{XX} represents a two-character termcap
149  specifier, the termcap escape sequence will be looked up and
150  substituted.
151
152  Upon success, \var{SLang_process_keystring} returns a raw
153  key-sequence whose first character represents the total length of
154  the key-sequence, including the length specifier itself.  It returns
155  \var{NULL} upon failure.
156\example
157  Consider the following examples:
158#v+
159     SLang_process_keystring ("^X^C");
160     SLang_process_keystring ("^[[A");
161#v-
162  The first example will return a pointer to a buffer of three characters
163  whose ASCII values are given by \exmp{\{3,24,3\}}.  Similarly, the
164  second example will return a pointer to the four characters
165  \exmp{\{4,27,91,65\}}.  Finally, the result of
166#v+
167     SLang_process_keystring ("^[^(ku)");
168#v-
169  will depend upon the termcap/terminfo capability \exmp{"ku"}, which
170  represents the escape sequence associated with the terminal's UP
171  arrow key.  For an ANSI terminal whose UP arrow produces
172  \exmp{"ESC [ A"}, the result will be \exmp{5,27,27,91,65}.
173\notes
174  \var{SLang_process_keystring} returns a pointer to a static area
175  that will be overwritten on subsequent calls.
176\seealso{SLang_define_key, SLang_make_keystring}
177\done
178
179\function{SLang_make_keystring}
180\synopsis{Make a printable key sequence}
181\usage{char *SLang_make_keystring (unsigned char *ks);}
182\description
183  The \var{SLang_make_keystring} function takes a raw key sequence
184  \var{ks} and converts it to a printable form by converting
185  characters such as ASCII 1 (ctrl-A) to \exmp{^A}.  That is, it
186  performs the opposite function of \var{SLang_process_keystring}.
187\notes
188  This function returns a pointer to a static area that will be
189  overwritten on the next call to \var{SLang_make_keystring}.
190\seealso{SLang_process_keystring}
191\done
192
193