(custom-icons)=

# カスタムアイコン

PME でカスタムアイコンを使う方法について説明します。

## 基本情報

- **対応形式**: PNG（拡張子 `.png` のみ読み込まれます）
- **配置場所**: **ユーザーリソースディレクトリの `icons/` フォルダ**に置きます。詳細とOS別パスは [保存先とフォルダ構成](../reference/file_locations.md) を参照してください。  
  Windowsの場合: `%USERPROFILE%\Documents\Pie Menu Editor\icons\my_icon.png`
- **名前の扱い**: ファイル名（拡張子なし）がアイコン名になります（例: `my_icon.png` → アイコン名は `my_icon`）。大文字小文字やスペースも区別されるため、入力はファイル名と完全一致で。

```{tip}
{guilabel}`Preferences` > {guilabel}`Settings` > {guilabel}`Resources` の **Open Folder** ボタンから、`icons/` フォルダを直接開けます。
アドオンの更新で消えない場所に保存されるので、移行時に気にする必要はありません。
```

## アイコンの読み込みと更新

アイコンは Blender 起動時（アドオン有効化時）に読み込まれます。
追加・変更した PNG を反映するには、アイコン設定画面の **Custom** タブにある **更新ボタン**（{octicon}`sync`）を押します。

```{versionadded} 2.1
Blender を再起動せずにカスタムアイコンを再読み込みできます。
```

## カスタムアイコンの使い方

アイコン設定画面の **Custom** タブで、読み込まれたカスタムアイコンを確認・選択できます。

存在しない名前を指定すると、Blender の代替アイコンが表示されることがあります。

## スクリプトから使う（任意）

- **簡単指定（PME のラッパを利用）**: `@` を含む文字列をそのまま渡せます
  ```python
  # 例: LayoutHelper を使う場合
  lh.operator("wm.operator", text="Run", icon='@my_icon')
  ```
- **Blender 標準 UI API で使う**: `icon='NONE'` と `icon_value` を併用
  ```python
  # 例: Python から直接
  from pie_menu_editor.previews_helper import custom_icon
  layout.operator("wm.operator", text="Run", icon='NONE', icon_value=custom_icon("my_icon"))
  ```

## ネーミングと画質のヒント

- なるべく半角英数字と `_` を推奨（入力ミス防止）
- 透過背景の PNG を推奨
- 解像度は任意（一般的には 32〜64px 四方程度が見やすい）

## トラブルシューティング

- **表示されない/別アイコンになる**
  - 拡張子が `.png` か確認
  - ファイル名（拡張子なし）と指定文字列（`@name`）が完全一致か確認
  - 追加・変更後に **Custom** タブの更新ボタンを押したか確認
- **一覧に出てこない**
  - `icons` 直下に置いているか確認（サブフォルダは読み込まれません）
  - 画像が壊れていないか再保存して試す
  - 更新ボタンで再読み込みして確認

## 既存のサンプル

ユーザーリソースの `icons/` フォルダには `p1.png`, `p2.png`, `pA.png` などのサンプルが初期コピーされます。指定例: `@p1`, `@pA`

## まとめ

1. ユーザーリソースの `icons/` フォルダに PNG ファイルを配置（{guilabel}`Settings` > {guilabel}`Resources` > **Open Folder** から開く）
2. アイコン設定画面の **Custom** タブで更新ボタンを押す
3. PME 内で `@ファイル名` の形式で指定

## 参考

- [保存先とフォルダ構成](../reference/file_locations.md) — ユーザーリソースディレクトリの OS 別パスと変更方法