Add railscast colorscheme

[micro.git] / runtime / help / keybindings.md

diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md
index 963c8bcac71e46acac89e764cf6adf9ae43b5734..0a76a8a4355d0ec09ca3ff1c76dd347dac926cf4 100644 (file)
--- a/runtime/help/keybindings.md
+++ b/runtime/help/keybindings.md
@@ -1,87 +1,29 @@
 # Keybindings
 
 # Keybindings
 

-Here are the default keybindings in json form which is also how
-you can rebind them to your liking.
+Micro has a plethora of hotkeys that make it easy and powerful to use and all
+hotkeys are fully customizable to your liking.

 
 

-```json
-{
-       "Up":             "CursorUp",
-       "Down":           "CursorDown",
-       "Right":          "CursorRight",
-       "Left":           "CursorLeft",
-       "ShiftUp":        "SelectUp",
-       "ShiftDown":      "SelectDown",
-       "ShiftLeft":      "SelectLeft",
-       "ShiftRight":     "SelectRight",
-       "AltLeft":        "WordLeft",
-       "AltRight":       "WordRight",
-       "AltShiftRight":  "SelectWordRight",
-       "AltShiftLeft":   "SelectWordLeft",
-       "CtrlLeft":       "StartOfLine",
-       "CtrlRight":      "EndOfLine",
-       "CtrlShiftLeft":  "SelectToStartOfLine",
-       "CtrlShiftRight": "SelectToEndOfLine",
-       "CtrlUp":         "CursorStart",
-       "CtrlDown":       "CursorEnd",
-       "CtrlShiftUp":    "SelectToStart",
-       "CtrlShiftDown":  "SelectToEnd",
-       "Enter":          "InsertEnter",
-       "Space":          "InsertSpace",
-       "Backspace":      "Backspace",
-       "Backspace2":     "Backspace",
-       "Alt-Backspace":  "DeleteWordLeft",
-       "Alt-Backspace2": "DeleteWordLeft",
-       "Tab":            "InsertTab,IndentSelection",
-       "CtrlO":          "OpenFile",
-       "CtrlS":          "Save",
-       "CtrlF":          "Find",
-       "CtrlN":          "FindNext",
-       "CtrlP":          "FindPrevious",
-       "CtrlZ":          "Undo",
-       "CtrlY":          "Redo",
-       "CtrlC":          "Copy",
-       "CtrlX":          "Cut",
-       "CtrlK":          "CutLine",
-       "CtrlD":          "DuplicateLine",
-       "CtrlV":          "Paste",
-       "CtrlA":          "SelectAll",
-       "CtrlT":          "AddTab"
-       "CtrlRightSq":    "PreviousTab",
-       "CtrlBackslash":  "NextTab",
-       "Home":           "Start",
-       "End":            "End",
-       "PageUp":         "CursorPageUp",
-       "PageDown":       "CursorPageDown",
-       "CtrlG":          "ToggleHelp",
-       "CtrlR":          "ToggleRuler",
-       "CtrlL":          "JumpLine",
-       "Delete":         "Delete",
-       "Esc":            "ClearStatus",
-       "CtrlB":          "ShellMode",
-       "CtrlQ":          "Quit",
-       "CtrlE":          "CommandMode",
-       "CtrlW":          "NextSplit",
-       
-       // Emacs-style keybindings
-       "Alt-f": "WordRight",
-       "Alt-b": "WordLeft",
-       "Alt-a": "StartOfLine",
-       "Alt-e": "EndOfLine",
-       "Alt-p": "CursorUp",
-       "Alt-n": "CursorDown"
-}
-```
+Custom keybindings are stored internally in micro if changed with the `> bind`
+command or you can also be added in the file `~/.config/micro/bindings.json` as
+discussed below.  For a list of the default keybindings in the json format used
+by micro, please see the end of this file. For a more user-friendly list with
+explanations of what the default hotkeys are and what they do, please see
+`>help defaultkeys`

 
 

