qlipboard

Windows向けの FIFO クリップボード常駐アプリです。コピーしたテキストを時系列で蓄積し、ホットキーで最も古い履歴から順に貼り付けできます。

本書は、Win32 API を用いた本アプリの正式仕様です。実装は本仕様を満たすことを目標とします。

1. 目的

• Windows上で、コピーされたテキストを時系列順に蓄積する。
• 利用者が任意のタイミングで、最も古い履歴から順に貼り付けできるようにする。
• 常駐型で軽量に動作し、通常業務の入力フローを阻害しない。

2. 用語

• FIFO: First-In, First-Out。先に入ったデータから先に取り出す方式。
• 履歴キュー: 本アプリ内部で保持するFIFOキュー。
• 先頭要素: 履歴キューで最も古いデータ。

3. 対象環境

• OS: Windows 10/11
• 言語: C++17
• API: Win32 API（user32.dll）

4. スコープ

4.1 対象（In Scope）

• テキスト形式（CF_UNICODETEXT）のクリップボード監視
• FIFO履歴の追加・取り出し
• グローバルホットキーによる貼り付け実行
• ホットキーによる常駐アプリ終了

4.2 非対象（Out of Scope）

• 画像、HTML、ファイル一覧など非テキスト形式の履歴保持
• 履歴の永続化（再起動後の復元）
• GUIウィンドウによる履歴一覧表示

5. 機能要件

FR-01 常駐動作

• アプリは起動後、メッセージループで常駐する。
• 通常の表示ウィンドウは持たない（隠しウィンドウまたはメッセージ専用ウィンドウ）。

FR-02 クリップボード監視

• システムのクリップボード更新をイベント駆動で検知する。
• 取得対象はCF_UNICODETEXTのみとする。

FR-03 履歴キュー追加

• 監視で取得したテキストを履歴キュー末尾へ追加する。
• 空文字は追加しない。
• 最大件数をMAX_HISTORY（初期値50）とする。
• 追加後に件数超過した場合は、先頭要素（最古）を破棄する。

FR-04 FIFO貼り付け

• ホットキー入力で履歴キュー先頭要素を1件取り出す。
• 取り出した内容をクリップボードへ設定し、貼り付けキー操作を送信する。
• キューが空の場合は貼り付け処理を行わず、警告音などで通知する。

FR-05 自己更新イベントの無視

• FR-04でアプリ自身がクリップボードを書き換えた際の更新イベントは、再登録を防ぐため1回分無視する。

FR-06 ホットキー仕様

• 貼り付け: 既定値 Ctrl + Shift + V（設定GUIで変更可能）
• キュー全消去: 既定値 Ctrl + Shift + Delete（設定GUIで変更可能）
• 終了: 既定値 Ctrl + Shift + Q（設定GUIで変更可能）
• 設定画面表示: Ctrl + Shift + S（固定）
• ホットキー登録失敗時は常駐を継続し、設定画面で再設定を促す。

FR-07 キュー全消去

• キュー全消去ホットキー入力で、履歴キュー内の要素をすべて削除する。
• 全消去後にFIFO貼り付けを実行した場合、空キュー扱いとなる。

FR-08 設定GUI

• 常駐中に設定画面を開き、ホットキー文字列を編集して保存できる。
• 保存時、ホットキー形式を検証し、競合または登録失敗時はエラー表示する。
• 設定は qlipboard.ini へ保存し、次回起動時に読み込む。
• 起動時は毎回設定画面を表示する。

FR-09 単一起動制御

• アプリは同時に1インスタンスのみ起動可能とする。
• 既に起動中の場合、2つ目以降の起動は通知を表示して終了する。

6. 非機能要件

NFR-01 応答性

• 監視イベント受信から履歴追加完了まで、体感遅延がないこと。

NFR-02 安定性

• クリップボード取得/設定に失敗しても異常終了しない。
• 失敗時は処理を中断し、次回イベント処理を継続できること。

NFR-03 メモリ制約

• 履歴件数は上限で制限し、無制限増加を禁止する。

7. 状態遷移（概念）

1. 起動
2. 監視待機
3. クリップボード更新検知
4. テキスト取得成功ならキューへ追加
5. ホットキーでFIFO先頭を取り出し貼り付け
6. 終了ホットキーで終了

8. エラー処理方針

• OpenClipboard失敗: 当該処理を中止して復帰。
• SetClipboardData失敗: 貼り付け処理を中止し、エラー通知。
• ホットキー未登録: 初期化失敗として終了。

9. 受け入れ条件

• AC-01: 任意の3つの文字列A,B,Cをこの順にコピーすると、履歴キューの取り出し順はA,B,Cである。
• AC-02: キュー空時に貼り付けホットキーを押してもクラッシュしない。
• AC-03: 51件連続コピー時、保持件数は50件で最古1件が破棄される。
• AC-04: アプリ終了ホットキーでプロセスが正常終了する。
• AC-05: 自己貼り付け時に同一データが即時に再蓄積されない。
• AC-06: キュー全消去ホットキー実行後は、FIFO貼り付けで警告動作となる（空キュー）。
• AC-07: 設定GUIで変更したホットキーが即時に再登録される。
• AC-08: アプリ再起動後も、保存済みホットキー設定が維持される。

10. ビルド要件

MSVC

cl /std:c++17 /EHsc /W4 /DUNICODE /D_UNICODE src\main.cpp src\hotkey_settings.cpp src\clipboard_fifo.cpp src\settings_window.cpp user32.lib

MinGW-w64

g++ -std=c++17 -municode -Wall -Wextra -O2 src/main.cpp src/hotkey_settings.cpp src/clipboard_fifo.cpp src/settings_window.cpp -o qlipboard.exe -luser32

11. 実行

.\qlipboard.exe

終了ホットキーはCtrl + Shift + Q。

設定画面はCtrl + Shift + Sで開く。

12. 将来拡張（任意）

• 履歴表示UI（トレイメニュー/一覧）
• 履歴の永続化
• 非テキスト形式への対応