# ConsoleLib

> 一个用 C++ 编写的跨平台控制台操作库。

ConsoleLib 提供 Windows / Linux 下的控制台初始化、原始键盘输入、后台按键轮询、ANSI 真彩色输出、清屏和毫秒级休眠等功能，并同时产出静态库和动态库。

## 特性

- 控制台原始模式 / 原生模式初始化与恢复
- 后台键盘输入线程，轮询并记录按键
- 24 位 ANSI 真彩色输出
- 清屏
- 毫秒级跨平台休眠 `sleep_ms`
- 安全的 `quit` 退出
- 同时生成静态库和动态库

## 平台产物

| 平台 | 静态库 | 动态库 |
| --- | --- | --- |
| Linux | `libConsoleLib.a` | `libConsoleLib.so` |
| Windows | `ConsoleLib.lib` | `ConsoleLib.dll` |

## 环境要求

- CMake 3.10+（使用 `CMakePresets.json` 时建议 3.28+）
- 支持 C++17 的编译器（Clang / GCC / MSVC）
- 使用默认 preset 时需要 [Ninja](https://ninja-build.org/)

## 目录结构

```text
ConsoleLib/
├── CMakeLists.txt
├── CMakePresets.json
├── ConsoleLib.cpp
├── include/
│   └── ConsoleLib.h
├── example/
│   ├── CMakeLists.txt
│   ├── CMakePresets.json
│   ├── build.sh
│   ├── build.bat
│   ├── helloworld/
│   │   ├── CMakeLists.txt
│   │   └── main.cpp
│   └── keyinput/
│       ├── CMakeLists.txt
│       └── main.cpp
└── docs/
    └── image.png
```

## 快速开始

### 方式一：使用 CMake Presets（推荐）

```bash
# 项目根目录
./build.sh
```

等价命令：

```bash
cmake --preset Clang
cmake --build --preset Clang -j
```

构建产物默认在 `build/`。

Windows 下可运行：

```bat
build.bat
```

### 方式二：手动构建

```bash
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
```

### 单独构建示例

```bash
cd example
./build.sh
```

或：

```bash
cd example
cmake --preset Clang
cmake --build --preset Clang -j
./build/helloworld/helloworld
./build/keyinput/keyinput
```

## 示例

### HelloWorld

`example/helloworld/main.cpp`：

```cpp
#include <ConsoleLib.h>

using namespace ConsoleLib;

signed main() {
  initConsole();
  clearConsole();
  printToConsole("HelloWorld!\r\n");
  printToConsole("Red", 0xff0000);
  printToConsole("Green", 0x00ff00);
  printToConsole("Blue", 0x0000ff);
  quit(0);
}
```

输出效果见 `docs/image.png`。

### 按键输入（含方向键）

`example/keyinput/main.cpp` 展示了 `getConsoleKeyInput()` 与方向键、`Home`、`End`、`F1` ~ `F4` 以及普通可打印字符的检测：

```cpp
#include <ConsoleLib.h>

using namespace ConsoleLib;

signed main() {
  initConsole();
  clearConsole();
  printToConsole("Press arrow keys, q or ESC to quit.\r\n");

  while (true) {
    auto &keys = getConsoleKeyInput();

    if (keys[KEY_UP]) {
      printToConsole("UP\r\n");
    }
    if (keys[KEY_DOWN]) {
      printToConsole("DOWN\r\n");
    }
    if (keys[KEY_LEFT]) {
      printToConsole("LEFT\r\n");
    }
    if (keys[KEY_RIGHT]) {
      printToConsole("RIGHT\r\n");
    }

    if (keys[KEY_q] || keys[KEY_ESCAPE]) {
      break;
    }

    sleep_ms(16);
  }

  quit(0);
}
```

## 集成到你的项目

### 静态库

```cmake
add_subdirectory(ConsoleLib)
target_link_libraries(your_target PRIVATE ConsoleLib)
```

### 动态库

```cmake
add_subdirectory(ConsoleLib)
target_link_libraries(your_target PRIVATE ConsoleLib_shared)
```

`ConsoleLib` 目标已通过 `target_include_directories(... PUBLIC ...)` 暴露 `include/` 目录，因此直接包含即可：

```cpp
#include <ConsoleLib.h>
```

## API 参考

| 函数 | 说明 |
| --- | --- |
| `void initConsole()` | 初始化控制台并启动后台输入线程 |
| `void stopInputThread()` | 停止后台输入线程 |
| `void restoreConsoleMode()` | 恢复终端原始模式 / Windows 控制台模式 |
| `void RawPrint(std::string_view text)` | 直接输出文本，不做颜色处理 |
| `void printToConsole(std::string_view data)` | 打印文本 |
| `void printToConsole(std::string_view data, Color color)` | 打印指定颜色的文本 |
| `void clearConsole()` | 清屏并将光标移动到左上角 |
| `char getinput()` | 读取一个输入字符 |
| `std::array<bool, KEYCODE_COUNT> &getConsoleKeyInput()` | 返回并清空按键状态表，下标为 `Keycode` |
| `bool isKeyPressed(Keycode key)` | 查询某个按键当前是否被按下 |
| `void sleep_ms(unsigned int ms)` | 休眠指定毫秒数 |
| `void setInputFrequency(std::uint8_t frequency)` | 设置输入轮询频率（Hz） |
| `std::uint8_t getInputFrequency()` | 获取当前输入轮询频率 |
| `void quit(int exitCode)` | 停止线程、恢复终端并退出进程 |

`Color` 为 `uint32_t`，格式为 `0xRRGGBB`。

## 按键码

`Keycode` 为 SDL 风格的按键码：

- ASCII 字符直接使用其 ASCII 值，例如 `KEY_a`、`KEY_0`、`KEY_SPACE`
- 特殊键从 `128` 开始，例如 `KEY_UP`、`KEY_DOWN`、`KEY_LEFT`、`KEY_RIGHT`、`KEY_HOME`、`KEY_END`、`KEY_F1` ~ `KEY_F4`

| 常量 | 含义 |
| --- | --- |
| `ASCII_TABLE_SIZE` | ASCII 范围大小，固定为 `128` |
| `KEYCODE_COUNT` | 按键状态表大小 |
| `DEFAULT_CONSOLE_INPUT_FREQUENCY` | 默认输入轮询频率（50 Hz） |

`getConsoleKeyInput()` 返回长度为 `KEYCODE_COUNT` 的 `std::array<bool, KEYCODE_COUNT>`，下标即 `Keycode`；调用后内部按键记录会被清空。`isKeyPressed(Keycode)` 仅查询、不会清空记录。

## 说明

- `initConsole()` 会将终端切换到非回显的原始模式；程序结束前请调用 `quit()` 或 `restoreConsoleMode()`，否则终端状态可能无法恢复。
- `quit()` 已包含 `stopInputThread()` 和 `restoreConsoleMode()`。
- `getinput()` 仅返回单个 ASCII 字符；方向键、功能键等特殊键请使用 `getConsoleKeyInput()` 或 `isKeyPressed()`。