add forwardKey function

[buzztaiki]

This PR adds a forwardKey function to the Lua API, allowing Lua scripts to explicitly send key events to the application.

By exposing forwardKey to Lua, I can now implement a per-application "passthrough" mode. This serves as a scriptable alternative to the old useXIM: false behavior for Wayland users who need fine-grained control over key event propagation.

In my specific use case using Emacs with DDSKK, I need a way to let the application handle all key events directly to avoid conflicts with Fcitx5's internal logic and shortcuts.

Example usage

local fcitx = require("fcitx")

local target_programs = {
   ["emacs"] = true
}

-- Restore keysym normalized by Key::normalize
function unnormalize_keysym(keysym, states)
   local chr_A = string.byte("A")
   local chr_Z = string.byte("Z")
   if chr_A <= keysym and keysym <= chr_Z
      and states & fcitx.KeyState.SimpleMask ~= 0
      and states & fcitx.KeyState.Shift == 0
   then
      return keysym + 32
   end
   return keysym
end

function handler(keysym, states, release)
   local program = fcitx.currentProgram()
   local keysym = unnormalize_keysym(keysym, states)
   if target_programs[program] then
      fcitx.forwardKey(keysym, states, release)
      return true
   end
   return false
end

fcitx.watchEvent(fcitx.EventType.KeyEvent, "handler")

[wengxt]

If your request is to bypass all key in fcitx, you'd better adjust the return value handling here

fcitx5-lua/src/addonloader/luaaddonstate.cpp

Line 267 in a6f0054

event.filterAndAccept();

right now it's a boolean to call filterAndAccept, for your use case you just need filter().

[buzztaiki]

Thank you! I tested filter() and confirmed that it successfully passes through key events in specific applications.

I'm going to submit a new PR that extends the return value handling by introducing a new enum (e.g. fcitx.KeyEventResult.Passthrough) to support this behavior.

[buzztaiki]

I've created new PR #30. Thank you for your advice!