neurocyte/flow-website
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Links between developer docs

Browse source
This commit is contained in:
Igor Támara 2025-10-29 16:43:37 -05:00 • committed by CJ van den Berg
parent 5eedc17542
commit e837a66b97
10 changed files with 318 additions and 243 deletions
Download patch file Download diff file Expand all files Collapse all files

128
content/docs/architecture/keybind.smd
View file

@ -4,26 +4,31 @@
.author = "Igor Támara",
.layout = "tutorial.shtml",
.draft = false,
.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture/keybind.md"},
.custom = {
.githubedit = "/docs/architecture/keybind.smd",
.codepath ="src/keybind/builtin/",
},
---
If you are here, it's possible that you already have edited your
If you are here, maybe is because you want to make flow behave according
to your key presses preferences or possibly you already have edited your
own keybinds to suit your needs and are looking for some advanced
topics to extend your use cases and make everything easier and
fluid when in Flow. If you have not, take a peek to learning how
to do it.
topics to cope your use cases and make everything easier and
fluid when in Flow.
Using the command palette `Ctrl+Shift+p` and typing **Edit key bindings**,
takes you to the json file to extend Flow configuring
keybindings to suit your needs.
Using the command palette `Ctrl+Shift+p` and typing **Edit key
bindings**, takes you to the json file to extend Flow configuring
keybindings to suit your needs. According to the mode you are in, the
corresponding file will be opened. The palette can also be reached left
clicking on the current mode in the status bar.
[]($section.id('tldr'))
## ;TLDR;
Once you open the corresponding json file, locate inside the imode
(internal mode) that will accept the key or keys/combo and add an
array, where the first element is the combination to map to the
commands that will happen, the array accepts strings like in
(internal mode) that will accept the key or keys/combo and add an array,
where the first element is the combination to map to the commands that
will happen, the array accepts strings like in
```js
["ctrl+alt+shift+p", "open_command_palette"]
@ -32,33 +37,37 @@ commands that will happen, the array accepts strings like in
To avoid screwing up the combinations, and putting Flow in an unusable
state derived from a wrong mapping of key combinations, read on.
[]($section.id('defaults'))
## Resetting keys to factory defaults
User configured keybindings are stored in Flow's configuration
directory under `keys/mode.json` where mode can be `flow`,
`emacs`, `vim`, `helix` or customized ones. Removing the keys
directory or the particular mode file can take you out from a
broken state.
User configured keybindings are stored in Flow's configuration directory
under `keys/mode.json` where mode can be `flow`, `emacs`, `vim`, `helix`
or customized ones. Removing the keys directory or the particular mode
file can take you out from a broken state.
[]($section.id('modes'))
## Keybinds for each mode
Keybinds are edited per mode, and other modes inherit what is
defined in your `flow.json` keybindings. Each mode override keybindings
of its parent mode. For example, if you are in **emacs** mode you will
be redirected to `emacs.json` and it will override the keybindings from
Keybinds are edited per mode, and other modes inherit what is defined
in your `flow.json` keybindings. Each mode override keybindings of its
parent mode. For example, if you are in **emacs** mode you will be
redirected to `emacs.json` and it will override the keybindings from
flow.
[introducing keybindings](/devlog/2024#2024-12-05T20:55:00) showcases
how to get to edit keybindings.
[]($section.id('hierarchy'))
## Keybindings hierarchy
Some terminology
* **Mode**: Stored in a json file, like flow mode declared in `flow.json`.
* **Mode**: Stored in a json file, like flow mode declared in
`flow.json`.
* **Imode**: under the json file.
* **Major Imode**: `project` or descendant from `project`.
* **Minimodes**: To be used momentarily and do not inherit from `project`.
* **Minimodes**: To be used momentarily and do not inherit from
`project`.
In general a keybinding json shows this hierarchy:
@ -67,41 +76,40 @@ Mode > Imode > press > Key and commands
map > map > array > array(array(string,numbers),strings,numbers)
```
`Mode` is the json file that holds a map, where each
entry has a map called `press` that is an array of
arrays.
`Mode` is the json file that holds a map, where each entry has a map
called `press` that is an array of arrays.
`project` is the main imode in `flow.json` and it can be
noticed that `normal` imode `inherit`s from `project`,
some modes have `release`, usually one will be using
only `press` inside `normal` imode or the specific mode
if inside `vim`, `helix` or `emacs` modes.
`project` is the main imode in `flow.json` and it can be noticed that
`normal` imode `inherit`s from `project`, some modes have `release`,
usually one will be using only `press` inside `normal` imode or the
specific mode if inside `vim`, `helix` or `emacs` modes.
Looking further, it can be seen that
[minimodes](/docs/architecture/minimode) have their
keybinding mappings defined in a particular imode.
[minimodes](/docs/architecture/minimode) have their keybinding mappings
defined in a particular imode.
As stated previously, there is a mode hierarchy, the main mode
is flow and other modes inherit from it. We remind that also
imodes have a hierarchy and it's common for major imodes to be
descendants from `project`.
As stated previously, there is a mode hierarchy, the main mode is flow
and other modes inherit from it. We remind that also imodes have a
hierarchy and it's common for major imodes to be descendants from
`project`.
[]($section.id('adding'))
## Adding a Keybinding
The most basic case to map a keybind to a command was covered in
[TLDR](#tldr) which used the combination of three keys pressed
simultaneously `ctrl`, `shift` and `p`, all of them where combined
with `+` to execute the command `open_command_palette`.
simultaneously `ctrl`, `shift` and `p`, all of them where combined with
`+` to execute the command `open_command_palette`.
A common use case is to add a keybinding to invoke an already
existing command and chain it to another, making Flow more suited to your
own needs.
A common use case is to add a keybinding to invoke an already existing
command and chain it to another, making Flow more suited to your own
needs.
[]($section.id('shell'))
## Running shell commands
For example, `f5` by default is used to run `zig build test`
outputting its results to a *scratch buffer* called `test`.
For example, `f5` by default is used to run `zig build test` outputting
its results to a *scratch buffer* called `test`.
```js
["f5", ["create_scratch_buffer", "*test*"], ["shell_execute_insert", "zig", "build", "test"]],
@ -110,14 +118,13 @@ outputting its results to a *scratch buffer* called `test`.
Note that:
The keybind is `f5`, which maps to the `f5` keycode. is invoking
`create_scratchbuffer`, receiving the parameter `*test*` which
results in creating a scratch buffer if didn't exist. And
then executing the command `shell_execute_insert` that receives
the paramaters `zig`, `build`, `test`. This latter command is
executing a shell command called `zig` with the parameters
`build` and `test`; if you don't have zig installed, it will
not work, and you might want to remap f5 to a different shell
command.
`create_scratchbuffer`, receiving the parameter `*test*` which results
in creating a scratch buffer if didn't exist. And then executing the
command `shell_execute_insert` that receives the paramaters `zig`,
`build`, `test`. This latter command is executing a shell command
called `zig` with the parameters `build` and `test`; if you don't have
zig installed, it will not work, and you might want to remap `f5` to a
different shell command.
```
[
@ -138,8 +145,21 @@ command.
Observe [tasks running](/devlog/2025#2025-01-26T22:11:00) and maybe
consider using more keybindings or running tasks for your projects.
Probably binding commands is good, but maybe there is a feature in
other texts editors that you miss and would love to have it at
your fingertips. Then it's Zig time:
[]($section.id('next'))
## Next steps
If you realized that there is a handy combination that others can
benefit from or that a mode lacks the combination and it might be
included in flow, look at the [contribution guidelines](/docs/contributing)
to submit your findings and solution.
Probably binding commands is good, but maybe there is a feature in other
text editors that you miss and would love to have it at your fingertips.
Then it's Zig time:
[Adding commands](/docs/architecture/command) to flow.
* Making flow even better with [tests](/docs/testing)
* [How to contribute](/docs/contributing)
* [Get in touch](https://discord.com/invite/4wvteUPphx) to share your
combos