syncfusion-winforms-popup

ポップアップコントロールの実装（PopupControlContainer）

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

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

• Windows Forms アプリケーションでカスタムポップアップパネルを作成する必要がある
• ポップアップを親コントロール（ボタン、テキストボックス、ラベルなど）に関連付けたい
• カスタムコントロールでドロップダウンのような動作を実装している
• ポップアップの自動クローズ、自動スクロール、キーボード操作を設定する必要がある
• ポップアップのライフサイクルイベント（表示前、表示後、閉じるとき）を処理したい
• コンテキストメニュー、ドロップダウンパネル、カスタムピッカーコントロールを作成している
• ポップアップに子コントロール（ボタン、グリッド、カレンダーなど）を配置する必要がある
• 透過またはサイズ変更可能なポップアップウィンドウが必要である
• ポップアップ内に ComboBoxBase やその他の複雑なコントロールを配置している
• ポップアップのクローズ動作やフォーカス管理で問題が発生している

コンポーネントの概要

PopupControlContainer は、子コントロールを配置し、親コントロールに関連付けることができる、パネル派生のコントロールです。既定ではポップアップは非表示で、親コントロールでのマウスクリック、ボタン押下、キーボード操作などのイベントを通じて、プログラムから表示できます。

主な機能：

• 任意の子コントロールを配置（ボタン、テキストボックス、グリッド、カスタムコントロール）
• 任意の親コントロールに関連付け
• ポップアップの外側をクリックすると自動クローズ
• コンテンツがポップアップのサイズを超えると自動スクロール
• ダイアログキー（Enter、Esc、Tab、F4、F2）によるキーボード操作
• イベント駆動型のライフサイクル（BeforePopup、Popup、CloseUp）
• 位置を指定したプログラムからの表示／非表示
• サイズ変更可能で透過するポップアップウィンドウ
• ネストされたポップアップをサポート（ComboBoxBase を配置）

一般的な用途：

• テキストボックスやボタン用のカスタムドロップダウンパネル
• カラーピッカー、日付ピッカー、カスタムセレクター
• コンテキストに応じて表示するツールバーやオプションパネル
• 操作可能なコントロールを備えたツールチップのようなウィンドウ
• カスタムコンボボックスの実装

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

はじめに

📄 参照： references/getting-started.md

• アセンブリの配置と NuGet パッケージ
• デザイナーとコードによるコントロールの追加
• 基本的な親コントロールとの関連付け
• ShowPopup メソッドと HidePopup メソッド
• 完全な動作例

ポップアップの動作設定

自動クローズの動作
📄 参照： references/auto-close-behavior.md

• 外側をクリックすると自動クローズする既定の動作
• IgnoreMouseMessages プロパティ
• PopupCloseType モード（Done、Canceled、Deactivated）
• 条件付きで閉じるケース

自動スクロール
📄 参照： references/autoscroll.md

• スクロールバーの自動有効化
• AutoScrollMargin と AutoScrollMinSize
• コンテンツのオーバーフローへの対処

キーボード操作
📄 参照： references/keyboard-navigation.md

• 既定のダイアログキーの動作
• IgnoreDialogKey プロパティ
• カスタムキーボード処理

イベントとライフサイクル

📄 参照： references/events.md

• BeforePopup イベント（表示前、サイズ変更時）
• Popup イベント（表示後、フォーカス管理）
• CloseUp イベント（閉じるとき、データの受け渡し）
• ニーモニックのサポートとフォーカス処理
• イベントハンドラーの完全な例

高度なシナリオ

📄 参照： references/advanced-scenarios.md

• ComboBoxBase コントロールの配置
• 透過ポップアップの作成
• IsShowing() によるポップアップ状態の確認
• BeforeCloseUp の回避策
• エッジケースとトラブルシューティング

クイックスタート例

基本的なポップアップの設定

using Syncfusion.Windows.Forms;

public partial class Form1 : Form
{
    private PopupControlContainer popupControlContainer1;
    private Button button1;
    private RichTextBox richTextBox1;
    
    public Form1()
    {
        InitializeComponent();
        
        // Initialize popup container
        this.popupControlContainer1 = new PopupControlContainer();
        
        // Add child control (button in this example)
        this.button1 = new Button();
        this.button1.Text = "Click Me";
        this.button1.Location = new Point(10, 10);
        this.popupControlContainer1.Controls.Add(this.button1);
        
        // Configure popup
        this.popupControlContainer1.Size = new Size(200, 100);
        
        // Create parent control
        this.richTextBox1 = new RichTextBox();
        this.richTextBox1.Size = new Size(150, 50);
        this.richTextBox1.Location = new Point(20, 20);
        this.richTextBox1.Click += RichTextBox1_Click;
        
        // Associate popup with parent
        this.popupControlContainer1.ParentControl = this.richTextBox1;
        
        // Add controls to form
        this.Controls.Add(this.richTextBox1);
    }
    
    private void RichTextBox1_Click(object sender, EventArgs e)
    {
        // Show popup at default position
        this.popupControlContainer1.ShowPopup(Point.Empty);
    }
}

特定の位置にポップアップを表示

// Show at specific screen coordinates
this.popupControlContainer1.ShowPopup(new Point(100, 200));

// Show below parent control
Point location = this.richTextBox1.PointToScreen(
    new Point(0, this.richTextBox1.Height));
