usr/src/lib/libtecla/common/keytab.h

   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 #pragma ident   "%Z%%M% %I%     %E% SMI"
  36
  37 #include "libtecla.h"
  38
  39 /*-----------------------------------------------------------------------*
  40  * This module defines a binary-search symbol table of key-bindings.     *
  41  *-----------------------------------------------------------------------*/
  42
  43 /*
  44  * All key-binding functions are defined as follows.
  45  *
  46  * Input:
  47  *  gl    GetLine *  The resource object of this library.
  48  *  count     int    A positive repeat count specified by the user,
  49  *                   or 1. Action functions should ignore this if
  50  *                   repeating the action multiple times isn't
  51  *                   appropriate.
  52  *  data     void *  A pointer to action-specific data,
  53  *                   cast to (void *).
  54  * Output:
  55  *  return    int    0 - OK.
  56  *                   1 - Error.
  57  */
  58 #define KT_KEY_FN(fn) int (fn)(GetLine *gl, int count, void *data)
  59
  60 typedef KT_KEY_FN(KtKeyFn);
  61
  62 /*
  63  * Allow the association of arbitrary callback data with each action
  64  * function.
  65  */
  66 typedef struct {
  67   KtKeyFn *fn;          /* The acion function */
  68   void *data;           /* A pointer to arbitrary data to be passed to */
  69                         /*  fn() whenever it is called. */
  70 } KtAction;
  71
  72 /*
  73  * Enumerate the possible sources of key-bindings in order of decreasing
  74  * priority.
  75  */
  76 typedef enum {
  77   KTB_USER,         /* This is a binding being set by the user */
  78   KTB_NORM,         /* This is the default binding set by the library */
  79   KTB_TERM,         /* This is a binding taken from the terminal settings */
  80 /* The following entry must always be last */
  81   KTB_NBIND         /* The number of binding sources listed above */
  82 } KtBinder;
  83
  84 /*
  85  * Define an entry of a key-binding binary symbol table.
  86  */
  87 typedef struct {
  88   char *keyseq;                /* The key sequence that triggers the macro */
  89   int nc;                      /* The number of characters in keyseq[] */
  90   KtAction actions[KTB_NBIND]; /* Bindings from different sources */
  91   int binder;                  /* The index of the highest priority element */
  92                                /*  of actions[] that has been assigned an */
  93                                /*  action function, or -1 if none have. */
  94 } KeySym;
  95
  96 /*
  97  * Provide an opaque type alias to the symbol table container.
  98  */
  99 typedef struct KeyTab KeyTab;
 100
 101 /*
 102  * Create a new symbol table.
 103  */
 104 KeyTab *_new_KeyTab(void);
 105
 106 /*
 107  * Delete the symbol table.
 108  */
 109 KeyTab *_del_KeyTab(KeyTab *kt);
 110
 111 int _kt_set_keybinding(KeyTab *kt, KtBinder binder,
 112                        const char *keyseq, const char *action);
 113 int _kt_set_keyfn(KeyTab *kt, KtBinder binder, const char *keyseq,
 114                   KtKeyFn *fn, void *data);
 115
 116 int _kt_set_action(KeyTab *kt, const char *action, KtKeyFn *fn, void *data);
 117
 118 /*
 119  * Lookup the function that implements a given action.
 120  */
 121 int _kt_lookup_action(KeyTab *kt, const char *action,
 122                       KtKeyFn **fn, void **data);
 123
 124 typedef enum {
 125   KT_EXACT_MATCH,   /* An exact match was found */
 126   KT_AMBIG_MATCH,   /* An ambiguous match was found */
 127   KT_NO_MATCH,      /* No match was found */
 128   KT_BAD_MATCH      /* An error occurred while searching */
 129 } KtKeyMatch;
 130
 131 KtKeyMatch _kt_lookup_keybinding(KeyTab *kt, const char *binary_keyseq,
 132                                  int nc, KeySym **matches, int *nmatch);
 133
 134 /*
 135  * Remove all key bindings that came from a specified source.
 136  */
 137 void _kt_clear_bindings(KeyTab *kt, KtBinder binder);
 138
 139 /*
 140  * When installing an array of keybings each binding is defined by
 141  * an element of the following type:
 142  */
 143 typedef struct {
 144   const char *keyseq;   /* The sequence of keys that trigger this binding */
 145   const char *action;   /* The name of the action function that is triggered */
 146 } KtKeyBinding;
 147
 148 /*
 149  * Merge an array of bindings with existing bindings.
 150  */
 151 int _kt_add_bindings(KeyTab *kt, KtBinder binder, const KtKeyBinding *bindings,
 152                      unsigned n);
 153
 154 /*
 155  * Get information about the last error in this module.
 156  */
 157 const char *_kt_last_error(KeyTab *kt);
 158
 159 #endif