im_switch/lib.rs
1//! A cross-platform input method switcher.
2//!
3//! **im-switch** provides a unified API to query, switch, and list input methods
4//! across Linux, Windows, and macOS.
5//!
6//! # Platform support
7//!
8//! | Platform | Backend |
9//! |----------|---------|
10//! | Linux | fcitx5 (D-Bus), ibus (CLI) — auto-detected at runtime |
11//! | Windows | Win32 API (keyboard layout + IME on/off control) |
12//! | macOS | Carbon TIS API |
13//!
14//! # Quick start
15//!
16//! ```rust,no_run
17//! use im_switch::{get_input_method, set_input_method, list_input_methods};
18//!
19//! // Get the current input method
20//! let im = get_input_method().unwrap();
21//! println!("Current IM: {im}");
22//!
23//! // List available input methods
24//! let methods = list_input_methods().unwrap();
25//! for m in &methods {
26//! println!(" {m}");
27//! }
28//!
29//! // Restore a saved input method
30//! set_input_method(&im).unwrap();
31//! ```
32
33// --- Module declarations ---
34
35mod error;
36
37#[cfg(target_os = "linux")]
38mod linux;
39
40#[cfg(target_os = "windows")]
41mod windows;
42
43#[cfg(target_os = "macos")]
44mod macos;
45
46#[cfg(not(any(target_os = "linux", target_os = "windows", target_os = "macos")))]
47mod unsupported;
48
49// --- Re-exports and platform alias ---
50
51pub use error::ImSwitchError;
52
53#[cfg(target_os = "linux")]
54use linux as platform;
55
56#[cfg(target_os = "windows")]
57use windows as platform;
58
59#[cfg(target_os = "macos")]
60use macos as platform;
61
62#[cfg(not(any(target_os = "linux", target_os = "windows", target_os = "macos")))]
63use unsupported as platform;
64
65// --- Cross-platform API ---
66
67/// Returns the current input method identifier.
68///
69/// The returned value is platform-dependent:
70/// - Windows: Keyboard layout ID (KLID), e.g., `"00000409"`
71/// - macOS: Input source identifier, e.g., `"com.apple.keylayout.ABC"`
72/// - Linux: Input method name (IM framework-dependent)
73pub fn get_input_method() -> Result<String, ImSwitchError> {
74 platform::get_input_method()
75}
76
77/// Sets the input method to the specified identifier.
78///
79/// The identifier format is platform-dependent (see [`get_input_method`]).
80pub fn set_input_method(im: &str) -> Result<(), ImSwitchError> {
81 platform::set_input_method(im)
82}
83
84/// Returns a list of available input method identifiers.
85pub fn list_input_methods() -> Result<Vec<String>, ImSwitchError> {
86 platform::list_input_methods()
87}
88
89// --- Windows-only API ---
90
91/// Returns the current IME on/off state (Windows only).
92#[cfg(target_os = "windows")]
93pub fn get_ime_state() -> Result<bool, ImSwitchError> {
94 platform::get_ime_state()
95}
96
97/// Sets the IME on/off state (Windows only).
98#[cfg(target_os = "windows")]
99pub fn set_ime_state(enabled: bool) -> Result<(), ImSwitchError> {
100 platform::set_ime_state(enabled)
101}
102
103/// Toggles the IME on/off state and returns the new state (Windows only).
104#[cfg(target_os = "windows")]
105pub fn toggle_ime_state() -> Result<bool, ImSwitchError> {
106 let current = get_ime_state()?;
107 let new_state = !current;
108 set_ime_state(new_state)?;
109 Ok(new_state)
110}