this.popupControlContainer1.ShowPopup(location);

プログラムからポップアップを非表示にする

// Simple hide
this.popupControlContainer1.HidePopup();

// Hide with close type
this.popupControlContainer1.HidePopup(PopupCloseType.Done);
this.popupControlContainer1.HidePopup(PopupCloseType.Canceled);

一般的なパターン

パターン 1：条件付きの自動クローズ

// Prevent auto-close on outside clicks
this.popupControlContainer1.IgnoreMouseMessages = true;

// Close only when condition is met
private void ValidateButton_Click(object sender, EventArgs e)
{
    if (ValidateInput())
    {
        this.popupControlContainer1.HidePopup(PopupCloseType.Done);
    }
}

パターン 2：閉じるときのデータの受け渡し

private void PopupControlContainer1_CloseUp(object sender, PopupClosedEventArgs e)
{
    if (e.PopupCloseType == PopupCloseType.Done)
    {
        // Transfer data from popup to parent form
        this.textBox1.Text = this.popupTextBox.Text;
    }
    else if (e.PopupCloseType == PopupCloseType.Canceled)
    {
        // Discard changes
    }
}

パターン 3：サイズ変更可能なポップアップ

private void PopupControlContainer1_BeforePopup(object sender, CancelEventArgs e)
{
    // Make popup resizable
    this.popupControlContainer1.PopupHost.FormBorderStyle = FormBorderStyle.SizableToolWindow;
    this.popupControlContainer1.Dock = DockStyle.Fill;
    
    // Set minimum size
    if (this.popupControlContainer1.PopupHost.Size.Width < 200)
    {
        this.popupControlContainer1.PopupHost.Size = new Size(200, 150);
    }
}

パターン 4：透過ポップアップ

private void PopupControlContainer1_BeforePopup(object sender, CancelEventArgs e)
{
    // Set opacity for transparency
    this.popupControlContainer1.PopupHost.Opacity = 0.75;
}

主なプロパティとメソッド

プロパティ

プロパティ	型	説明
ParentControl	Control	ポップアップが関連付けられているコントロール
IgnoreMouseMessages	bool	true の場合、外側のクリックによる自動クローズを防ぎます
IgnoreDialogKey	bool	true の場合、既定のキーボードによるクローズ動作を無効にします
AutoScroll	bool	コンテンツが領域を超えたときにスクロールバーを自動的に表示します
AutoScrollMargin	Size	スクロール領域の周囲の余白
AutoScrollMinSize	Size	スクロール領域の最小サイズ
PopupHost	Form	ポップアップを格納するホストフォーム（イベント内でアクセスできます）

メソッド

メソッド	説明
ShowPopup(Point)	指定された画面座標にポップアップを表示します
HidePopup()	ポップアップを非表示にします
HidePopup(PopupCloseType)	指定されたクローズタイプでポップアップを非表示にします
IsShowing()	ポップアップが現在表示されている場合は true を返します

イベント

イベント	発生タイミング	主な用途
BeforePopup	ポップアップが表示される前	ポップアップのサイズ変更、外観のカスタマイズ、表示のキャンセル
Popup	ポップアップが表示された後	フォーカスの設定、ニーモニックの有効化
CloseUp	ポップアップが閉じられたとき	データの転送、フォーカスの復元、クローズタイプの処理

一般的なユースケース

ユースケース 1：カスタム日付ピッカー

テキストボックスに関連付けたカレンダーコントロールを含むポップアップを作成します。

ユースケース 2：カラーセレクターポップアップ

ボタンをクリックすると表示される、OK／Cancel ボタン付きのカラーピッカーパネルを作成します。

ユースケース 3：コンテキスト対応ツールバー

RichTextBox でテキストが選択されたときに、書式設定オプションを含むポップアップツールバーを表示します。

ユースケース 4：複数選択ドロップダウン

複数選択用のチェックボックスを含むポップアップを作成し、「Done」がクリックされたときだけ閉じます。

ユースケース 5：カスケードポップアップ

ポップアップ内に ComboBoxBase を格納し、適切なフォーカスを維持して、早すぎるクローズを防ぎます。

トラブルシューティングのヒント

ポップアップがすぐに閉じる場合：

• IgnoreMouseMessages = true を設定して自動クローズを防ぎます
• IgnoreDialogKey を有効にする必要があるか確認します
• イベントハンドラーが意図せず HidePopup() を呼び出していないか確認します

子コントロールでニーモニックが機能しない場合：

• Popup イベントを処理し、this.popupControlContainer1.Focus() を呼び出します

ポップアップが誤った位置に表示される場合：

• PointToScreen() を使用して、親コントロールの座標を画面座標に変換します
• 親コントロールのサイズと画面の境界を考慮します

コンテンツが切れている場合：

• AutoScroll = true を有効にします
• 適切な AutoScrollMinSize を設定します
• BeforePopup イベントでポップアップのサイズを調整します

ComboBoxBase のドロップダウンを開くとポップアップが閉じる場合：

• OnPopup() をオーバーライドしたカスタム PopupControlContainer を実装します
• ComboBoxBase の DropDown イベントで親子関係を設定します
• 実装の全容については、references/advanced-scenarios.md を参照してください

---

詳しい実装ガイダンス、コード例、エッジケースへの対応については、上記のドキュメントとナビゲーションガイドを使用して、該当するリファレンスファイルを参照してください。