syncfusion-winforms-popup-menu

Windows Forms での PopupMenu の実装

このスキルでは、Windows Forms アプリケーションに Syncfusion PopupMenu コントロールを実装するための包括的なガイダンスを提供します。PopupMenu は、ユーザーの操作に応じて表示されるコンテキストメニューです。複数の BarItem タイプ、マルチレベル階層、キーボード操作、Bar Manager との統合をサポートします。

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• WinForms でコンテキストメニューや右クリックメニューを実装する必要がある
• さまざまな種類の項目（ボタン、ドロップダウン、コンボボックス、リスト）を含むポップアップメニューを作成したい
• 入れ子になったサブメニューを含むマルチレベルのメニュー構造が必要である
• メニューでキーボードショートカット、ニーモニック、タッチ操作を使用したい
• 区切り線でメニュー項目をグループ化する必要がある
• メニューでチェック状態や無効状態の項目を使用したい
• メニュー項目に画像やツールチップを表示する必要がある
• ポップアップメニューを Bar Manager または CommandBar と統合したい
• 使用頻度の高い項目を優先する部分メニューが必要である
• デスクトップアプリケーション向けに、状況に応じたメニューシステムを構築している

コンポーネントの概要

PopupMenu は、既定では非表示で、操作（通常は右クリック）をきっかけに任意のコントロール上に表示されるコンテキストメニューコントロールです。7 種類の BarItem、マルチレベルの入れ子構造、外観のカスタマイズ、キーボードとタッチによる包括的な操作をサポートします。

主な機能：

• 7 種類の BarItem： BarItem、ParentBarItem、DropDownBarItem、ComboBoxBarItem、ListBarItem、StaticBarItem、TextBoxBarItem
• マルチレベルメニュー： 深さに制限のない入れ子のサブメニュー構造
• グループ化： 関連するメニュー項目間の区切り線
• 状態： チェック状態／未チェック状態、有効状態／無効状態をサポート
• 外観のカスタマイズ： 画像（通常、無効、強調表示）、ツールチップ
• キーボードサポート： ショートカット、ニーモニック、キーボード操作
• タッチサポート： 最新デバイス向けに既定でタッチ操作を有効化
• 部分メニュー： 使用頻度の高い項目を優先し、その他の項目を非表示にする
• 統合： Bar Manager、CommandBar、PopupMenusManager
• イベント： BeforePopup、Popup、Collapse、ParentBarItemChanged

主要コンポーネント：

• PopupMenu： メニュー構造を格納するメインコントロール
• ParentBarItem： すべてのメニュー項目を格納するルートコンテナー
• PopupMenusManager： ポップアップメニューをコントロールに関連付ける
• BarItems： 個々のメニュー項目（7 種類を使用可能）

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• アセンブリ参照と依存関係
• デザイナーから PopupMenu を追加する（ツールボックスからドラッグ＆ドロップ）
• コードから PopupMenu を追加する（初期化とセットアップ）
• PopupMenusManager の構成
• ポップアップメニューをコントロール（RichTextBox、Button など）に関連付ける
• 既定の ParentBarItem を追加する
• テキストと画像を含む基本的な BarItem を作成する
• NuGet パッケージのインストール

BarItem の種類と構成

📄 参照： references/baritem-types.md

• BarItem： テキスト、画像、イベントを含む標準のメニュー項目
• ParentBarItem： サブメニュー項目を格納するコンテナー（階層型メニュー）
• DropDownBarItem： カスタム PopupControlContainer（ColorPicker など）を含むドロップダウン
• ComboBoxBarItem： メニュー内の編集可能なコンボボックス
• ListBarItem： メニュー内の子項目のリスト
• StaticBarItem： 隣接する項目に使用するラベル／静的テキスト
• TextBoxBarItem： メニュー内のテキスト入力フィールド
• 各種類のデザイナーとコードの例
• 各 BarItem の種類の使い分け

マルチレベルメニューとグループ化

📄 参照： references/multilevel-menus.md

• 入れ子になったメニュー構造の作成
• サブメニューのコンテナーとして ParentBarItem を追加
• 階層型メニューの構築（ファイル → 新規 → 新しいプロジェクト）
• 深さに制限のないメニュー階層
• 複数レベルにわたる複雑なメニューの例

📄 参照： references/grouping-baritems.md

