documentation/modes.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2016.
   4 See the file README.md for copying conditions.
   5 -->
   6
   7 # Modes
   8
   9 ## Summary
  10
  11 VimFx’s functionality is contained in an hierarchy.
  12
  13 1. There are several _modes._
  14
  15    Modes decide how VimFx works.
  16
  17 2. Each mode has several _commands._
  18
  19    Commands do things.
  20
  21 3. Each command has several _shortcuts._
  22
  23    Shortcuts tell which keys to press to activate a command.
  24
  25 These are the modes of VimFx:
  26
  27 - Normal mode. This is where you’ll stay most of the time, while only
  28   occasionally popping into another mode for a bit, before returning to Normal
  29   mode again.
  30
  31 - Ignore mode. When you want VimFx to get out of the way. In some pages it might
  32   make sense to [enter Ignore mode by default][blacklist] and stay in Ignore
  33   mode most of the time, occasionally popping into Normal mode.
  34
  35 - Hints mode. Entered when using the [hint commands][hint-commands] and lets you
  36   click things by typing the letters of hint markers.
  37
  38 - Caret mode. Entered when using some of the [`v` commands][v-commands] and lets
  39   you copy text using the keyboard.
  40
  41 If you’re unsure which mode you’re in, have a look at VimFx’s toolbar [button].
  42
  43
  44 ## Details
  45
  46 A mode does three things.
  47
  48 - It decides which _commands_ are available. Normal mode has lots of commands,
  49   while the point of Ignore mode is to have as few as possible. This is the most
  50   important point of modes.
  51
  52 - It decides what happens when you press keys on your keyboard. If your keypress
  53   is part of the [shortcut] for a command, it is usually consumed by VimFx. If
  54   not, Normal mode and Ignore mode pass the keypress on (letting it behave as if
  55   VimFx wasn’t even installed), while in [Hints mode][hint-commands] _all_
  56   keypresses are captured, allowing you to type the letters of a hint marker.
  57
  58 - It tells all parts of VimFx what mode you’re in. (How surprising!) Some
  59   features are only enabled in certain modes. For example, [autofocus
  60   prevention] in only enabled in Normal mode.
  61
  62 All modes have a way to return to Normal mode. By default, you usually press
  63 `<escape>`. To enter other modes, you usually run some command. For example, the
  64 default shortcut for running the command to enter Normal mode is `i`.
  65
  66 Note that the mode is per tab, not global.
  67
  68
  69 [blacklist]: options.md#blacklist
  70 [autofocus prevention]: options.md#prevent-autofocus
  71 [shortcut]: shortcuts.md
  72 [hint-commands]: commands.md#the-hint-commands--hints-mode
  73 [v-commands]: commands.md#the-v-commands--caret-mode
  74 [button]: button.md