mirror of https://github.com/sayanarijit/xplr
Add more keyboard input handlers
This PR adds 3 more keyboard input handlers: - on_alphanumeric - on_character - on_navigation Also updates documentation.pull/399/head
Arijit Basu
3 years ago
committed by
Arijit Basu
parent
ca6cefb1c1
commit
b45a553a0c
@ -0,0 +1,223 @@
|
||||
# Configure Key Bindings
|
||||
|
||||
In xplr, each keyboard input passes through a bunch of handlers (e.g. `on_key`,
|
||||
`on_number`, `default` etc.) in a given order. If any of the handlers is
|
||||
configured to with an [action][16], it will intercept the key and produce
|
||||
[messages][18] for xplr to handle.
|
||||
|
||||
## Key Bindings
|
||||
|
||||
Key bindings contains the following information:
|
||||
|
||||
- [on_key][10]
|
||||
- [on_alphabet][11]
|
||||
- [on_number][12]
|
||||
- [on_alphanumeric][32]
|
||||
- [on_special_character][13]
|
||||
- [on_character][33]
|
||||
- [on_navigation][34]
|
||||
- [default][14]
|
||||
|
||||
### on_key
|
||||
|
||||
Type: mapping of [Key][15] to nullable [Action][16]
|
||||
|
||||
Defines what to do when an exact key is pressed.
|
||||
|
||||
### on_alphabet
|
||||
|
||||
Type: nullable [Action][16]
|
||||
|
||||
An action to perform if the keyboard input is an alphabet and is not mapped via
|
||||
the [on_key][10] field.
|
||||
|
||||
### on_number
|
||||
|
||||
Type: nullable [Action][16]
|
||||
|
||||
An action to perform if the keyboard input is a number and is not mapped via
|
||||
the [on_key][10] field.
|
||||
|
||||
### on_alphanumeric
|
||||
|
||||
Type: nullable [Action][16]
|
||||
|
||||
An action to perform if the keyboard input is alphanumeric and is not mapped
|
||||
via the [on_key][10], [on_alphabet][11] or [on_number][12] field.
|
||||
|
||||
### on_special_character
|
||||
|
||||
Type: nullable [Action][16]
|
||||
|
||||
An action to perform if the keyboard input is a special character and is not
|
||||
mapped via the [on_key][10] field.
|
||||
|
||||
### on_character
|
||||
|
||||
Type: nullable [Action][16]
|
||||
|
||||
An action to perform if the keyboard input is a character and is not mapped
|
||||
via the [on_key][10], [on_alphabet][11], [on_number][12], [on_alphanumeric][32]
|
||||
or [on_special_character][13] field.
|
||||
|
||||
### on_navigation
|
||||
|
||||
Type: nullable [Action][16]
|
||||
|
||||
An action to perform if the keyboard input is a navigation key and is not
|
||||
mapped via the [on_key][10] field.
|
||||
|
||||
### default
|
||||
|
||||
Type: nullable [Action][16]
|
||||
|
||||
Default action to perform in case if a keyboard input not mapped via any of the
|
||||
`on_*` fields mentioned above.
|
||||
|
||||
## Key
|
||||
|
||||
A key can be one of the following:
|
||||
|
||||
- 0, 1, ... 9
|
||||
- a, b, ... z
|
||||
- A, B, ... Z
|
||||
- f1, f2, ... f12
|
||||
- backspace
|
||||
- left
|
||||
- right
|
||||
- up
|
||||
- down
|
||||
- home
|
||||
- end
|
||||
- page-up
|
||||
- page-down
|
||||
- back-tab
|
||||
- delete
|
||||
- insert
|
||||
- enter
|
||||
- tab
|
||||
- esc
|
||||
- ctrl-a, ctrl-b, ... ctrl-z
|
||||
- ctrl-backspace, ctrl-left, ... ctrl-esc
|
||||
- alt-a, alt-b, ... alt-z
|
||||
|
||||
And finally, the special characters - including space (`" "`) with their `ctrl`
|
||||
bindings.
|
||||
|
||||
## Action
|
||||
|
||||
An action contains the following information:
|
||||
|
||||
- [help][1]
|
||||
- [messages][17]
|
||||
|
||||
### help
|
||||
|
||||
Type: nullable string
|
||||
|
||||
Description of what it does. If unspecified, it will be excluded from the help
|
||||
menu.
|
||||
|
||||
### messages
|
||||
|
||||
Type: A list of [Message][18] to send.
|
||||
|
||||
The list of messages to send when a key is pressed.
|
||||
|
||||
## Tutorial: Adding a New Mode
|
||||
|
||||
Assuming xplr is [installed][19] and [setup][20], let's
|
||||
add our own mode to integrate xplr with [fzf][21].
|
||||
|
||||
We'll call it `fzxplr` mode.
|
||||
|
||||
First, let's add a custom mode called `fzxplr`, and map the key `F` to an
|
||||
action that will call `fzf` to search and focus on a file or enter into a
|
||||
directory.
|
||||
|
||||
```lua
|
||||
xplr.config.modes.custom.fzxplr = {
|
||||
name = "fzxplr",
|
||||
key_bindings = {
|
||||
on_key = {
|
||||
F = {
|
||||
help = "search",
|
||||
messages = {
|
||||
{
|
||||
BashExec = [===[
|
||||
PTH=$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}" | awk -F/ '{print $NF}' | fzf)
|
||||
if [ -d "$PTH" ]; then
|
||||
echo ChangeDirectory: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
|
||||
else
|
||||
echo FocusPath: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
|
||||
fi
|
||||
]===]
|
||||
},
|
||||
"PopMode",
|
||||
},
|
||||
},
|
||||
},
|
||||
default = {
|
||||
messages = {
|
||||
"PopMode",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
As you can see, the key `F` in mode `fzxplr` (the name can be anything)
|
||||
executes a script in `bash`.
|
||||
|
||||
`BashExec`, `PopMode`, `SwitchModeBuiltin`, `ChangeDirectory` and `FocusPath`
|
||||
are [messages][18], `$XPLR_PIPE_MSG_IN`,
|
||||
`$XPLR_PIPE_DIRECTORY_NODES_OUT` are
|
||||
[environment variables][22] exported by `xplr`
|
||||
before executing the command. They contain the path to the
|
||||
[input][23] and [output][24] pipes that
|
||||
allows external tools to interact with `xplr`.
|
||||
|
||||
Now that we have our new mode ready, let's add an entry point to this mode via
|
||||
the `default` mode.
|
||||
|
||||
```lua
|
||||
xplr.config.modes.builtin.default.key_bindings.on_key["F"] = {
|
||||
help = "fzf mode",
|
||||
messages = {
|
||||
{ SwitchModeCustom = "fzxplr" },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Now let's try out the new `xplr`-`fzf` integration.
|
||||
|
||||
[![xplr-fzf.gif][25]][26]
|
||||
|
||||
---
|
||||
|
||||
Visit [Awesome Plugins][27] for more [integration][28] options.
|
||||
|
||||
[1]: #help
|
||||
[10]: #on_key
|
||||
[11]: #on_alphabet
|
||||
[12]: #on_number
|
||||
[13]: #on_special_character
|
||||
[14]: #default
|
||||
[15]: #key
|
||||
[16]: #action
|
||||
[17]: #messages
|
||||
[18]: message.md#message
|
||||
[19]: install.md
|
||||
[20]: post-install.md
|
||||
[21]: https://github.com/junegunn/fzf
|
||||
[22]: message.md#environment-variables
|
||||
[23]: message.md#input-pipe
|
||||
[24]: message.md#output-pipes
|
||||
[25]: https://s3.gifyu.com/images/xplr-fzf.gif
|
||||
[26]: https://gifyu.com/image/tW86
|
||||
[27]: awesome-plugins.md
|
||||
[28]: awesome-plugins.md#integration
|
||||
[31]: debug-key-bindings.md
|
||||
[32]: #on_alphanumeric
|
||||
[33]: #on_character
|
||||
[34]: #on_navigation
|
||||
@ -0,0 +1,93 @@
|
||||
# Debug Key Bindings
|
||||
|
||||
If you need help debugging or understanding key bindings DYI way, you can
|
||||
create a `test.lua` file with the following script, launch xplr with
|
||||
`xplr --extra-config text.lua`, press `#` and play around.
|
||||
|
||||
```lua
|
||||
xplr.config.modes.builtin.default.key_bindings.on_key["#"] = {
|
||||
help = "test",
|
||||
messages = {
|
||||
"PopMode",
|
||||
{ SwitchModeCustom = "test" },
|
||||
},
|
||||
}
|
||||
|
||||
xplr.config.modes.custom.test = {
|
||||
name = "test",
|
||||
key_bindings = {
|
||||
on_key = {
|
||||
["1"] = {
|
||||
messages = {
|
||||
{ LogInfo = "on_key called" },
|
||||
},
|
||||
},
|
||||
a = {
|
||||
messages = {
|
||||
{ LogInfo = "on_key called" },
|
||||
},
|
||||
},
|
||||
["`"] = {
|
||||
messages = {
|
||||
{ LogInfo = "on_key called" },
|
||||
},
|
||||
},
|
||||
f1 = {
|
||||
messages = {
|
||||
{ LogInfo = "on_key called" },
|
||||
},
|
||||
},
|
||||
tab = {
|
||||
messages = {
|
||||
{ LogInfo = "on_key called" },
|
||||
},
|
||||
},
|
||||
esc = {
|
||||
messages = {
|
||||
"PopMode",
|
||||
},
|
||||
},
|
||||
["ctrl-c"] = {
|
||||
messages = {
|
||||
"Terminate",
|
||||
},
|
||||
},
|
||||
},
|
||||
on_alphabet = {
|
||||
messages = {
|
||||
{ LogInfo = "on_alphabet called" },
|
||||
},
|
||||
},
|
||||
on_number = {
|
||||
messages = {
|
||||
{ LogInfo = "on_number called" },
|
||||
},
|
||||
},
|
||||
-- on_alphanumeric = {
|
||||
-- messages = {
|
||||
-- { LogInfo = "on_alphanumeric called" },
|
||||
-- },
|
||||
-- },
|
||||
on_special_character = {
|
||||
messages = {
|
||||
{ LogInfo = "on_special_character called" },
|
||||
},
|
||||
},
|
||||
-- on_character = {
|
||||
-- messages = {
|
||||
-- { LogInfo = "on_character called" },
|
||||
-- },
|
||||
-- },
|
||||
on_navigation = {
|
||||
messages = {
|
||||
{ LogInfo = "on_navigation called" },
|
||||
},
|
||||
},
|
||||
default = {
|
||||
messages = {
|
||||
{ LogInfo = "default called" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
@ -1 +1,16 @@
|
||||
# Key Bindings
|
||||
|
||||
Key bindings define how each keyboard input will be handled while in a specific
|
||||
[mode][4].
|
||||
|
||||
See the [Default key bindings][1] for example.
|
||||
|
||||
To configure or work with key bindings, visit [Configure Key Bindings][2].
|
||||
|
||||
In case you need help debugging key bindings or to understand the system DYI
|
||||
way, refer to the [Debug Key Bindings][3] guide.
|
||||
|
||||
[1]: default-key-bindings.md
|
||||
[2]: configure-key-bindings.md
|
||||
[3]: debug-key-bindings.md
|
||||
[4]: modes.md#mode
|
||||
|
||||
Loading…
Reference in New Issue