Add KeyEventResult enum and support passthrough (filter) mode

src/addonloader/base.lua

@@ -120,10 +120,23 @@ local oldsetCurrentInputMethod=fcitx.setCurrentInputMethod
 local function setCurrentInputMethod(name,local_im)
     if(local_im == nil) then
         local_im = false
-    end    
+    end
     oldsetCurrentInputMethod(name,local_im)
 end
 
 fcitx.setCurrentInputMethod = setCurrentInputMethod
 
+--- Result of key event handler. It represents the action to be taken
+-- after a fcitx.EventType.KeyEvent handler is executed.
+-- @table KeyEventResult
+-- @field NotHandled Let Fcitx5 continue its normal processing. Equivalent to returning `false`.
+-- @field Handled Fcitx5 handles the event and consumes it. Equivalent to returning `true`.
+-- @field Passthrough Fcitx5 will not process this event and will let it pass through to the application.
+local KeyEventResult = {
+    NotHandled = 0,
+    Handled = 1,
+    Passthrough = 2,
+}
+fcitx.KeyEventResult = KeyEventResult
+
 return fcitx

src/addonloader/luaaddonstate.cpp

@@ -262,9 +262,26 @@ std::tuple<int> LuaAddonState::watchEventImpl(int eventType,
                 return 3;
             },
             [](std::unique_ptr<LuaState> &state, KeyEvent &event) {
-                auto b = lua_toboolean(state, -1);
-                if (b) {
-                    event.filterAndAccept();
+                if (lua_isinteger(state, -1)) {
+                    auto result = lua_tointeger(state, -1);
+                    switch (static_cast<KeyEventResult>(result)) {
+                    case KeyEventResult::NotHandled:
+                        break;
+                    case KeyEventResult::Handled:
+                        event.filterAndAccept();
+                        break;
+                    case KeyEventResult::Passthrough:
+                        event.filter();
+                        break;
+                    default:
+                        FCITX_LUA_ERROR()
+                            << "invalid KeyEventResult: " << result;
+                    }
+                } else {
+                    auto b = lua_toboolean(state, -1);
+                    if (b) {
+                        event.filterAndAccept();
+                    }
                 }
             });
         break;

src/addonloader/luaaddonstate.h

@@ -95,6 +95,12 @@ class Converter {
     ScopedConnection connection_;
 };
 
+enum class KeyEventResult {
+    NotHandled,
+    Handled,
+    Passthrough,
+};
+
 class LuaAddonState {
 public:
     LuaAddonState(Library *luaLibrary, const std::string &name,

src/addonloader/luafunc.h

@@ -23,6 +23,7 @@ FOREACH_LUA_FUNCTION(lua_pushstring)
 FOREACH_LUA_FUNCTION(lua_pushlstring)
 FOREACH_LUA_FUNCTION(lua_type)
 FOREACH_LUA_FUNCTION(lua_gettable)
+FOREACH_LUA_FUNCTION(lua_isinteger)
 FOREACH_LUA_FUNCTION(lua_tointegerx)
 FOREACH_LUA_FUNCTION(lua_pushnil)
 FOREACH_LUA_FUNCTION(lua_next)

test/lua/testlua/test.lua

@@ -56,3 +56,27 @@ end
 function testUtf8Conversion(str)
     return fcitx.UTF16ToUTF8(str)
 end
+
+function getLastCommit()
+    return fcitx.lastCommit()
+end
+
+fcitx.watchEvent(fcitx.EventType.KeyEvent, "testKeyEventResultHandler")
+
+function testKeyEventResultHandler(sym, state, release)
+    local key = string.char(sym)
+    if key == "x" then
+        return fcitx.KeyEventResult.NotHandled
+    elseif key == "y" then
+        return fcitx.KeyEventResult.Handled
+    elseif key == "z" then
+        return fcitx.KeyEventResult.Passthrough
+    elseif key == "e" then
+        return false
+    elseif key == "f" then
+        return
+    elseif key == "g" then
+        return true
+    end
+    return fcitx.KeyEventResult.NotHandled
+end

test/testlua.cpp

@@ -29,6 +29,42 @@
 
 using namespace fcitx;
 
+void testKeyEventResult(AddonInstance *testfrontend, AddonInstance *luaaddon,
+                        ICUUID uuid, InputContext *ic) {
+    auto sendKey = [&](const std::string &key) {
+        return testfrontend->call<ITestFrontend::sendKeyEvent>(uuid, Key(key),
+                                                               false);
+    };
+    auto getLastCommit = [&]() {
+        return luaaddon
+            ->call<ILuaAddon::invokeLuaFunction>(ic, "getLastCommit",
+                                                 RawConfig{})
+            .value();
+    };
+
+    // Test KeyEventResult enum values
+
+    FCITX_ASSERT(sendKey("x")) << "NotHandled: should accept the event";
+    FCITX_ASSERT(getLastCommit() == "x") << "NotHandled: should commit 'x'";
+
+    FCITX_ASSERT(sendKey("y")) << "Handled: should accept the event";
+    FCITX_ASSERT(getLastCommit() == "x") << "Handled: should still be 'x'";
+
+    FCITX_ASSERT(!sendKey("z")) << "Passthrough: should not accept the event";
+    FCITX_ASSERT(getLastCommit() == "x") << "Passthrough: should still be 'x'";
+
+    // Legacy boolean/nil return values
+
+    FCITX_ASSERT(sendKey("e")) << "false: should accept the event";
+    FCITX_ASSERT(getLastCommit() == "e") << "false: should commit 'e'";
+
+    FCITX_ASSERT(sendKey("f")) << "nil: should accept the event";
+    FCITX_ASSERT(getLastCommit() == "f") << "nil: should commit 'f'";
+
+    FCITX_ASSERT(sendKey("g")) << "true: should accept the event";
+    FCITX_ASSERT(getLastCommit() == "f") << "true: should still be 'f'";
+}
+
 void scheduleEvent(EventDispatcher *dispatcher, Instance *instance) {
     dispatcher->schedule([instance]() {
         auto *luaaddonloader =
@@ -126,6 +162,8 @@ void scheduleEvent(EventDispatcher *dispatcher, Instance *instance) {
             ic, "testUtf8Conversion", strConfig);
         FCITX_ASSERT(ret.value() == testString) << ret;
 
+        testKeyEventResult(testfrontend, luaaddon, uuid, ic);
+
         dispatcher->detach();
         instance->exit();
     });