• メニュー項目間に区切り線を追加
• グループ化に使用する SeparatorIndices プロパティ
• プログラムからグループ化する BeginGroupAt() メソッド
• 区切り線を削除する RemoveGroupAt() メソッド
• グループ化の状態を確認する IsGroupBeginning()
• 視覚的な整理パターン

視覚的なカスタマイズ

📄 参照： references/baritem-states.md

• チェック状態と未チェック状態（Checked プロパティ）
• Click イベントによる切り替え動作
• 有効状態と無効状態（Enabled プロパティ）
• 状態管理のパターン
• OverlapCheckBoxImageBounds（チェックボックスと画像の重なりを制御）
• チェック状態と他の表示方法の使い分け

📄 参照： references/images-and-tooltips.md

• BarItems に画像を追加（Image プロパティ）
• 画像の読み込みに使用する ImageExt クラス
• 無効状態で使用する DisabledImage
• ホバー／選択状態で使用する HighlightedImage
• ツールチップの設定（Tooltip プロパティ）
• ツールチップを有効にする ShowToolTipInPopUp
• アイコンのガイドラインとベストプラクティス

キーボードと操作

📄 参照： references/keyboard-interaction.md

• タッチのサポート（デフォルトで有効）
• キーボードショートカット（Shortcut プロパティ、例：Ctrl+F）
• カスタムショートカットのテキスト（ShortcutText プロパティ）
• キーボードニーモニック（&Text、例：「&File」）
• ニーモニックを常に表示する ShowMnemonicUnderlinesAlways
• メニュー項目の選択に対する Click イベント処理
• キーボードとマウスを使った操作の実行

高度な統合

📄 参照： references/advanced-features.md

• 部分メニュー（UsePartialMenus プロパティ）
• 使用頻度に基づいて優先表示する IsRecentlyUsedItem
• アプリケーション全体のメニューを対象とした Bar Manager の統合
• CommandBar との関連付け（ドロップダウンとしての PopupMenu）
• CommandBarController の設定
• イベント：BeforePopup、Popup、Collapse、ParentBarItemChanged
• イベント駆動型のメニューカスタマイズ

📄 参照： references/troubleshooting.md

• よくあるセットアップの問題
• デザイナーとコードの違い
• アセンブリ参照の問題
• PopupMenusManager の設定に関する問題
• BarItem の表示に関する問題
• イベント処理のトラブルシューティング

クイックスタートの例

BarItems を使った基本的な PopupMenu

using Syncfusion.Windows.Forms.Tools.XPMenus;
using System.Windows.Forms;

public partial class Form1 : Form
{
    private PopupMenu popupMenu1;
    private ParentBarItem parentBarItem1;
    private BarItem barItem1;
    private BarItem barItem2;
    private BarItem barItem3;
    private PopupMenusManager popupMenusManager1;
    private RichTextBox richTextBox1;

    public Form1()
    {
        InitializeComponent();
        
        // Initialize components
        this.popupMenu1 = new PopupMenu(this.components);
        this.parentBarItem1 = new ParentBarItem();
        this.barItem1 = new BarItem();
        this.barItem2 = new BarItem();
        this.barItem3 = new BarItem();
        this.richTextBox1 = new RichTextBox();
        this.popupMenusManager1 = new PopupMenusManager(this.components);
        
        // Configure popup menu
        this.popupMenu1.ParentBarItem = this.parentBarItem1;
        
        // Configure BarItems
        this.barItem1.Text = "Cut";
        this.barItem1.Shortcut = Shortcut.CtrlX;
        this.barItem1.Click += BarItem1_Click;
        
        this.barItem2.Text = "Copy";
        this.barItem2.Shortcut = Shortcut.CtrlC;
        this.barItem2.Click += BarItem2_Click;
        
        this.barItem3.Text = "Paste";
        this.barItem3.Shortcut = Shortcut.CtrlV;
        this.barItem3.Click += BarItem3_Click;
        
        // Add items to parent
        this.parentBarItem1.Items.AddRange(new BarItem[] { 
            this.barItem1, this.barItem2, this.barItem3 
        });
        this.parentBarItem1.SizeToFit = true;
        
        // Associate with control
        this.richTextBox1.Size = new System.Drawing.Size(300, 200);
        this.popupMenusManager1.SetXPContextMenu(this.richTextBox1, this.popupMenu1);
        
        // Add to form
        this.Controls.Add(this.richTextBox1);
    }
    
