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 [`f` commands][f-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 key
  53   press is part of the [shortcut] for a command, it is usually consumed by
  54   VimFx. If not, Normal mode and Ignore mode pass the key press on (letting it
  55   behave as if VimFx wasn’t even installed), while in [Hints mode][f-commands]
  56   _all_ key presses are captured, allowing you to type the letters of a hint
  57   marker.
  58
  59 - It tells all parts of VimFx what mode you’re in. (How surprising!) Some
  60   features are only enabled in certain modes. For example, [autofocus
  61   prevention] in only enabled in Normal mode.
  62
  63 All modes have a way to return to Normal mode. By default, you usually press
  64 `<escape>`. To enter other modes, you usually run some command. For example, the
  65 default shortcut for running the command to enter Normal mode is `i`.
  66
  67 Note that the mode is per tab, not global.
  68
  69
  70 [blacklist]: options.md#blacklist
  71 [autofocus prevention]: options.md#prevent-autofocus
  72 [shortcut]: shortcuts.md
  73 [f-commands]: commands.md#the-f-commands--hints-mode
  74 [v-commands]: commands.md#the-v-commands--caret-mode
  75 [button]: button.md