Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve keyboard shortcuts documentation #1799

Merged
merged 4 commits into from
Jul 20, 2021
Merged

Improve keyboard shortcuts documentation #1799

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f923e6e
Improve keyboard shortcuts documentation
rchl Jul 20, 2021
00ecb84
unnecessary "and"
rchl Jul 20, 2021
f18077a
remove example how to override "auto_complete_open_link"
rchl Jul 20, 2021
262babe
a bit of grammar
rchl Jul 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions docs/src/customization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,59 @@ html {
to `Packages/User/mdpopups.css`.
See the [mdpopups documentation](http://facelessuser.github.io/sublime-markdown-popups/) for more details.

## Keyboard shortcuts (key bindings)

LSP's key bindings can be edited from the `Preferences: LSP Key Bindings` command from the Command Palette. Many of the default key bindings (visible in the left view) are disabled to avoid conflicts with default or user key bindings. To enable those, copy them to your user key bindings on the right, un-comment and pick the key shortcut of your choice.

If you want to customize the provided key bindings (or create new ones) and make them only be active when there is a language server with a specific [LSP capability](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize) (refer to the `ServerCapabilities` structure in that link) running, you can make use of the `lsp.session_with_capability` context. For example, the following example overrides `ctrl+r` to use LSP's symbol provider but only when the current view has a language server with the `documentSymbolProvider` capability and we're in a javascript or a typescript file:

```js
{
"command": "lsp_document_symbols",
"keys": [
"ctrl+r"
],
"context": [
{
"key": "lsp.session_with_capability",
"operator": "equal",
"operand": "documentSymbolProvider"
},
{
"key": "selector",
"operator": "equal",
"operand": "source.ts, source.js"
}
]
},
```

But generally you should not need to restrict your key bindings to specific scopes and just rely on checking the capability context.

## Mouse map configuration

If you want to bind some action to a mouse, open `Preferences / Browser Packages` from the main menu and create a sublime-mousemap file in the following location within the Packages folder:

| Platform | Path |
| -------- | ---- |
| Windows | `/User/Default (Windows).sublime-mousemap` |
| Linux | `/User/Default (Linux).sublime-mousemap` |
| Mac | `/User/Default (OSX).sublime-mousemap` |

Here is an example mouse binding that triggers LSP's "go to symbol definition" command on pressing the <kbd>ctrl</kbd>+<kbd>left click</kbd>:

```js
[
{
"button": "button1",
"count": 1,
"modifiers": ["ctrl"],
"press_command": "drag_select",
"command": "lsp_symbol_definition",
}
]
```

## Color scheme customizations

Some features use TextMate scopes to control the colors (underline, background or text color) of styled regions in a document or popup.
Expand Down
67 changes: 1 addition & 66 deletions docs/src/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,43 +66,6 @@ You can include special variables in the `command_args` array that will be autom
| `"$position"` or `"${position}"` | object | JSON object `{ 'line': int, 'character': int }` of the (topmost) cursor position, see [Position](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position) |
| `"$range"` or `"${range}"` | object | JSON object with `'start'` and `'end'` positions of the (topmost) selection, see [Range](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#range) |

### Overriding keybindings

LSP's keybindings can be edited from the `Preferences: LSP Keybindings` command from the command palette.
There is a special context called `lsp.session_with_capability` that can check whether there is a language server active
with the given [LSP capability](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize).
Refer to the `ServerCapabilities` structure in that link.
The following example overrides `ctrl+r` to use LSP's symbol provider when we're in a javascript or typescript view:
Comment on lines -71 to -75
Copy link
Member Author

@rchl rchl Jul 20, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll paste here the new text since it's not clear from the diff how this has changed.

LSP's key bindings can be edited from the Preferences: LSP Key Bindings command from the Command Palette. Many of the default key bindings (visible in the left view) are disabled to avoid conflicts with default or user key bindings. To enable those, copy them to your user key bindings on the right, un-comment and pick the key shortcut of your choice.

If you want to customize the provided key bindings (or create new ones) and make them only be active when there is a language server with a specific LSP capability (refer to the ServerCapabilities structure in that link) running, you can make use of the lsp.session_with_capability context. For example, the following example overrides ctrl+r to use LSP's symbol provider but only when the current view has a language server with the documentSymbolProvider capability and we're in a javascript or a typescript file:

Basically made the first paragraph talk about default (disabled) key bindings and how to enable them.
The second paragraph is the more advanced part about customizing key bindings (which I imagine most won't need as the provided default ones should be enough).


```js
{
"command": "lsp_document_symbols",
"keys": [
"ctrl+r"
],
"context": [
{
"key": "lsp.session_with_capability",
"operator": "equal",
"operand": "documentSymbolProvider"
},
{
"key": "selector",
"operator": "equal",
"operand": "source.ts, source.js"
}
]
},
```

More useful keybindings (OS-X), edit Package Settings -> LSP -> Key Bindings
```js
{ "keys": ["f2"], "command": "lsp_symbol_rename" },
{ "keys": ["f12"], "command": "lsp_symbol_definition" },
{ "keys": ["super+option+r"], "command": "lsp_document_symbols" },
{ "keys": ["super+option+h"], "command": "lsp_hover"}
```
Comment on lines -98 to -104
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've removed that part completely since those examples are bad as they don't check the context. And there are better versions of those in the default key bindings.


### Show autocomplete documentation

Some completion items can have documentation associated with them.
Expand All @@ -117,7 +80,7 @@ You can change the default keybinding by remapping the command as below:
```js
{
"command": "auto_complete_open_link",
"keys": ["f12"],
"keys": ["f13"],
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this example is about overriding the default F12 shortcut, I've changed it to something else than F12.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this example isn't really necessary at all, because it is just a default keybinding from ST and not specific to LSP? And you have already described how to define/override a keybinding in customization.md.
Btw, I think F-keys larger than F12 are macOS exclusive.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I agree, removed.

"context": [
{
"key": "auto_complete_visible",
Expand All @@ -127,31 +90,3 @@ You can change the default keybinding by remapping the command as below:
]
},
```
Note that <kbd>F12</kbd> may conflict with your Goto Definition keybinding. To avoid the conflict, make sure that you
have a context which checks that the AC widget is not visible:
```js
{
"command": "lsp_symbol_definition",
"keys": [
"f12"
],
"context": [
{
"key": "lsp.session_with_capability",
"operator": "equal",
"operand": "definitionProvider"
},
{
"key": "auto_complete_visible",
"operator": "equal",
"operand": false
}
]
},
```
There is an example of this in LSP's default keybindings.
Comment on lines -130 to -152
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part was in a very weird place, talking about F12 potentially conflicting with default binding after the example that shown how to override default F12 key binding without conflicting with "goto definition". I've deemed that part completely unnecessary and it was removed.


### Mouse map configuration

See below link, but bind to `lsp_symbol_definition` command
https://stackoverflow.com/questions/16235706/sublime-3-set-key-map-for-function-goto-definition