# sxzxs/explore_select_items architecture

> Architecture diagram of the GitHub repository sxzxs/explore_select_items, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sxzxs/explore_select_items
- Repository: https://github.com/sxzxs/explore_select_items

## Overview

##### Project type and purpose
- This is a Windows Explorer extension (a system‐level utility) written in AutoHotkey (AHK) that provides pinyin (and wubi) based filtering/search of Explorer items.
- The main deliverable is an AHK script (`资源管理器拼音搜索.ahk`) and a compiled EXE (`资源管理器拼音搜索.exe`) that hooks into Explorer, captures keystrokes, queries the file/folder list, applies pinyin matching, and renders a custom UI overlay.

##### File structure
Top-level:
- README.md / README.html – project description and usage
- `资源管理器拼音搜索.ahk` & `.exe` – the main entrypoint (script + compiled binary)
- `back/资源管理器拼音搜索.ahk` – backup or alternate version
- `config/settings.json` – user‐tweakable settings (e.g., hotkeys, filter modes)
- `lib/` – a collection of AHK libraries and DLLs:
– `IbPinyin.ahk`/`IbPinyin_v2.ahk` – pinyin conversion & matching
– `wubi.ahk` – 86 五笔 input support
– `json.ahk` – JSON read/write for config
– `Gdip_All.ahk` – GDI+ UI rendering
– `log.ahk`, `NonNull.ahk` – utility helpers
– `dll_32` / `dll_64` – native binaries for GDI+ or other hooks
- `test.ahk` – standalone test harness for development

##### README for additional insights
- Explains features: supports initial letters, full pinyin, double‐拼, wubi.
- Describes usage: right-click admin to run EXE or AHK; then when in Explorer, type and filter; Tab/Shift+Tab for navigation; Enter to enter directory.

##### Main components & their interactions
a. Windows Explorer (Host)
- Explorer window where user invokes the extension (via right-click or hotkey).
b. Extension Process (AHK Script / EXE)
- Registers keyboard hooks or shell hooks to monitor keystrokes in Explorer.
- On activation, enumerates the current Explorer item list.
- Loads `config/settings.json` via `json.ahk`.
- Routes raw keystrokes to filter logic.
c. Matching Engine
- Uses `IbPinyin(.ahk)`, `IbPinyin_v2.ahk` for pinyin decomposition, `wubi.ahk` for wubi schemes.
- Applies filter rules (first‐letter, full pinyin, double pinyin).
d. UI Renderer
e. Utilities & Helpers
- `log.ahk` for debug logging
- `NonNull.ahk` for safe variable handling
f. Test Harness
- `test.ahk` for offline testing of matching logic

Data flows:
Explorer → (hook) → AHK Extension → read settings → enumerate items → matching engine → UI renderer → user
AHK Extension ↔ Libraries (pinyin, JSON, GDI+)
AHK Extension → config/settings.json

##### Architectural patterns & design principles
- Modular scripting: core logic separated from libraries and config
- Single‐process, event‐driven model—AHK listens for key events, reacts, and renders
- External dependency isolation: JSON and GDI+ functionality are factored into reusable libs

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External System"
        Explorer["Windows Explorer"]:::external
    end

    subgraph "AHK Extension (入口)"
        ExtScript["AHK Extension\n(资源管理器拼音搜索.ahk)"]:::core
        ExtExe["Compiled Extension\n(资源管理器拼音搜索.exe)"]:::core
        Backup["Backup Script\n(back/资源管理器拼音搜索.ahk)"]:::core
    end

    subgraph "Libraries & Helpers"
        subgraph "Matching Engine"
            Pinyin1["IbPinyin.ahk"]:::lib
            Pinyin2["IbPinyin_v2.ahk"]:::lib
            Wubi["wubi.ahk"]:::lib
        end
        subgraph "UI Renderer"
            Gdip["Gdip_All.ahk"]:::lib
            DLL32["dll_32/"]:::lib
            DLL64["dll_64/"]:::lib
        end
        JSON["json.ahk"]:::lib
        Log["log.ahk"]:::lib
        NonNull["NonNull.ahk"]:::lib
    end

    Config["Config (settings.json)"]:::config
    Assets["UI Assets/Icons"]:::assets
    Test["Test Harness\n(test.ahk)"]:::test

    Explorer -->|KeyEvent| ExtScript
    Explorer -->|KeyEvent| ExtExe
    ExtScript -->|"load settings\n(JSON settings)"| Config
    ExtScript -->|"enumerate items\n(FileList[])"| Explorer
    ExtScript -->|"use"| Pinyin1
    ExtScript -->|"use"| Pinyin2
    ExtScript -->|"use"| Wubi
    ExtScript -->|"use"| JSON
    ExtScript -->|"use"| Log
    ExtScript -->|"use"| NonNull
    ExtScript -->|"render overlay"| Gdip
    ExtScript -->|"render overlay"| DLL32
    ExtScript -->|"render overlay"| DLL64
    ExtScript -->|"load icons"| Assets
    ExtScript -->|"draw overlay"| Explorer

    Test -->|"invoke matching"| Pinyin1
    Test -->|"invoke matching"| Pinyin2
    Test -->|"invoke matching"| Wubi

    click ExtScript "https://github.com/sxzxs/explore_select_items/blob/master/资源管理器拼音搜索.ahk"
    click ExtExe "https://github.com/sxzxs/explore_select_items/blob/master/资源管理器拼音搜索.exe"
    click Backup "https://github.com/sxzxs/explore_select_items/blob/master/back/资源管理器拼音搜索.ahk"
    click Config "https://github.com/sxzxs/explore_select_items/blob/master/config/settings.json"
    click Pinyin1 "https://github.com/sxzxs/explore_select_items/blob/master/lib/IbPinyin.ahk"
    click Pinyin2 "https://github.com/sxzxs/explore_select_items/blob/master/lib/IbPinyin_v2.ahk"
    click Wubi "https://github.com/sxzxs/explore_select_items/blob/master/lib/wubi.ahk"
    click Gdip "https://github.com/sxzxs/explore_select_items/blob/master/lib/Gdip_All.ahk"
    click DLL32 "https://github.com/sxzxs/explore_select_items/tree/master/lib/dll_32/"
    click DLL64 "https://github.com/sxzxs/explore_select_items/tree/master/lib/dll_64/"
    click Assets "https://github.com/sxzxs/explore_select_items/tree/master/picture/"
    click JSON "https://github.com/sxzxs/explore_select_items/blob/master/lib/json.ahk"
    click Log "https://github.com/sxzxs/explore_select_items/blob/master/lib/log.ahk"
    click NonNull "https://github.com/sxzxs/explore_select_items/blob/master/lib/NonNull.ahk"
    click Test "https://github.com/sxzxs/explore_select_items/blob/master/test.ahk"

    classDef external fill:#add8e6,stroke:#000,stroke-width:1px
    classDef core fill:#98fb98,stroke:#000,stroke-width:1px
    classDef lib fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef config fill:#ffa500,stroke:#000,stroke-width:1px
    classDef assets fill:#ffffe0,stroke:#000,stroke-width:1px
    classDef test fill:#dda0dd,stroke:#000,stroke-width:1px
```
