From 61d7f68f9b7f32073cb989416fa9c0d2465199f3 Mon Sep 17 00:00:00 2001 From: Dmytro Maluka Date: Sat, 5 Jul 2025 17:17:21 +0200 Subject: [PATCH 1/4] help: Document binding keys to lua functions This is still not properly documented (except for the example in tutorial.md), so document it. --- runtime/help/keybindings.md | 42 +++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md index 15163f72..3817131d 100644 --- a/runtime/help/keybindings.md +++ b/runtime/help/keybindings.md @@ -105,6 +105,48 @@ Now when you press `Ctrl-g`, `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 Lua functions + +You can also bind a key to a Lua function provided by a plugin, or by your own +`~/.config/micro/init.lua`. For example: + +```json +{ + "Alt-q": "lua:foo.bar" +} +``` + +where `foo` is the name of the plugin and `bar` is the name of the lua function +in it, e.g.: + +```lua +local micro = import("micro") + +function bar(bp) + micro.InfoBar():Message("Bar action triggered") + return true +end +``` + +See `> help plugins` for more informations on how to write lua functions. + +For `~/.config/micro/init.lua` the plugin name is `initlua` (so the keybinding +in this example would be `"Alt-q": "lua:initlua.bar"`). + +The currently active bufpane is passed to the lua function as the argument. If +the key is a mouse button, e.g. `MouseLeft` or `MouseWheelUp`, the mouse event +info is passed to the lua function as the second argument, of type +`*tcell.EventMouse`. See https://pkg.go.dev/github.com/micro-editor/tcell/v2#EventMouse +for the description of this type and its methods. + +The return value of the lua function defines whether the action has succeeded. +This is used when chaining lua functions with other actions. They can be chained +the same way as regular actions as described above, for example: + +``` +"Alt-q": "lua:initlua.bar|Quit" +``` + ## Binding raw escape sequences Only read this section if you are interested in binding keys that aren't on the From ffdd4b43ddcf84677a05e42c2de78dec11bdeda7 Mon Sep 17 00:00:00 2001 From: Dmytro Maluka Date: Sat, 5 Jul 2025 17:18:26 +0200 Subject: [PATCH 2/4] help: Update the list of mouse actions --- runtime/help/keybindings.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md index 3817131d..af6072a8 100644 --- a/runtime/help/keybindings.md +++ b/runtime/help/keybindings.md @@ -351,6 +351,8 @@ You can also bind some mouse actions (these must be bound to mouse buttons) ``` MousePress +MouseDrag +MouseRelease MouseMultiCursor ``` From c267c7c9aaf39753fa1fc1e2d9528f40b99e92e8 Mon Sep 17 00:00:00 2001 From: Dmytro Maluka Date: Sat, 5 Jul 2025 16:09:55 +0200 Subject: [PATCH 3/4] help: Update and correct documentation for onAction return value The documentation says that the returned value of onAction callbacks is used for determining whether the view should be relocated, which has nothing to do with reality, this returned value is used for a completely different thing. So update the docs accordingly. --- runtime/help/keybindings.md | 7 +++++++ runtime/help/plugins.md | 9 ++++----- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md index af6072a8..5ed58570 100644 --- a/runtime/help/keybindings.md +++ b/runtime/help/keybindings.md @@ -70,6 +70,13 @@ will execute `InsertTab`. To use `,`, `|` or `&` in an action (as an argument to a command, for example), escape it with `\` or wrap it in single or double quotes. +If the action has an `onAction` lua callback, for example `onAutocomplete` (see +`> help plugins`), then the action is only considered successful if the action +itself succeeded *and* the callback returned true. If there are multiple +`onAction` callbacks for this action, registered by multiple plugins, then the +action is only considered successful if the action itself succeeded and all the +callbacks returned true. + ## Binding commands You can also bind a key to execute a command in command mode (see diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md index 0411fcff..4a8b8a68 100644 --- a/runtime/help/plugins.md +++ b/runtime/help/plugins.md @@ -71,8 +71,10 @@ that micro defines: * `onAction(bufpane)`: runs when `Action` is triggered by the user, where `Action` is a bindable action (see `> help keybindings`). A bufpane - is passed as input and the function should return a boolean defining - whether the view should be relocated after this action is performed. + is passed as input. The function should return a boolean defining + whether the action was successful, which is used when the action is + chained with other actions (see `> help keybindings`) to determine whether + the next actions in the chain should be executed or not. * `preAction(bufpane)`: runs immediately before `Action` is triggered by the user. Returns a boolean which defines whether the action should @@ -101,9 +103,6 @@ within. This is almost always the current bufpane. All available actions are listed in the keybindings section of the help. -These functions should also return a boolean specifying whether the bufpane -should be relocated to the cursor or not after the action is complete. - ## Accessing micro functions Some of micro's internal information is exposed in the form of packages, which From 0694cd2c1b5b910b61f372e84d305a4b3d9d8665 Mon Sep 17 00:00:00 2001 From: Dmytro Maluka Date: Sat, 5 Jul 2025 17:16:15 +0200 Subject: [PATCH 4/4] help: Document passing *tcell.EventMouse to mouse action callbacks --- runtime/help/plugins.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md index 4a8b8a68..4de98ede 100644 --- a/runtime/help/plugins.md +++ b/runtime/help/plugins.md @@ -76,10 +76,19 @@ that micro defines: chained with other actions (see `> help keybindings`) to determine whether the next actions in the chain should be executed or not. + If the action is a mouse action, e.g. `MousePress`, the mouse event info + is passed to the callback as an extra argument of type `*tcell.EventMouse`. + See https://pkg.go.dev/github.com/micro-editor/tcell/v2#EventMouse for the + description of this type and its methods. + * `preAction(bufpane)`: runs immediately before `Action` is triggered by the user. Returns a boolean which defines whether the action should be canceled. + Similarly to `onAction`, if the action is a mouse action, the mouse event + info is passed to the callback as an extra argument of type + `*tcell.EventMouse`. + * `onRune(bufpane, rune)`: runs when the composed rune has been inserted * `preRune(bufpane, rune)`: runs before the composed rune will be inserted