X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=runtime%2Fhelp%2Fkeybindings.md;h=305e04a8c0ca93f60e451d3ffc4ade795c49276d;hb=1dc1c65565dce81226c6f39610a4f971b61aeeec;hp=73e95a6c7c2c354dc3ba38ac9aff42eb04d90d4e;hpb=41065f02228e87a12e53017c9c8e47f518c5ff43;p=micro.git diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md index 73e95a6c..305e04a8 100644 --- a/runtime/help/keybindings.md +++ b/runtime/help/keybindings.md @@ -1,87 +1,29 @@ # 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` (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. -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 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. -# Rebinding keys +## Rebinding keys -The bindings may be rebound using the `~/.config/micro/bindings.json` -file. Each key is bound to an action. +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. @@ -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 ` 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 { @@ -102,7 +47,99 @@ and quit you can bind it like so: } ``` -# Bindable actions and bindable keys +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 + +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 +`None` 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. @@ -128,16 +165,22 @@ WordRight WordLeft SelectWordRight SelectWordLeft +MoveLinesUp +MoveLinesDown DeleteWordRight DeleteWordLeft +SelectLine SelectToStartOfLine SelectToEndOfLine InsertNewline InsertSpace Backspace Delete +Center InsertTab Save +SaveAll +SaveAs Find FindNext FindPrevious @@ -157,10 +200,14 @@ Start End PageUp PageDown +SelectPageUp +SelectPageDown HalfPageUp HalfPageDown StartOfLine EndOfLine +ParagraphPrevious +ParagraphNext ToggleHelp ToggleRuler JumpLine @@ -168,11 +215,35 @@ ClearStatus ShellMode CommandMode Quit +QuitAll AddTab PreviousTab NextTab NextSplit +Unsplit +VSplit +HSplit PreviousSplit +ToggleMacro +PlayMacro +Suspend (Unix only) +ScrollUp +ScrollDown +SpawnMultiCursor +SpawnMultiCursorSelect +RemoveMultiCursor +RemoveAllMultiCursors +SkipMultiCursor +None +JumpToMatchingBrace +Autocomplete +``` + +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: @@ -297,15 +368,142 @@ CtrlRightSq CtrlCarat CtrlUnderscore Backspace +OldBackspace Tab 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": "Autocomplete|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", + "CtrlPageUp": "PreviousTab", + "CtrlPageDown": "NextTab", + "CtrlG": "ToggleHelp", + "Alt-g": "ToggleKeyMenu", + "CtrlR": "ToggleRuler", + "CtrlL": "command-edit:goto ", + "Delete": "Delete", + "CtrlB": "ShellMode", + "CtrlQ": "Quit", + "CtrlE": "CommandMode", + "CtrlW": "NextSplit", + "CtrlU": "ToggleMacro", + "CtrlJ": "PlayMacro", + "Insert": "ToggleOverwriteMode", + + // Emacs-style keybindings + "Alt-f": "WordRight", + "Alt-b": "WordLeft", + "Alt-a": "StartOfLine", + "Alt-e": "EndOfLine", + + // Integration with file managers + "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", + + "Alt-n": "SpawnMultiCursor", + "Alt-m": "SpawnMultiCursorSelect", + "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). + +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.