doc/vis.rst

   1 Vis
   2 ===
   3
   4 The core Vis API.
   5
   6 Lifecycle
   7 ---------
   8
   9 .. doxygengroup:: vis_lifecycle
  10    :content-only:
  11
  12 Draw
  13 ----
  14
  15 .. doxygengroup:: vis_draw
  16    :content-only:
  17
  18 Windows
  19 -------
  20
  21 .. doxygengroup:: vis_windows
  22    :content-only:
  23
  24 Input
  25 -----
  26
  27 The editor core processes input through a sequences of symbolic keys:
  28
  29  * Special keys such as ``<Enter>``, ``<Tab>`` or ``<Backspace>`` as reported by
  30    `termkey_strfkey <http://www.leonerd.org.uk/code/libtermkey/doc/termkey_strfkey.3.html>`_.
  31
  32    .. note:: The prefixes ``C-``, ``S-`` and ``M-`` are used to denote the ``Ctrl``,
  33              ``Shift`` and ``Alt`` modifiers, respectively.
  34
  35  * Key action names as registered with `vis_action_register`.
  36
  37    .. note:: By convention they are prefixed with ``vis-`` as in ``<vis-nop>``.
  38
  39  * Regular UTF-8 encoded input.
  40
  41 .. note:: An exhaustive list of the first two types is displayed in the ``:help`` output.
  42
  43 .. doxygengroup:: vis_keys
  44    :content-only:
  45
  46 Key Map
  47 -------
  48
  49 The key map is used to translate keys in non-input modes, *before* any key
  50 bindings are evaluated. It is intended to facilitate usage of non-latin keyboard
  51 layouts.
  52
  53 .. doxygengroup:: vis_keymap
  54    :content-only:
  55
  56 Key Binding
  57 -----------
  58
  59 Each mode has a set of key bindings. A key binding maps a key to either
  60 another key (referred to as an alias) or a key action (implementing an
  61 editor operation).
  62
  63 If a key sequence is ambiguous (i.e. it is a prefix of multiple mappings)
  64 more input is awaited, until a unique mapping can be resolved.
  65
  66 .. warning:: Key aliases are always evaluated recursively.
  67
  68 .. doxygengroup:: vis_keybind
  69    :content-only:
  70
  71 Key Action
  72 ----------
  73
  74 A key action is invoked by a key binding and implements a certain editor function.
  75
  76 The editor operates like a finite state machine with key sequences as
  77 transition labels. Once a prefix of the input queue uniquely refers to a
  78 key action, it is invoked with the remainder of the input queue passed as argument.
  79
  80 .. note:: A triggered key action currently does not know through which key binding
  81           it was invoked. TODO: change that?
  82
  83 .. doxygengroup:: vis_action
  84    :content-only:
  85
  86 Modes
  87 -----
  88
  89 A mode defines *enter*, *leave* and *idle* actions and captures a set of
  90 key bindings.
  91
  92 Modes are hierarchical, key bindings are searched recursively towards
  93 the top of the hierarchy stopping at the first match.
  94
  95 .. doxygenenum:: VisMode
  96 .. doxygengroup:: vis_modes
  97    :content-only:
  98
  99 Count
 100 -----
 101
 102 Dictates how many times a motion or text object is evaluated. If none
 103 is specified, a minimal count of 1 is assumed.
 104
 105 .. doxygengroup:: vis_count
 106    :content-only:
 107
 108 Operators
 109 ---------
 110
 111 .. doxygengroup:: vis_operators
 112    :content-only:
 113
 114 Motions
 115 -------
 116
 117 .. doxygengroup:: vis_motions
 118    :content-only:
 119
 120 Text Objects
 121 ------------
 122
 123 .. doxygengroup:: vis_textobjs
 124    :content-only:
 125
 126 Marks
 127 -----
 128
 129 Marks keep track of a given text position.
 130
 131 .. note:: Marks are currently file local.
 132
 133 .. doxygengroup:: vis_marks
 134    :content-only:
 135
 136 Registers
 137 ---------
 138
 139 .. doxygengroup:: vis_registers
 140    :content-only:
 141
 142 Macros
 143 ------
 144
 145 Macros are a sequence of keys stored in a Register which can be reprocessed
 146 as if entered by the user.
 147
 148 .. warning:: Macro support is currently half-baked. If you do something stupid
 149              (e.g. use mutually recursive macros), you will likely encounter
 150              stack overflows.
 151
 152 .. doxygengroup:: vis_macros
 153    :content-only:
 154
 155 Commands
 156 --------
 157
 158 .. doxygengroup:: vis_cmds
 159    :content-only:
 160
 161 Options
 162 -------
 163
 164 .. doxygengroup:: vis_options
 165    :content-only:
 166
 167 Modification
 168 ------------
 169
 170 These function operate on the currently focused window but ensure that
 171 all windows which show the affected region are redrawn too.
 172
 173 .. doxygengroup:: vis_changes
 174    :content-only:
 175
 176 Interaction
 177 -----------
 178
 179 .. doxygengroup:: vis_info
 180    :content-only:
 181
 182 Miscellaneous
 183 -------------
 184
 185 .. doxygengroup:: vis_misc
 186    :content-only:
 187