-You can use the alt keys + arrows to move word by word.
-Ctrl left and right move the cursor to the start and end of the line, and
-ctrl up and down move the cursor the start and end of the buffer.
+If `~/.config/micro/bindings.json` does not exist, you can simply create it.
+Micro will know what to do with it.
+
+You can use the alt keys + arrows to move word by word. Ctrl left and right move
+the cursor to the start and end of the line, and ctrl up and down move the
+cursor the start and end of the buffer.

 
 You can hold shift with all of these movement actions to select while moving.
 
 
 You can hold shift with all of these movement actions to select while moving.
 

-# Rebinding keys

 
 

-The bindings may be rebound using the `~/.config/micro/bindings.json`
-file. Each key is bound to an action.
+## Rebinding keys
+
+The bindings may be rebound using the `~/.config/micro/bindings.json` file. Each
+key is bound to an action.

 
 For example, to bind `Ctrl-y` to undo and `Ctrl-z` to redo, you could put the
 following in the `bindings.json` file.
 
 For example, to bind `Ctrl-y` to undo and `Ctrl-z` to redo, you could put the
 following in the `bindings.json` file.


@@ -93,8 +35,11 @@ following in the `bindings.json` file.
 }
 ```
 
 }
 ```
 

-You can also chain commands when rebinding. For example, if you want Alt-s to save
-and quit you can bind it like so:
+In addition to editing your `~/.config/micro/bindings.json`, you can run
+`>bind <keycombo> <action>` For a list of bindable actions, see below.
+
+You can also chain commands when rebinding. For example, if you want Alt-s to
+save and quit you can bind it like so:

 
 ```json
 {
 
 ```json
 {


@@ -102,7 +47,86 @@ and quit you can bind it like so:
 }
 ```
 
 }
 ```
 