    private void BarItem1_Click(object sender, EventArgs e)
    {
        if (richTextBox1.SelectionLength > 0)
        {
            richTextBox1.Cut();
        }
    }
    
    private void BarItem2_Click(object sender, EventArgs e)
    {
        if (richTextBox1.SelectionLength > 0)
        {
            richTextBox1.Copy();
        }
    }
    
    private void BarItem3_Click(object sender, EventArgs e)
    {
        richTextBox1.Paste();
    }
}

よくあるパターン

パターン 1：マルチレベルのメニュー構造

// Create hierarchy: File → New → New Project, New Website
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "File";

ParentBarItem newSubmenu = new ParentBarItem();
newSubmenu.Text = "New";

BarItem newProject = new BarItem();
newProject.Text = "New Project...";
newProject.Click += NewProject_Click;

BarItem newWebsite = new BarItem();
newWebsite.Text = "New Website...";
newWebsite.Click += NewWebsite_Click;

// Build hierarchy
newSubmenu.Items.AddRange(new BarItem[] { newProject, newWebsite });
fileMenu.Items.Add(newSubmenu);
parentBarItem1.Items.Add(fileMenu);

パターン 2：区切り線によるグループ化

// Create menu items
BarItem cut = new BarItem { Text = "Cut" };
BarItem copy = new BarItem { Text = "Copy" };
BarItem paste = new BarItem { Text = "Paste" };
BarItem selectAll = new BarItem { Text = "Select All" };

// Add items
parentBarItem1.Items.AddRange(new BarItem[] { cut, copy, paste, selectAll });

// Add separator after index 2 (after Paste)
parentBarItem1.SeparatorIndices.Add(2);

// Alternative: Use method
parentBarItem1.BeginGroupAt(selectAll);

パターン 3：チェック可能なメニュー項目

BarItem wordWrap = new BarItem();
wordWrap.Text = "Word Wrap";
wordWrap.Checked = true;  // Initial state
wordWrap.Click += (s, e) => 
{
    wordWrap.Checked = !wordWrap.Checked;  // Toggle
    richTextBox1.WordWrap = wordWrap.Checked;  // Apply setting
};

パターン 4：画像付きメニュー項目

BarItem saveItem = new BarItem();
saveItem.Text = "Save";
saveItem.Image = new ImageExt(Image.FromFile(@"icons\save.png"));
saveItem.DisabledImage = new ImageExt(Image.FromFile(@"icons\save_disabled.png"));
saveItem.HighlightedImage = new ImageExt(Image.FromFile(@"icons\save_highlight.png"));
saveItem.Shortcut = Shortcut.CtrlS;
saveItem.Tooltip = "Save the current document";
saveItem.ShowToolTipInPopUp = true;

パターン 5：部分メニュー（よく使用する項目）

// Enable partial menus
parentBarItem1.UsePartialMenus = true;

// Mark items as frequently used (visible by default)
cutItem.IsRecentlyUsedItem = true;
copyItem.IsRecentlyUsedItem = true;
pasteItem.IsRecentlyUsedItem = true;

// Mark items as less frequently used (hidden initially)
advancedItem.IsRecentlyUsedItem = false;
optionsItem.IsRecentlyUsedItem = false;

主なプロパティとイベント

PopupMenu のプロパティ

• ParentBarItem： すべてのメニュー項目を格納するルートコンテナー（必須）

ParentBarItem のプロパティ

• Items： メニュー内の BarItems のコレクション
• SizeToFit： コンテンツに合わせてメニュー項目のサイズを自動調整
• SeparatorIndices： 区切り線を表示するインデックスのコレクション
• UsePartialMenus： 優先順位付けされたメニュー表示を有効化
• OverlapCheckBoxImageBounds： チェックボックスと画像の重なり方を制御

BarItem のプロパティ

