ClicKey システム基本仕様書

· ♻️ · 📁 ClicKey
目次

概要

ClicKeyは、Windows向けのオンスクリーン操作支援アプリケーション。 「マウスだけで文字入力、ショートカット操作、マクロ実行を完結させる」ことを目的とし、他のアプリケーションのフォーカスを奪わない非アクティブウィンドウ (WS_EX_NOACTIVATE) として動作する。インストール不要のポータブル構成。

システム構成と動作環境

  • プラットフォーム: Windows 10 / 11（64bit）
  • フレームワーク: .NET 9.0（WPF / Windows Desktop）
  • 開発言語: C# (.NET 9.0)
  • アーキテクチャ: MVVM（Model-View-ViewModel）パターン
  • 実行権限: 管理者権限（他のウィンドウへ SendInput でキー操作を送信するための権限昇格が必要）
  • レジストリ使用: 自動起動設定のみ（HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Run）

画面・UI仕様 (UI/UX Design)

メインウィンドウ (MainWindow)

  • ウィンドウ構成: 左側の「マクロパネル」と右側の「キーボードパネル」で構成される2ペイン構造。中央のスプリッターで幅を調整可能。
  • 非アクティブウィンドウ: WS_EX_NOACTIVATE 属性により、クリックしても前景アプリケーションのフォーカスを奪わない。キー送出はすべて SendInput API 経由で前景ウィンドウに対して行われる。
  • IMEステータス表示: ツールバーに前景ウィンドウの現在のIME状態（IME: ON / IME: OFF）をリアルタイム表示。ImeService がポーリング（200ms間隔）で監視。

テーマ対応 (ThemeService)

  • 🖥️システム連動（System）、☀️ライト（Light）、🌙ダーク（Dark）の3種類。
  • system 選択時はレジストリ（AppsUseLightTheme）からOSの現在のテーマを取得し、OSのテーマ変更イベント (SystemEvents.UserPreferenceChanged) にリアルタイム追従。
  • ResourceDictionary (Themes/LightTheme.xaml, Themes/DarkTheme.xaml) を動的に差し替えてUI全体のスタイルを切替。
  • DWM API (DwmSetWindowAttribute) を用いてタイトルバーのダーク/ライトモードを全ウィンドウに適用。

ウィンドウ挙動制御 (WindowBehaviorService)

  • 📌画面端スナップ (Snap to Edge): ドラッグ終了時（WM_EXITSIZEMOVE）に画面端から20px以内であれば吸着。マルチモニタ環境に対応し、ウィンドウが最も多く含まれるディスプレイの作業領域(WorkArea)を基準に計算。
  • 👻オートハイド (Auto Hide): マウスが離れると500ms後にウィンドウの透明度を設定値（autoHideOpacity、デフォルト0.15）まで低下。マウスが戻ると即座に復帰。WindowsFormsHostの子HWNDが透過時に黒残りするバグを回避するため、半透明化の直前にCollapsedに切替。
  • 🔒サイズロック: ウィンドウサイズとスプリッター位置の変更を一括抑止。
  • ⬛タスクバー非表示: デフォルトでタスクバーにボタンを表示しない（ShowInTaskbar = false）。設定で切替可能。
  • 🔲ミニウィンドウ (RestoreWindow): メインウィンドウ非表示時に小型の再表示用ウィンドウを表示。前回位置を記憶。

タスクトレイ (TrayIconService)

  • WinForms の NotifyIcon を使用してタスクトレイにアイコンを常駐。
  • 左クリック: メインウィンドウの表示/非表示をトグル。
  • 右クリックメニュー:「表示/非表示の切替」「閉じる」の2項目。

設定画面 (SettingsWindow)

5つのカテゴリに分類されたタブナビゲーション構成。

カテゴリ設定項目
一般自動起動ON/OFF、タスクバー表示ON/OFF
外観テーマ（System/Dark/Light）、透明度、オートハイドON/OFF・透明度、コントロールボタン表示位置（左上/右上の隠す・オートの各ボタンの表示/非表示）
入力オートリピート遅延（ms）・間隔（ms）、カラー絵文字ON/OFF
サウンド音フィードバックON/OFF、打鍵音ファイル選択（Assets/内のWAV）、テスト再生
バージョン情報アプリ名、バージョン、著作権表示

機能仕様 (Functional Specifications)

⌨️ 仮想キーボード (Virtual Keyboard)

マウス操作のみでの各種文字入力を実現。グリッドベースのレイアウトをJSON定義に従い動的に描画。

