xref: /illumos-gate/usr/src/lib/libtecla/common/keytab.h (revision 1da57d551424de5a9d469760be7c4b4d4f10a755)
1 #ifndef keytab_h
2 #define keytab_h
3 
4 /*
5  * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
6  *
7  * All rights reserved.
8  *
9  * Permission is hereby granted, free of charge, to any person obtaining a
10  * copy of this software and associated documentation files (the
11  * "Software"), to deal in the Software without restriction, including
12  * without limitation the rights to use, copy, modify, merge, publish,
13  * distribute, and/or sell copies of the Software, and to permit persons
14  * to whom the Software is furnished to do so, provided that the above
15  * copyright notice(s) and this permission notice appear in all copies of
16  * the Software and that both the above copyright notice(s) and this
17  * permission notice appear in supporting documentation.
18  *
19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
20  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
22  * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
23  * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
24  * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
25  * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
26  * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
27  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
28  *
29  * Except as contained in this notice, the name of a copyright holder
30  * shall not be used in advertising or otherwise to promote the sale, use
31  * or other dealings in this Software without prior written authorization
32  * of the copyright holder.
33  */
34 
35 #include "libtecla.h"
36 
37 /*-----------------------------------------------------------------------*
38  * This module defines a binary-search symbol table of key-bindings.     *
39  *-----------------------------------------------------------------------*/
40 
41 /*
42  * All key-binding functions are defined as follows.
43  *
44  * Input:
45  *  gl    GetLine *  The resource object of this library.
46  *  count     int    A positive repeat count specified by the user,
47  *                   or 1. Action functions should ignore this if
48  *                   repeating the action multiple times isn't
49  *                   appropriate.
50  *  data     void *  A pointer to action-specific data,
51  *                   cast to (void *).
52  * Output:
53  *  return    int    0 - OK.
54  *                   1 - Error.
55  */
56 #define KT_KEY_FN(fn) int (fn)(GetLine *gl, int count, void *data)
57 
58 typedef KT_KEY_FN(KtKeyFn);
59 
60 /*
61  * Allow the association of arbitrary callback data with each action
62  * function.
63  */
64 typedef struct {
65   KtKeyFn *fn;          /* The acion function */
66   void *data;           /* A pointer to arbitrary data to be passed to */
67                         /*  fn() whenever it is called. */
68 } KtAction;
69 
70 /*
71  * Enumerate the possible sources of key-bindings in order of decreasing
72  * priority.
73  */
74 typedef enum {
75   KTB_USER,         /* This is a binding being set by the user */
76   KTB_NORM,         /* This is the default binding set by the library */
77   KTB_TERM,         /* This is a binding taken from the terminal settings */
78 /* The following entry must always be last */
79   KTB_NBIND         /* The number of binding sources listed above */
80 } KtBinder;
81 
82 /*
83  * Define an entry of a key-binding binary symbol table.
84  */
85 typedef struct {
86   char *keyseq;                /* The key sequence that triggers the macro */
87   int nc;                      /* The number of characters in keyseq[] */
88   KtAction actions[KTB_NBIND]; /* Bindings from different sources */
89   int binder;                  /* The index of the highest priority element */
90                                /*  of actions[] that has been assigned an */
91                                /*  action function, or -1 if none have. */
92 } KeySym;
93 
94 /*
95  * Provide an opaque type alias to the symbol table container.
96  */
97 typedef struct KeyTab KeyTab;
98 
99 /*
100  * Create a new symbol table.
101  */
102 KeyTab *_new_KeyTab(void);
103 
104 /*
105  * Delete the symbol table.
106  */
107 KeyTab *_del_KeyTab(KeyTab *kt);
108 
109 int _kt_set_keybinding(KeyTab *kt, KtBinder binder,
110 		       const char *keyseq, const char *action);
111 int _kt_set_keyfn(KeyTab *kt, KtBinder binder, const char *keyseq,
112 		  KtKeyFn *fn, void *data);
113 
114 int _kt_set_action(KeyTab *kt, const char *action, KtKeyFn *fn, void *data);
115 
116 /*
117  * Lookup the function that implements a given action.
118  */
119 int _kt_lookup_action(KeyTab *kt, const char *action,
120 		      KtKeyFn **fn, void **data);
121 
122 typedef enum {
123   KT_EXACT_MATCH,   /* An exact match was found */
124   KT_AMBIG_MATCH,   /* An ambiguous match was found */
125   KT_NO_MATCH,      /* No match was found */
126   KT_BAD_MATCH      /* An error occurred while searching */
127 } KtKeyMatch;
128 
129 KtKeyMatch _kt_lookup_keybinding(KeyTab *kt, const char *binary_keyseq,
130 				 int nc, KeySym **matches, int *nmatch);
131 
132 /*
133  * Remove all key bindings that came from a specified source.
134  */
135 void _kt_clear_bindings(KeyTab *kt, KtBinder binder);
136 
137 /*
138  * When installing an array of keybings each binding is defined by
139  * an element of the following type:
140  */
141 typedef struct {
142   const char *keyseq;   /* The sequence of keys that trigger this binding */
143   const char *action;   /* The name of the action function that is triggered */
144 } KtKeyBinding;
145 
146 /*
147  * Merge an array of bindings with existing bindings.
148  */
149 int _kt_add_bindings(KeyTab *kt, KtBinder binder, const KtKeyBinding *bindings,
150 		     unsigned n);
151 
152 /*
153  * Get information about the last error in this module.
154  */
155 const char *_kt_last_error(KeyTab *kt);
156 
157 #endif
158