src/KeyMap.h

   1 // -*- C++ -*-
   2 /**
   3  * \file KeyMap.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Lars Gullik Bjønnes
   8  * \author Jean-Marc Lasgouttes
   9  * \author John Levon
  10  *
  11  * Full author contact details are available in file CREDITS.
  12  */
  13
  14 #ifndef KEYMAP_H
  15 #define KEYMAP_H
  16
  17 #include "FuncRequest.h"
  18 #include "KeySequence.h"
  19
  20 #include "support/strfwd.h"
  21
  22 #include <boost/shared_ptr.hpp>
  23
  24 #include <vector>
  25 #include <deque>
  26
  27
  28 namespace lyx {
  29
  30 /// Defines key maps and actions for key sequences
  31 class KeyMap {
  32 public:
  33         /**
  34          * Bind/Unbind a key sequence to an action.
  35          * @return 0 on success, or position in string seq where error
  36          * occurs.
  37          * See KeySequence::parse for the syntax of the seq string
  38          */
  39         size_t bind(std::string const & seq, FuncRequest const & func);
  40         size_t unbind(std::string const & seq, FuncRequest const & func);
  41
  42         /**
  43          * Define/Undefine an action for a key sequence.
  44          * @param r internal recursion level
  45          */
  46         void bind(KeySequence * seq, FuncRequest const & func,
  47                     unsigned int r = 0);
  48         void unbind(KeySequence * seq, FuncRequest const & func,
  49                     unsigned int r = 0);
  50
  51
  52         // if a keybinding has been defined.
  53         bool hasBinding(KeySequence const & seq, FuncRequest const & func,
  54                         unsigned int r = 0);
  55
  56         // clear all bindings
  57         void clear();
  58
  59         /** Parse a bind file. If a valid unbind_map is given, put \unbind
  60          * bindings to a separate KeyMap. This is used in the Shortcut preference
  61          * dialog where main and user bind files are loaded separately so \unbind
  62          * in user.bind can not nullify \bind in the master bind file.
  63          *
  64          * @param bind_file bind file
  65          * @param unbind_map pointer to a KeyMap that holds \unbind bindings
  66          */
  67         bool read(std::string const & bind_file, KeyMap * unbind_map = NULL);
  68
  69         /** write to a bind file.
  70          * @param append append to the bind_file instead of overwrite it
  71          * @param unbind use \unbind instead of \bind, indicating this KeyMap
  72          *        actually record unbind maps.
  73          */
  74         void write(std::string const & bind_file, bool append, bool unbind=false) const;
  75
  76         /**
  77          * print all available keysyms
  78          * @param forgui true if the string should use translations and
  79          *   special characters.
  80          */
  81         docstring const print(bool forgui) const;
  82
  83         /**
  84          * Look up a key press in the keymap.
  85          * @param key the keysym
  86          * @param mod the modifiers
  87          * @param seq the current key sequence so far
  88          * @return the action / LFUN_COMMAND_PREFIX / LFUN_UNKNOWN_ACTION
  89          */
  90         FuncRequest const &
  91         lookup(KeySymbol const & key, KeyModifier mod, KeySequence * seq) const;
  92
  93         ///
  94         typedef std::deque<KeySequence> Bindings;
  95
  96         /// Given an action, find all keybindings.
  97         Bindings findbindings(FuncRequest const & func) const;
  98
  99         /// Given an action, print the keybindings.
 100         docstring const printbindings(FuncRequest const & func) const;
 101
 102         struct Binding {
 103                 Binding(FuncRequest const & r, KeySequence const & s, int t)
 104                         : request(r), sequence(s), tag(t) {}
 105                 FuncRequest request;
 106                 KeySequence sequence;
 107                 int tag;
 108         };
 109         typedef std::vector<Binding> BindingList;
 110         /**
 111          * Return all lfun and their associated bindings.
 112          * @param unbound list unbound (func without any keybinding) as well
 113          * @param tag an optional tag to indicate the source of the bindinglist
 114          */
 115         BindingList listBindings(bool unbound, int tag = 0) const;
 116
 117         /**
 118          *  Given an action, find the first 1-key binding (if it exists).
 119          *  The KeySymbol pointer is 0 is no key is found.
 120          *  [only used by the Qt/Mac frontend]
 121          */
 122         std::pair<KeySymbol, KeyModifier>
 123         find1keybinding(FuncRequest const & func) const;
 124
 125
 126         /**
 127          * Returns a string of the given keysym, with modifiers.
 128          * @param key the key as a keysym
 129          * @param mod the modifiers
 130          */
 131         static std::string const printKeySym(KeySymbol const & key,
 132                                              KeyModifier mod);
 133
 134         typedef std::pair<KeyModifier, KeyModifier> ModifierPair;
 135
 136
 137 private:
 138         ///
 139         struct Key {
 140                 /// Keysym
 141                 KeySymbol code;
 142
 143                 /// Modifier masks
 144                 ModifierPair mod;
 145
 146                 /// Keymap for prefix keys
 147                 boost::shared_ptr<KeyMap> table;
 148
 149                 /// Action for !prefix keys
 150                 FuncRequest func;
 151         };
 152
 153         /**
 154          * Given an action, find all keybindings
 155          * @param func the action
 156          * @param prefix a sequence to prepend the results
 157          */
 158         Bindings findbindings(FuncRequest const & func,
 159                               KeySequence const & prefix) const;
 160
 161         void listBindings(BindingList & list, KeySequence const & prefix,
 162                                   int tag) const;
 163
 164         /// is the table empty ?
 165         bool empty() const { return table.empty(); }
 166         ///
 167         typedef std::vector<Key> Table;
 168         ///
 169         Table table;
 170 };
 171
 172 /// Implementation is in LyX.cpp
 173 extern KeyMap & theTopLevelKeymap();
 174
 175
 176 } // namespace lyx
 177
 178 #endif // KEYMAP_H