タブ構成（3タブ + 絵文字サブカテゴリ）:

タブ名レイアウト説明
キーボードKeyBD.jsonJIS配列キーボード。Shift/CapsLock/かな入力の各状態を反映した動的ラベル表示
50音50音.json / 50音_Alphabet.json50音配列。ひらがな⇔アルファベットの切替対応
絵文字Emoji_*.json (24ファイル)絵文字入力。Smileys, People, Animals, Food, Travel, Activities, Objects, Symbols, Flags の各カテゴリ。カラー/アウトライン表示切替対応（Emoji.Wpf）。最近使用した絵文字の履歴（Emoji_History.json、最大100個）

キーボタンの仕組み (ButtonDefinition):

  • 各ボタンはグリッド座標 (x, y) とサイズ (width, height) で配置位置を定義。
  • Shift状態に応じてラベルが動的に切り替わる（label ⇔ labelShift）。
  • かな入力モード時は labelKana / labelKanaShift にフォールバック。
  • CapsLockとShiftの組み合わせは XOR 動作（両方ONで小文字に戻る）。
  • minOS プロパティで特定のWindows バージョン未満では非表示にするキーを制御。

オートリピート:

  • キー長押し時にオートリピート動作。開始遅延（デフォルト500ms）と繰返し間隔（デフォルト50ms）をユーザー設定可能。

🖱️ IME制御 (ImeService)

  • Win32 API (imm32.dll) を使用して前景ウィンドウのIME状態を取得・切替。
  • IMEのON/OFF監視を DispatcherTimer による200msポーリングで実施。状態変化時にイベント発火。
  • かな入力/ローマ字入力モードの検出と切替に対応（ImmGetConversionStatus / ImmSetConversionStatus）。
  • Scroll Lock 状態の監視にも対応。
  • 前景ウィンドウが自プロセス（ClicKey自身）の場合は、最後に記憶した外部ウィンドウのIME状態をフォールバック参照。

⚡ キー送出エンジン (KeyboardService)

  • SendInput API（user32.dll）を使用して仮想キー入力を前景ウィンドウに送出。
  • 対応するキー入力方式:
    • 単一キー送出 (SendKeyPress): 仮想キーコード指定
    • ショートカット (SendShortcut): "Ctrl+C" 形式の文字列を解析し、修飾キーを押下→メインキー打鍵→修飾キー解放の順で送出
    • Unicode文字列 (SendText): KEYEVENTF_UNICODE で1文字ずつ送出
    • WM_CHAR直接送信 (SendCharDirect): SendMessage(WM_CHAR) による同期送信。IME ON状態でもcompositionと干渉しない
  • Ctrl++ のような記号メインキーのショートカットでShift自動付与が誤動作しない安全な解析ロジック。
  • Windowsキー (VK_LWIN) は keybd_event で送出（SendInputでは動作不安定のため）。
  • 拡張キー（矢印、Home/End、Insert/Delete、右Ctrl/Alt等）の KEYEVENTF_EXTENDEDKEY フラグ自動付与。

📋 マクロ機能 (Macro System)

マクロの構成 (MacroDefinition):

  • 一意ID、表示名、ピン留め状態、表示順序、ステップ配列で構成。

対応するステップ種別 (MacroStep):

type説明例
key単一キー送出"Enter", "F5"
shortcutショートカット送出"Ctrl+S", "Alt+F4"
textUnicode文字列送出"こんにちは"
delay待機（ミリ秒）"500"

マクロ実行 (MacroService):

  • 非同期実行 (ExecuteAsync)。各ステップを順次処理。
  • CancellationToken によるキャンセル対応。

マクロ記録 (MacroRecordingService):

  • ClicKeyのボタン操作をリアルタイムにキャプチャしてステップとして蓄積。
  • 修飾キー（Ctrl/Shift/Alt/Win）はバッファに一時保持し、次のキーと自動結合してショートカットステップを生成（例: Ctrl押下 → C押下 → "Ctrl+C" ショートカット）。
  • 連続するテキスト入力は1つのtextステップに自動結合。
  • 最大記録ステップ数: 1000。

マクロパネル (MacroPanelViewModel):

  • 左パネルにマクロ一覧を表示。ピン留め、検索（履歴付き）、D&D並び替え、右クリックメニュー（編集・名前変更・複製・削除）に対応。
  • ストック機能: 1つのマクロを一時保管して貼り付け可能（stock_macro.json）。