• Text： メニュー項目に表示するテキスト
• Image： 項目とともに表示するアイコン
• DisabledImage： 項目が無効なときに表示するアイコン
• HighlightedImage： 項目が強調表示またはホバーされたときに表示するアイコン
• Tooltip： ホバー時に表示するツールチップのテキスト
• ShowToolTipInPopUp： ツールチップの表示を有効にします
• Shortcut： キーボードショートカット（Ctrl+C、Alt+F など）
• ShortcutText： ショートカット表示用のカスタムテキスト
• Checked： テキストの前にチェックマークを表示します
• Enabled： メニュー項目を有効または無効にします
• IsRecentlyUsedItem： よく使う項目としてマークします（部分メニュー用）
• ShowMnemonicUnderlinesAlways： ニーモニックの下線を常に表示します
• SizeToFit： 内容に合わせて項目のサイズを自動調整します

PopupMenusManager のメソッド

• SetXPContextMenu(Control, PopupMenu)： ポップアップメニューをコントロールに関連付けます

ParentBarItem のメソッド

• BeginGroupAt(BarItem)： 指定した項目の前に区切り線を追加します
• RemoveGroupAt(BarItem)： 指定した項目の前にある区切り線を削除します
• IsGroupBeginning(BarItem)： 項目がグループの先頭かどうかを確認します

イベント

• BeforePopup： メニューの表示前に発生します（マウス位置の取得、メニューのカスタマイズ）
• Popup： メニューの表示後に発生します
• Collapse： メニューが閉じられたときに発生します
• ParentBarItemChanged： ParentBarItem のプロパティが変更されたときに発生します
• Click (BarItem)： メニュー項目がクリックされたときに発生します

一般的なユースケース

ユースケース 1：テキストエディターのコンテキストメニュー

RichTextBox に、切り取り、コピー、貼り付け、すべて選択、および書式設定オプションを含むコンテキストメニューを作成します。

ユースケース 2：グリッド／DataGridView のコンテキストメニュー

行の追加、行の削除、セルの編集、データのエクスポートなどのオプションを含むコンテキストメニューをグリッドに追加します。

ユースケース 3：ファイル／フォルダーのコンテキストメニュー

開く、コピー、削除、プロパティ、および入れ子になったサブメニューを含む Windows エクスプローラー風のコンテキストメニューを実装します。

ユースケース 4：フォームコントロールのコンテキストメニュー

ボタン、ラベル、またはパネルに、コントロール固有の操作を含むコンテキストメニューを追加します。

ユースケース 5：アプリケーション全体のメニューシステム

PopupMenu を Bar Manager と統合し、アプリケーション全体で一貫したメニュー操作を実現します。

ユースケース 6：動的なコンテキストメニュー

BeforePopup イベントを使って、アプリケーションの状態に応じてメニュー項目をカスタマイズします（項目の有効化／無効化、オプションの表示／非表示）。

ユースケース 7：タッチ対応メニュー

組み込みのタッチサポートを活用し、タブレットやタッチスクリーン向けのアプリケーションを実現します。

ヒントとベストプラクティス

BarItem の種類の選択：

• 標準的なメニューコマンドには BarItem を使用します
• サブメニューには ParentBarItem を使用します
• カスタムコントロール（ColorPicker、カスタムパネル）が必要な場合は DropDownBarItem を使用します
• 編集機能付きの選択には ComboBoxBarItem を使用します
• 選択肢が固定されたリストには ListBarItem を使用します
• ラベルや見出しには StaticBarItem を使用します
• メニュー内のテキスト入力には TextBoxBarItem を使用します

パフォーマンス：

• 可能な場合は、複数のコントロール間で PopupMenu のインスタンスを再利用します
• メニューを作り直す代わりに、動的なカスタマイズには BeforePopup イベントを使用します
• メニュー項目に大きな画像を読み込むのは避け、16x16 または 24x24 のアイコンを使用します

アクセシビリティ：

• よく使うコマンドには必ずキーボードショートカットを設定します
• キーボード操作にはニーモニック（&Text）を使用します
• アイコンのみの項目には、内容がわかるツールチップのテキストを設定します
• 無効な項目が視覚的に区別できるようにします

デザイナーとコード：

• 静的なメニュー構造にはデザイナーを使うと、よりすばやく作成できます
• 動的なメニューをより細かく制御するにはコードを使用します
• デザイナーのスマートタグを使うと、すばやく設定できます
• 一貫性を確保するため、デザイナーとコードの両方の方法をテストします

---

詳しい実装方法については、「Documentation and Navigation Guide」セクションに記載されているリファレンスファイルを参照してください。