X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=runtime%2Fhelp%2Fkeybindings.md;h=305e04a8c0ca93f60e451d3ffc4ade795c49276d;hb=f2a1e2337f6957c6dfba86762651f9d63365aec0;hp=19aea8202338bbe24e7f38ea058e300f851a872d;hpb=a6ee75a9cfeedeebd5e1debc35846eb9667554ce;p=micro.git diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md index 19aea820..305e04a8 100644 --- a/runtime/help/keybindings.md +++ b/runtime/help/keybindings.md @@ -2,25 +2,28 @@ Micro has a plethora of hotkeys that make it easy and powerful to use and all 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 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` + +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. @@ -35,8 +38,8 @@ following in the `bindings.json` file. 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: +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 { @@ -44,12 +47,99 @@ and quit you can bind it like so: } ``` -# Unbinding 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 -`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 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. @@ -79,6 +169,7 @@ MoveLinesUp MoveLinesDown DeleteWordRight DeleteWordLeft +SelectLine SelectToStartOfLine SelectToEndOfLine InsertNewline @@ -109,10 +200,14 @@ Start End PageUp PageDown +SelectPageUp +SelectPageDown HalfPageUp HalfPageDown StartOfLine EndOfLine +ParagraphPrevious +ParagraphNext ToggleHelp ToggleRuler JumpLine @@ -131,7 +226,24 @@ HSplit PreviousSplit ToggleMacro PlayMacro -UnbindKey +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: @@ -256,12 +368,26 @@ CtrlRightSq CtrlCarat CtrlUnderscore Backspace +OldBackspace Tab Esc Escape Enter ``` +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 @@ -276,26 +402,29 @@ Enter "ShiftRight": "SelectRight", "AltLeft": "WordLeft", "AltRight": "WordRight", - "AltShiftRight": "SelectWordRight", - "AltShiftLeft": "SelectWordLeft", "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", - "Space": "InsertSpace", "CtrlH": "Backspace", "Backspace": "Backspace", "Alt-CtrlH": "DeleteWordLeft", "Alt-Backspace": "DeleteWordLeft", - "Tab": "IndentSelection,InsertTab", - "Backtab": "OutdentSelection", + "Tab": "Autocomplete|IndentSelection|InsertTab", + "Backtab": "OutdentSelection|OutdentLine", "CtrlO": "OpenFile", "CtrlS": "Save", "CtrlF": "Find", @@ -318,9 +447,12 @@ Enter "CtrlEnd": "CursorEnd", "PageUp": "CursorPageUp", "PageDown": "CursorPageDown", + "CtrlPageUp": "PreviousTab", + "CtrlPageDown": "NextTab", "CtrlG": "ToggleHelp", + "Alt-g": "ToggleKeyMenu", "CtrlR": "ToggleRuler", - "CtrlL": "JumpLine", + "CtrlL": "command-edit:goto ", "Delete": "Delete", "CtrlB": "ShellMode", "CtrlQ": "Quit", @@ -328,32 +460,50 @@ Enter "CtrlW": "NextSplit", "CtrlU": "ToggleMacro", "CtrlJ": "PlayMacro", + "Insert": "ToggleOverwriteMode", // Emacs-style keybindings "Alt-f": "WordRight", "Alt-b": "WordLeft", "Alt-a": "StartOfLine", "Alt-e": "EndOfLine", - "Alt-p": "CursorUp", - "Alt-n": "CursorDown", // 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", + + "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. +## 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). -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.