Rust Wayland键盘处理库wayland-kbd的使用指南

概述

wayland-kbd是一个用于在Linux下通过Wayland协议处理键盘输入的Rust库。它提供了高效、安全的键盘事件处理机制，适合需要精细控制键盘输入的Wayland客户端应用。

主要特性

• 支持Wayland键盘协议
• 提供按键事件回调机制
• 支持键盘布局和键码处理
• 线程安全设计
• 与Rust生态系统良好集成

安装方法

在Cargo.toml中添加依赖：

[dependencies]
wayland-kbd = "0.3"  # 请使用最新版本
wayland-client = "0.30"  # 需要配合wayland-client使用

基本使用方法

1. 初始化键盘处理

use wayland_client::{Display, GlobalManager};
use wayland_kbd::{KeyboardHandler, KeyboardManager};

fn main() {
    // 连接到Wayland显示服务器
    let display = Display::connect_to_env().unwrap();
    let mut event_queue = display.create_event_queue();
    let attached_display = display.attach(event_queue.token());
    
    // 初始化全局对象管理器
    let globals = GlobalManager::new(&attached_display);
    
    // 初始化键盘管理器
    let keyboard_manager = KeyboardManager::new(&globals).unwrap();
    
    // 设置键盘事件处理器
    keyboard_manager.set_handler(MyKeyboardHandler);
    
    // 进入事件循环
    loop {
        event_queue.dispatch(&mut (), |_, _, _| {}).unwrap();
    }
}

struct MyKeyboardHandler;

impl KeyboardHandler for MyKeyboardHandler {
    fn on_key(&mut self, keycode: u32, state: wayland_kbd::KeyState) {
        println!("Key event: code={}, state={:?}", keycode, state);
    }
    
    fn on_modifiers(&mut self, modifiers: wayland_kbd::Modifiers) {
        println!("Modifiers changed: {:?}", modifiers);
    }
}

2. 处理按键事件

impl KeyboardHandler for MyKeyboardHandler {
    fn on_key(&mut self, keycode: u32, state: wayland_kbd::KeyState) {
        match state {
            wayland_kbd::KeyState::Pressed => {
                println!("Key pressed: {}", keycode);
                // 转换为字符(考虑键盘布局)
                if let Some(ch) = wayland_kbd::keycode_to_char(keycode, &modifiers) {
                    println!("Character: {}", ch);
                }
            }
            wayland_kbd::KeyState::Released => {
                println!("Key released: {}", keycode);
            }
        }
    }
}

3. 处理修饰键状态

impl KeyboardHandler for MyKeyboardHandler {
    fn on_modifiers(&mut self, modifiers: wayland_kbd::Modifiers) {
        println!("Current modifiers:");
        if modifiers.ctrl { println!("  CTRL pressed"); }
        if modifiers.alt { println!("  ALT pressed"); }
        if modifiers.shift { println!("  SHIFT pressed"); }
        if modifiers.caps_lock { println!("  CAPS LOCK active"); }
        if modifiers.num_lock { println!("  NUM LOCK active"); }
    }
}

高级用法

1. 键盘抓取(获取全局键盘事件)

use wayland_kbd::KeyboardGrab;

let grab = keyboard_manager.grab_keyboard().unwrap();
grab.set_handler(MyGrabHandler);

struct MyGrabHandler;

impl KeyboardHandler for MyGrabHandler {
    fn on_key(&mut self, keycode: u32, state: wayland_kbd::KeyState) {
        // 处理全局键盘事件
    }
}

2. 自定义键盘映射

use wayland_kbd::Keymap;

// 加载自定义键盘映射
let keymap = Keymap::from_file("/path/to/keymap.xkb").unwrap();
keyboard_manager.set_keymap(keymap);

错误处理

match keyboard_manager.grab_keyboard() {
    Ok(grab) => {
        // 处理键盘抓取
    }
    Err(err) => {
        eprintln!("Failed to grab keyboard: {}", err);
    }
}

注意事项

1. Wayland协议限制了某些键盘操作的权限，特别是在安全敏感的上下文中
2. 键盘抓取可能需要特殊权限或用户确认
3. 不同Wayland合成器的行为可能略有不同
4. 考虑处理键盘布局变化事件

完整示例

use wayland_client::{Display, GlobalManager};
use wayland_kbd::{KeyboardHandler, KeyboardManager, Modifiers};

fn main() {
    // 初始化Wayland连接
    let display = Display::connect_to_env().unwrap();
    let mut event_queue = display.create_event_queue();
    let attached_display = display.attach(event_queue.token());
    
    let globals = GlobalManager::new(&attached_display);
    event_queue.sync_roundtrip(&mut (), |_, _, _| {}).unwrap();
    
    // 初始化键盘管理器
    let keyboard_manager = KeyboardManager::new(&globals).unwrap();
    
    // 设置处理器
    keyboard_manager.set_handler(MyKeyboardHandler);
    
    println!("Waiting for keyboard events...");
    
    // 事件循环
    loop {
        event_queue.dispatch(&mut (), |_, _, _| {}).unwrap();
    }
}

struct MyKeyboardHandler {
    modifiers: Modifiers,
}

impl KeyboardHandler for MyKeyboardHandler {
    fn on_key(&mut self, keycode: u32, state: wayland_kbd::KeyState) {
        match state {
            wayland_kbd::KeyState::Pressed => {
                if let Some(ch) = wayland_kbd::keycode_to_char(keycode, &self.modifiers) {
                    println!("Typed: {}", ch);
                } else {
                    println!("Special key pressed: {}", keycode);
                }
            }
            wayland_kbd::KeyState::Released => {
                println!("Key released: {}", keycode);
            }
        }
    }
    
    fn on_modifiers(&mut self, modifiers: wayland_kbd::Modifiers) {
        self.modifiers = modifiers;
        println!("Modifiers updated");
    }
}

这个库为Rust开发者提供了在Wayland环境下处理键盘输入的高效方式，适合需要精细控制键盘交互的应用程序开发。