Merge branch 'master' of https://github.com/dbeef/micro into dbeef-master

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

diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md
index 240305633e573ddd1340639ddc56ddbaf96f2383..305e04a8c0ca93f60e451d3ffc4ade795c49276d 100644 (file)
--- a/runtime/help/keybindings.md
+++ b/runtime/help/keybindings.md
@@ -5,10 +5,11 @@ hotkeys are fully customizable to your liking.
 
 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
 
 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
+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
 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`
+`> help defaultkeys` (a json formatted list of default keys is included
+at the end of this document).

 
 If `~/.config/micro/bindings.json` does not exist, you can simply create it.
 Micro will know what to do with it.
 
 If `~/.config/micro/bindings.json` does not exist, you can simply create it.
 Micro will know what to do with it.


@@ -19,7 +20,6 @@ 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
 ## Rebinding keys
 
 The bindings may be rebound using the `~/.config/micro/bindings.json` file. Each


@@ -47,6 +47,48 @@ save and quit you can bind it like so:
 }
 ```
 
 }
 ```
 

+Each action will return a success flag. Actions can be chained such that
+the chain only continues when there are successes, or failures, or either.
+The `,` separator will always chain to the next action. The `|` separator
+will abort the chain if the action preceding it succeeds, and the `&` will
+abort the chain if the action preceding it fails. For example, in the default
+bindings, tab is bound as
+
+```
+"Tab": "Autocomplete|IndentSelection|InsertTab"
+```
+
+This means that if the `Autocomplete` action is successful, the chain will abort.
+Otherwise, it will try `IndentSelection`, and if that fails too, it will
+execute `InsertTab`.
+
+## 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
 
 
 ## Binding raw escape sequences
 


@@ -92,12 +134,10 @@ You can do this in linux using the loadkeys program.
 
 Coming soon!
 
 
 Coming soon!
 

-

 ## Unbinding keys
 
 It is also possible to disable any of the default key bindings by use of the 
 ## 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.
-
+`None` action in the user's `bindings.json` file.

 
 ## Bindable actions and bindable keys
 
 
 ## Bindable actions and bindable keys
 


@@ -129,6 +169,7 @@ MoveLinesUp
 MoveLinesDown
 DeleteWordRight
 DeleteWordLeft
 MoveLinesDown
 DeleteWordRight
 DeleteWordLeft

+SelectLine

 SelectToStartOfLine
 SelectToEndOfLine
 InsertNewline
 SelectToStartOfLine
 SelectToEndOfLine
 InsertNewline


@@ -159,6 +200,8 @@ Start
 End
 PageUp
 PageDown
 End
 PageUp
 PageDown

+SelectPageUp
+SelectPageDown

 HalfPageUp
 HalfPageDown
 StartOfLine
 HalfPageUp
 HalfPageDown
 StartOfLine


@@ -187,10 +230,13 @@ Suspend (Unix only)
 ScrollUp
 ScrollDown
 SpawnMultiCursor
 ScrollUp
 ScrollDown
 SpawnMultiCursor

+SpawnMultiCursorSelect

 RemoveMultiCursor
 RemoveAllMultiCursors
 SkipMultiCursor
 RemoveMultiCursor
 RemoveAllMultiCursors
 SkipMultiCursor

-UnbindKey
+None
+JumpToMatchingBrace
+Autocomplete

 ```
 
 You can also bind some mouse actions (these must be bound to mouse buttons)
 ```
 
 You can also bind some mouse actions (these must be bound to mouse buttons)


@@ -322,6 +368,7 @@ CtrlRightSq
 CtrlCarat
 CtrlUnderscore
 Backspace
 CtrlCarat
 CtrlUnderscore
 Backspace

+OldBackspace

 Tab
 Esc
 Escape
 Tab
 Esc
 Escape


@@ -376,8 +423,8 @@ MouseWheelRight
     "Backspace":      "Backspace",
     "Alt-CtrlH":      "DeleteWordLeft",
     "Alt-Backspace":  "DeleteWordLeft",
     "Backspace":      "Backspace",
     "Alt-CtrlH":      "DeleteWordLeft",
     "Alt-Backspace":  "DeleteWordLeft",

-    "Tab":            "IndentSelection,InsertTab",
-    "Backtab":        "OutdentSelection,OutdentLine",
+    "Tab":            "Autocomplete|IndentSelection|InsertTab",
+    "Backtab":        "OutdentSelection|OutdentLine",

     "CtrlO":          "OpenFile",
     "CtrlS":          "Save",
     "CtrlF":          "Find",
     "CtrlO":          "OpenFile",
     "CtrlS":          "Save",
     "CtrlF":          "Find",


@@ -400,9 +447,12 @@ MouseWheelRight
     "CtrlEnd":        "CursorEnd",
     "PageUp":         "CursorPageUp",
     "PageDown":       "CursorPageDown",
     "CtrlEnd":        "CursorEnd",
     "PageUp":         "CursorPageUp",
     "PageDown":       "CursorPageDown",

+    "CtrlPageUp":     "PreviousTab",
+    "CtrlPageDown":   "NextTab",

     "CtrlG":          "ToggleHelp",
     "CtrlG":          "ToggleHelp",

+    "Alt-g":          "ToggleKeyMenu",

     "CtrlR":          "ToggleRuler",
     "CtrlR":          "ToggleRuler",

-    "CtrlL":          "JumpLine",
+    "CtrlL":          "command-edit:goto ",

     "Delete":         "Delete",
     "CtrlB":          "ShellMode",
     "CtrlQ":          "Quit",
     "Delete":         "Delete",
     "CtrlB":          "ShellMode",
     "CtrlQ":          "Quit",


@@ -410,6 +460,7 @@ MouseWheelRight
     "CtrlW":          "NextSplit",
     "CtrlU":          "ToggleMacro",
     "CtrlJ":          "PlayMacro",
     "CtrlW":          "NextSplit",
     "CtrlU":          "ToggleMacro",
     "CtrlJ":          "PlayMacro",

+    "Insert":         "ToggleOverwriteMode",

 
     // Emacs-style keybindings
     "Alt-f": "WordRight",
 
     // Emacs-style keybindings
     "Alt-f": "WordRight",


@@ -418,7 +469,6 @@ MouseWheelRight
     "Alt-e": "EndOfLine",
 
     // Integration with file managers
     "Alt-e": "EndOfLine",
 
     // Integration with file managers

-    "F1":  "ToggleHelp",

     "F2":  "Save",
     "F3":  "Find",
     "F4":  "Quit",
     "F2":  "Save",
     "F3":  "Find",
     "F4":  "Quit",


@@ -433,11 +483,11 @@ MouseWheelRight
     "MouseMiddle":    "PastePrimary",
     "Ctrl-MouseLeft": "MouseMultiCursor",
 
     "MouseMiddle":    "PastePrimary",
     "Ctrl-MouseLeft": "MouseMultiCursor",
 

-    // Multiple cursors bindings

     "Alt-n": "SpawnMultiCursor",
     "Alt-n": "SpawnMultiCursor",

+    "Alt-m": "SpawnMultiCursorSelect",

     "Alt-p": "RemoveMultiCursor",
     "Alt-c": "RemoveAllMultiCursors",
     "Alt-p": "RemoveMultiCursor",
     "Alt-c": "RemoveAllMultiCursors",

-    "Alt-x": "SkipMultiCursor",
+    "Alt-x": "SkipMultiCursor"

 }
 ```
 
 }
 ```
 


@@ -451,3 +501,9 @@ Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or
 `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).
 `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).

+
+Please note that terminal emulators are strange applications and micro only receives
+key events that the terminal decides to send. Some terminal emulators may not
+send certain events even if this document says micro can receive the event. To see
+exactly what micro receives from the terminal when you press a key, run the `> raw`
+command.