マクロ永続化 (MacroStorageService):

  • Config/macros.json に保存。アトミック書き込み（.tmp → File.Move）でクラッシュ時のファイル破損を防止。
  • 3段階フォールバック読み込み: ①メイン → ②AppDataバックアップ → ③デフォルトテンプレート (macros.default.json)。
  • 正常起動時はバックアップを自動更新。

🔊 音フィードバック (AudioService)

  • キー押下時にカスタムWAVファイルまたはシステム音を再生。
  • Assets/ フォルダ内の .wav ファイルから選択可能（4種類同梱: key1.wav ～ key4.wav）。
  • SoundPlayer でプリロードし、再生遅延を最小化。
  • マクロ完了音・エラー音にも対応（SystemSounds使用）。

🚀 自動起動 (StartupHelper)

  • レジストリ (HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Run) にEXEパスを登録/削除。
  • 設定画面で有効/無効を切替。レジストリの実際の状態を起動時に検証。

データ保存仕様 (Data Storage)

アプリの実行ファイルと同一ディレクトリに設定・データを配置し、ポータビリティを実現。すべてJSON形式でシリアライズ（System.Text.Json）。

Config/settings.json

アプリケーション全体の設定状態を保存。

キー名型デフォルト値説明
themestring"system"テーマ（system / dark / light）
soundFeedbackbooltrue音フィードバックON/OFF
soundFilePathstring"key1.wav"打鍵音ファイル名
opacitydouble1.0ウィンドウ透明度（0.0〜1.0）
snapToEdgebooltrue画面端吸着ON/OFF
autoHideboolfalseオートハイドON/OFF
autoHideOpacitydouble0.15オートハイド時の透明度
autoStartboolfalseWindows起動時の自動起動
autoRepeat.delayint500オートリピート開始遅延（ms）
autoRepeat.intervalint50オートリピート間隔（ms）
window.x/y/width/heightdouble100/500/1200/400ウィンドウの位置とサイズ
lastActiveTabstring"KeyBD"最後に選択していたタブ名
enableColorEmojibooltrueカラー絵文字表示ON/OFF
lastEmojiCategorystring"Emoji_Smileys"最後の絵文字カテゴリー
lastGozyuonLayoutstring"50音"最後の50音レイアウト
recentEmojisstring[][]最近使用した絵文字（最大100個）
showInTaskbarboolfalseタスクバー表示
macroSearchHistorystring[][]マクロ検索履歴（最大10件）
macroPanelWidthdouble160マクロパネル幅（px）
isSizeLockedboolfalseサイズロック
showLeftHideButtonboolfalse左上の隠すボタン表示
showLeftAutoButtonboolfalse左上のオートボタン表示
showRightHideButtonbooltrue右上の隠すボタン表示
showRightAutoButtonbooltrue右上のオートボタン表示
startAsMiniWindowboolfalseミニウィンドウ状態で起動
keyChooser*/shortcutChooser*/macroEditor*double/double?各種各ダイアログの位置・サイズ
restoreWindowX/Ydouble?nullミニウィンドウの位置

Config/macros.json

ユーザーが作成したマクロ定義を配列として保存。

[
  {
    "id": "macro_001",
    "name": "保存",
    "isPinned": false,
    "sortOrder": 0,
    "steps": [
      { "type": "shortcut", "value": "Ctrl+S" }
    ]
  }
]

Config/macros.default.json

初回起動時のデフォルトマクロテンプレート。保存・検索・元に戻す・やり直す・コピー・切り取り・ペースト・全選択の8種類を同梱。

Config/stock_macro.json

マクロのストック（一時保管）データ。単一の MacroDefinition をシリアライズ。

Layouts/*.json

キーボードレイアウト定義。タブごとに1ファイル。

{
  "name": "KeyBD",
  "version": "1.0",
  "columns": 15,
  "rows": 5,
  "buttons": [
    {
      "id": "key_esc",
      "label": "Esc",
      "labelShift": null,
      "labelKana": null,
      "labelKanaShift": null,
      "x": 0, "y": 0,
      "width": 1, "height": 1,
      "actionType": "key",
      "actionValue": "Escape",
      "actionValueShift": null,
      "color": "#CCCCCC",
      "fontSize": 12,
      "minOS": 0.0,
      "tooltip": ""
    }
  ]
}

AppData バックアップ

  • パス: %APPDATA%\ClicKey\macros_backup.json
  • メインの macros.json が破損・消失した場合のフォールバック先。正常起動ごとに自動同期。

コメントを書く

メールアドレスは公開されません。