vim-im-switch/README_en.md

# Vim Input Method Switch Plugin

[![Version](https://img.shields.io/badge/version-2.0.3-blue.svg)](./CHANGELOG.md)

English | [中文](./README.md)

An input method auto-switching plugin designed for Vim and Obsidian's Vim mode, including:
- **Obsidian Plugin**: For Obsidian editor's Vim mode
- **Vim Plugin**: For native Vim/NeoVim editors

## Features

- **Automatic switching**: Automatically switches input methods when transitioning between Vim's Normal and Insert modes
- **Smart memory**: Remembers the input method state when exiting Insert mode and restores it on next entry
- **Seamless experience**: Won't trigger input method changes during normal text input in Insert mode

## Core Features

### 1. Mode Switch Automation
- **Enter Normal mode** (press ESC or other commands) → Auto switch to English input method
- **Enter Insert mode** (press i, a, o, etc.) → Auto restore previous input method state

### 2. Input Method State Memory
- Automatically detects and saves current input method (Chinese/English) when exiting Insert mode
- Automatically restores to last saved input method state when entering Insert mode
- Supports mixed Chinese/English input scenarios

### 3. Smart Detection Mechanism
The plugin uses multiple detection mechanisms for reliability:
- **Keyboard event listening** (primary): Uses capture mode to listen for ESC and Insert keys
- **CodeMirror events** (auxiliary): Monitors vim-mode-change events
- **Polling** (fallback): 100ms polling to detect mode changes

## Quick Start

### Requirements

#### macOS
```bash
brew install fcitx-remote-for-osx
```

#### Linux
```bash
# Ubuntu/Debian
sudo apt-get install fcitx

# Fedora
sudo dnf install fcitx

# Arch Linux
sudo pacman -S fcitx
```

#### Windows
Download [fcitx-remote.exe](https://github.com/yuanotes/obsidian-vim-im-switch-plugin/releases/download/1.0.3/fcitx-remote.exe) and place it in your system PATH

### Installation

#### Obsidian Plugin Installation

1. Download plugin to Obsidian plugins directory:
   ```bash
   cd /path/to/your/vault/.obsidian/plugins/
   git clone https://github.com/yourusername/vim-im-switch.git
   ```

2. Enable plugin in Obsidian:
   - Open Settings → Community Plugins
   - Find "Vim Input Method Switch" and enable it

3. Configure input methods (optional):
   - Set English input method (default: `com.apple.keylayout.ABC`)
   - Set Chinese input method (default: auto-detect)

#### Vim Plugin Installation

1. Copy plugin file to Vim config directory:
   ```bash
   mkdir -p ~/.vim/plugin
   cp fcitx-osx.vim ~/.vim/plugin/
   ```

2. Restart Vim, the plugin will load automatically

3. Configure input methods (optional):
   Add to `.vimrc`:
   ```vim
   " English input method ID (default)
   let g:fcitx_english_im = 'com.apple.keylayout.ABC'
   
   " Chinese input method ID (optional, auto-detect by default)
   " let g:fcitx_chinese_im = 'com.tencent.inputmethod.wetype.pinyin'
   ```

#### One-Click Deploy (Recommended)

Deploy both plugins with a single command:
```bash
./deploy.sh
```

Note: v2.0.2 fixes a terminal-specific title/flash issue when using terminal Vim (see CHANGELOG for details).

## Usage

### Basic Usage Scenarios

**Chinese Input**:
```
Press i → Enter Insert mode → IM switches to Chinese (if last time was Chinese)
Type Chinese content
Press ESC → Exit to Normal mode → IM switches to English
```

**English Input**:
```
Press i → Enter Insert mode → IM stays English (if last time was English)
Type English content
Press ESC → Exit to Normal mode → IM stays English
```

**Mixed Input**:
```
Press i → Auto restore last IM
Type Chinese, then manually switch to English
Press ESC → Save current IM state (English)
Press i → Auto restore English IM
```

### Supported Vim Commands

- **Enter Insert mode**: `i`, `I`, `a`, `A`, `o`, `O`, `s`, `S`, `c`, `C`
- **Exit Insert mode**: `ESC`, and other commands that trigger Normal mode

## How It Works

```mermaid
graph TD
    A[Normal Mode<br/>English IM] -->|Press i/a/o etc| B[Detect Mode Change]
    B --> C[Restore Last Saved<br/>IM State]
    C --> D[Insert Mode<br/>Restored IM:<br/>Chinese/English]
    D -->|Press ESC| E[Save Current IM<br/>State CN/EN]
    E --> F[Switch to English IM]
    F --> A
    
    style A fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    style D fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style E fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style F fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
```

### Technical Details

**Input Method Detection**
- Uses `fcitx-remote -n` to get current input method name
- Compares with configured Chinese/English input method names

**Event Handling**
- **Keyboard events**: Uses `capture` mode to intercept keys early
- **Debouncing**: Ignores repeated events within 100ms
- **Async processing**: All input method switches are asynchronous and non-blocking

**State Management**
- `currentVimMode`: Current Vim mode (normal/insert/visual)
- `lastInsertModeIMStatus`: Last input method state in Insert mode
- `imStatus`: Current input method state (Activate=Chinese, Deactivate=English)

## Troubleshooting

### Issue: Plugin not working
1. Check if fcitx-remote is properly installed:
   ```bash
   which fcitx-remote
   fcitx-remote -n
   ```

2. Check plugin logs (developer console):
   - Press `Cmd+Option+I` (macOS) or `Ctrl+Shift+I` (Windows/Linux) to open developer console
   - Look for logs starting with `[VimIMSwitch]`

3. Verify input method names:
   ```bash
   # After switching to Chinese input method
   fcitx-remote -n
   # Output should match the Chinese IM name in plugin settings
   ```

### Issue: Incorrect input method switching
1. Confirm input method names in settings are correct
2. Check logs in developer console after manually switching IM
3. Check for conflicts with other plugins

### Issue: ESC key requires multiple presses
- This issue has been fixed in the latest version
- If it still occurs, please update to the latest version

## Development

### Build
```bash
npm install
npm run build
```

### Deploy
Deploy both Obsidian and Vim plugins with one command:
```bash
./deploy.sh
```

### Debug

#### Obsidian Plugin
The plugin outputs key logs in the console:
- `Loading plugin...` - Plugin loaded
- `ESC → English` - ESC switches to English
- `→ Chinese` - Switches to Chinese
- `Error...` - Error messages

#### Vim Plugin
View messages in Vim:
```vim
:messages
```
- `→ Chinese` - Switch to Chinese
- `Error...` - Error messages

### Changelog

See [CHANGELOG_en.md](./CHANGELOG_en.md) for detailed version history.

## License

MIT License

## Links

- [Changelog](./CHANGELOG_en.md)
- [中文文档](./README.md)
- [fcitx-remote-for-osx](https://github.com/xcodebuild/fcitx-remote-for-osx)