-# Bindable actions and bindable keys
+## Binding commands
+
+You can also bind a key to execute a command in command mode (see 
+`help commands`). Simply prepend the binding with `command:`. For example:
+
+```json
+{
+    "Alt-p": "command:pwd"
+}
+```
+
+Now when you press `Alt-p` the `pwd` command will be executed which will show
+your working directory in the infobar.
+
+You can also bind an "editable" command with `command-edit:`. This means that 
+micro won't immediately execute the command when you press the binding, but
+instead just place the string in the infobar in command mode. For example, 
+you could rebind `CtrlG` to `> help`:
+
+```json
+{
+    "CtrlG": "command-edit:help "
+}
+```
+
+Now when you press `CtrlG`, `help` will appear in the command bar and your cursor will
+be placed after it (note the space in the json that controls the cursor placement).
+
+## Binding raw escape sequences
+
+Only read this section if you are interested in binding keys that aren't on the 
+list of supported keys for binding.
+
+One of the drawbacks of using a terminal-based editor is that the editor must
+get all of its information about key events through the terminal. The terminal
+sends these events in the form of escape sequences often (but not always)
+starting with `0x1b`. 
+
+For example, if micro reads `\x1b[1;5D`, on most terminals this will mean the
+user pressed CtrlLeft.
+
+For many key chords though, the terminal won't send any escape code or will send
+an escape code already in use. For example for `CtrlBackspace`, my terminal
+sends `\u007f` (note this doesn't start with `0x1b`), which it also sends for
+`Backspace` meaning micro can't bind `CtrlBackspace`.
+
+However, some terminals do allow you to bind keys to send specific escape
+sequences you define. Then from micro you can directly bind those escape
+sequences to actions. For example, to bind `CtrlBackspace` you can instruct your
+terminal to send `\x1bctrlback` and then bind it in `bindings.json`:
+
+```json
+{
+    "\u001bctrlback": "DeleteWordLeft"
+}
+```
+
+Here are some instructions for sending raw escapes in different terminals
+
+### iTerm2
+
+In iTerm2, you can do this in  `Preferences->Profiles->Keys` then click the `+`,
+input your keybinding, and for the `Action` select `Send Escape Sequence`. For
+the above example your would type `ctrlback` into the box (the `\x1b`) is
+automatically sent by iTerm2.
+
+### Linux using loadkeys
+
+You can do this in linux using the loadkeys program.
+
+Coming soon!
+
+
+## Unbinding keys
+
+It is also possible to disable any of the default key bindings by use of the 
+`UnbindKey` action in the user's `bindings.json` file.
+
+
+## Bindable actions and bindable keys

 
 The list of default keybindings contains most of the possible actions and keys
 which you can use, but not all of them. Here is a full list of both.
 
 The list of default keybindings contains most of the possible actions and keys
 which you can use, but not all of them. Here is a full list of both.


@@ -128,6 +152,8 @@ WordRight
 WordLeft
 SelectWordRight
 SelectWordLeft
 WordLeft
 SelectWordRight
 SelectWordLeft

+MoveLinesUp
+MoveLinesDown

 DeleteWordRight
 DeleteWordLeft
 SelectToStartOfLine
 DeleteWordRight
 DeleteWordLeft
 SelectToStartOfLine


@@ -139,6 +165,8 @@ Delete
 Center
 InsertTab
 Save
 Center
 InsertTab
 Save

+SaveAll
+SaveAs

 Find
 FindNext
 FindPrevious
 Find
 FindNext
 FindPrevious


@@ -162,6 +190,8 @@ HalfPageUp
 HalfPageDown
 StartOfLine
 EndOfLine
 HalfPageDown
 StartOfLine
 EndOfLine

+ParagraphPrevious
+ParagraphNext

 ToggleHelp
 ToggleRuler
 JumpLine
 ToggleHelp
 ToggleRuler
 JumpLine


@@ -169,11 +199,33 @@ ClearStatus
 ShellMode
 CommandMode
 Quit
 ShellMode
 CommandMode
 Quit

+QuitAll

 AddTab
 PreviousTab
 NextTab
 NextSplit
 AddTab
 PreviousTab
 NextTab
 NextSplit

+Unsplit
+VSplit
+HSplit

 PreviousSplit
 PreviousSplit

+ToggleMacro
+PlayMacro
+Suspend (Unix only)
+ScrollUp
+ScrollDown
+SpawnMultiCursor
+RemoveMultiCursor
+RemoveAllMultiCursors
+SkipMultiCursor
+UnbindKey
+JumpToMatchingBrace
+```
+
+You can also bind some mouse actions (these must be bound to mouse buttons)
+
+```
+MousePress
+MouseMultiCursor

 ```
 
 Here is the list of all possible keys you can bind:
 ```
 
 Here is the list of all possible keys you can bind:


@@ -302,11 +354,128 @@ Tab
 Esc
 Escape
 Enter
 Esc
 Escape
 Enter

-Backspace2

 ```
 
 ```
 

-Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a`
-or `Alt-Up`. Micro supports an optional `-` between modifiers like `Alt` and `Ctrl`
-so `Alt-a` could be rewritten as `Alta` (case matters for alt bindings). This is
-why in the default keybindings you can see `AltShiftLeft` instead of `Alt-ShiftLeft` 
-(they are equivalent).
+You can also bind some mouse buttons (they may be bound to normal actions or
+mouse actions)
+
+```
+MouseLeft
+MouseMiddle
+MouseRight
+MouseWheelUp
+MouseWheelDown
+MouseWheelLeft
+MouseWheelRight
+```
+
+# Default keybinding configuration.
+
+```json
+{
+    "Up":             "CursorUp",
+    "Down":           "CursorDown",
+    "Right":          "CursorRight",
+    "Left":           "CursorLeft",
+    "ShiftUp":        "SelectUp",
+    "ShiftDown":      "SelectDown",
+    "ShiftLeft":      "SelectLeft",
+    "ShiftRight":     "SelectRight",
+    "AltLeft":        "WordLeft",
+    "AltRight":       "WordRight",
+    "AltUp":          "MoveLinesUp",
+    "AltDown":        "MoveLinesDown",
+    "AltShiftRight":  "SelectWordRight",
+    "AltShiftLeft":   "SelectWordLeft",
+    "CtrlLeft":       "StartOfLine",
+    "CtrlRight":      "EndOfLine",
+    "CtrlShiftLeft":  "SelectToStartOfLine",
+    "ShiftHome":      "SelectToStartOfLine",
+    "CtrlShiftRight": "SelectToEndOfLine",
+    "ShiftEnd":       "SelectToEndOfLine",
+    "CtrlUp":         "CursorStart",
+    "CtrlDown":       "CursorEnd",
+    "CtrlShiftUp":    "SelectToStart",
+    "CtrlShiftDown":  "SelectToEnd",
+    "Alt-{":          "ParagraphPrevious",
+    "Alt-}":          "ParagraphNext",
+    "Enter":          "InsertNewline",
+    "CtrlH":          "Backspace",
+    "Backspace":      "Backspace",
+    "Alt-CtrlH":      "DeleteWordLeft",
+    "Alt-Backspace":  "DeleteWordLeft",
+    "Tab":            "IndentSelection,InsertTab",
+    "Backtab":        "OutdentSelection,OutdentLine",
+    "CtrlO":          "OpenFile",
+    "CtrlS":          "Save",
+    "CtrlF":          "Find",
+    "CtrlN":          "FindNext",
+    "CtrlP":          "FindPrevious",
+    "CtrlZ":          "Undo",
+    "CtrlY":          "Redo",
+    "CtrlC":          "Copy",
+    "CtrlX":          "Cut",
+    "CtrlK":          "CutLine",
+    "CtrlD":          "DuplicateLine",
+    "CtrlV":          "Paste",
+    "CtrlA":          "SelectAll",
+    "CtrlT":          "AddTab",
+    "Alt,":           "PreviousTab",
+    "Alt.":           "NextTab",
+    "Home":           "StartOfLine",
+    "End":            "EndOfLine",
+    "CtrlHome":       "CursorStart",
+    "CtrlEnd":        "CursorEnd",
+    "PageUp":         "CursorPageUp",
+    "PageDown":       "CursorPageDown",
+    "CtrlG":          "ToggleHelp",
+    "CtrlR":          "ToggleRuler",
+    "CtrlL":          "JumpLine",
+    "Delete":         "Delete",
+    "CtrlB":          "ShellMode",
+    "CtrlQ":          "Quit",
+    "CtrlE":          "CommandMode",
+    "CtrlW":          "NextSplit",
+    "CtrlU":          "ToggleMacro",
+    "CtrlJ":          "PlayMacro",
+
+    // Emacs-style keybindings
+    "Alt-f": "WordRight",
+    "Alt-b": "WordLeft",
+    "Alt-a": "StartOfLine",
+    "Alt-e": "EndOfLine",
+
+    // Integration with file managers
+    "F1":  "ToggleHelp",
+    "F2":  "Save",
+    "F3":  "Find",
+    "F4":  "Quit",
+    "F7":  "Find",
+    "F10": "Quit",
+    "Esc": "Escape",
+
+    // Mouse bindings
+    "MouseWheelUp":   "ScrollUp",
+    "MouseWheelDown": "ScrollDown",
+    "MouseLeft":      "MousePress",
+    "MouseMiddle":    "PastePrimary",
+    "Ctrl-MouseLeft": "MouseMultiCursor",
+
+    // Multiple cursors bindings
+    "Alt-n": "SpawnMultiCursor",
+    "Alt-p": "RemoveMultiCursor",
+    "Alt-c": "RemoveAllMultiCursors",
+    "Alt-x": "SkipMultiCursor",
+}
+```
+
+## Final notes
+
+Note: On some old terminal emulators and on Windows machines, `CtrlH` should be
+used for backspace.
+
+Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or
+`Alt-Up`. Micro supports an optional `-` between modifiers like `Alt` and 
+`Ctrl` so `Alt-a` could be rewritten as `Alta` (case matters for alt bindings).
+This is why in the default keybindings you can see `AltShiftLeft` instead of
+`Alt-ShiftLeft` (they are equivalent).