syncfusion-winforms-popup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Popup Controls (PopupControlContainer)

实现弹出控件(PopupControlContainer)

When to Use This Skill

何时使用本指南

Use this skill when the user:
  • Needs to create custom popup panels in Windows Forms applications
  • Wants to attach popups to parent controls (buttons, textboxes, labels, etc.)
  • Is implementing dropdown-like behavior with custom controls
  • Needs to configure auto-close, auto-scroll, or keyboard navigation for popups
  • Wants to handle popup lifecycle events (before showing, after showing, on close)
  • Is building context menus, dropdown panels, or custom picker controls
  • Needs to populate popups with child controls (buttons, grids, calendars, etc.)
  • Requires transparent or resizable popup windows
  • Is hosting ComboBoxBase or other complex controls within popups
  • Encounters issues with popup closing behavior or focus management
当用户存在以下需求时可使用本指南:
  • 需要在Windows Forms应用中创建自定义弹出面板
  • 希望将弹出框关联到父控件(按钮、文本框、标签等)
  • 要基于自定义控件实现类下拉框的交互效果
  • 需要为弹出框配置自动关闭、自动滚动或键盘导航能力
  • 希望处理弹出框生命周期事件(显示前、显示后、关闭时)
  • 正在构建上下文菜单、下拉面板或自定义选择器控件
  • 需要在弹出框中填充子控件(按钮、表格、日历等)
  • 需要透明或可调整大小的弹出窗口
  • 要在弹出框中承载ComboBoxBase或其他复杂控件
  • 遇到弹出框关闭行为或焦点管理相关问题

Component Overview

组件概览

PopupControlContainer is a panel-derived control that allows you to populate it with child controls and associate it with a parent control. By default, the popup is hidden and can be shown programmatically through events like mouse clicks, button presses, or keyboard actions on the parent control.
Key Capabilities:
  • Host any child controls (buttons, textboxes, grids, custom controls)
  • Associate with any parent control
  • Auto-close when clicking outside the popup
  • Auto-scroll when content exceeds popup size
  • Keyboard navigation with dialog keys (Enter, Esc, Tab, F4, F2)
  • Event-driven lifecycle (BeforePopup, Popup, CloseUp)
  • Programmatic show/hide with position control
  • Resizable and transparent popup windows
  • Support for nested popups (ComboBoxBase hosting)
Common Use Cases:
  • Custom dropdown panels for textboxes or buttons
  • Color pickers, date pickers, or custom selectors
  • Context-sensitive toolbars or option panels
  • Tooltip-like windows with interactive controls
  • Custom combo box implementations
PopupControlContainer 是派生自面板的控件,支持填充子控件并关联到父控件。默认状态下弹出框处于隐藏状态,可通过父控件的鼠标点击、按钮按下或键盘操作等事件编程触发显示。
核心功能:
  • 承载任意子控件(按钮、文本框、表格、自定义控件)
  • 关联任意父控件
  • 点击弹出框外区域时自动关闭
  • 内容超出弹出框尺寸时自动滚动
  • 支持对话框按键的键盘导航(Enter、Esc、Tab、F4、F2)
  • 事件驱动的生命周期(BeforePopup、Popup、CloseUp)
  • 可编程控制显示/隐藏及显示位置
  • 可调整大小、支持透明效果的弹出窗口
  • 支持嵌套弹出框(承载ComboBoxBase)
常见使用场景:
  • 为文本框或按钮定制下拉面板
  • 颜色选择器、日期选择器或自定义选择器
  • 上下文相关工具栏或选项面板
  • 带交互控件的类 tooltip 窗口
  • 自定义组合框实现

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Assembly deployment and NuGet packages
  • Adding control via designer and code
  • Basic parent control association
  • ShowPopup and HidePopup methods
  • Complete working examples
📄 阅读: references/getting-started.md
  • 程序集部署与NuGet包
  • 通过设计器和代码添加控件
  • 基础父控件关联配置
  • ShowPopup与HidePopup方法使用
  • 完整可运行示例

Popup Behavior Configuration

弹出行为配置

Auto-Close Behavior
📄 Read: references/auto-close-behavior.md
  • Default auto-close on outside click
  • IgnoreMouseMessages property
  • PopupCloseType modes (Done, Canceled, Deactivated)
  • Conditional closing scenarios
Auto-Scroll
📄 Read: references/autoscroll.md
  • Enabling automatic scrollbars
  • AutoScrollMargin and AutoScrollMinSize
  • Handling content overflow
Keyboard Navigation
📄 Read: references/keyboard-navigation.md
  • Default dialog key behavior
  • IgnoreDialogKey property
  • Custom keyboard handling
自动关闭行为
📄 阅读: references/auto-close-behavior.md
  • 点击外部区域默认自动关闭逻辑
  • IgnoreMouseMessages属性说明
  • PopupCloseType模式(Done、Canceled、Deactivated)
  • 条件关闭场景实现
自动滚动
📄 阅读: references/autoscroll.md
  • 启用自动滚动条
  • AutoScrollMargin与AutoScrollMinSize配置
  • 内容溢出处理
键盘导航
📄 阅读: references/keyboard-navigation.md
  • 默认对话框按键行为
  • IgnoreDialogKey属性说明
  • 自定义键盘事件处理

Events and Lifecycle

事件与生命周期

📄 Read: references/events.md
  • BeforePopup event (before showing, resizing)
  • Popup event (after shown, focus management)
  • CloseUp event (on close, data transfer)
  • Mnemonic support and focus handling
  • Complete event handler examples
📄 阅读: references/events.md
  • BeforePopup事件(显示、调整大小前触发)
  • Popup事件(显示完成后触发,用于焦点管理)
  • CloseUp事件(关闭时触发,用于数据传输)
  • 助记键支持与焦点处理
  • 完整事件处理示例

Advanced Scenarios

高级场景

📄 Read: references/advanced-scenarios.md
  • Hosting ComboBoxBase controls
  • Creating transparent popups
  • Checking popup state with IsShowing()
  • BeforeCloseUp workarounds
  • Edge cases and troubleshooting
📄 阅读: references/advanced-scenarios.md
  • 承载ComboBoxBase控件
  • 创建透明弹出框
  • 使用IsShowing()检查弹出框状态
  • BeforeCloseUp问题解决方案
  • 边界场景与故障排查

Quick Start Example

快速入门示例

Basic Popup Setup

基础弹出框配置

csharp
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);
    }
}
csharp
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 Popup at Specific Position

在指定位置显示弹出框

csharp
// 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);
csharp
// 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);

Hide Popup Programmatically

编程隐藏弹出框

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

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

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

Common Patterns

常用实现模式

Pattern 1: Conditional Auto-Close

模式1:条件自动关闭

csharp
// 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);
    }
}
csharp
// 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);
    }
}

Pattern 2: Data Transfer on Close

模式2:关闭时数据传输

csharp
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
    }
}
csharp
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
    }
}

Pattern 3: Resizable Popup

模式3:可调整大小的弹出框

csharp
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);
    }
}
csharp
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);
    }
}

Pattern 4: Transparent Popup

模式4:透明弹出框

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

Key Properties and Methods

核心属性与方法

Properties

属性

PropertyTypeDescription
ParentControlControlThe control to which the popup is associated
IgnoreMouseMessagesboolPrevents auto-close on outside clicks when true
IgnoreDialogKeyboolDisables default keyboard closing behavior when true
AutoScrollboolEnables automatic scrollbars when content overflows
AutoScrollMarginSizeMargin around scroll region
AutoScrollMinSizeSizeMinimum size for scroll region
PopupHostFormThe host form containing the popup (access in events)
属性类型说明
ParentControlControl弹出框关联的父控件
IgnoreMouseMessagesbool设置为true时可阻止点击外部区域自动关闭
IgnoreDialogKeybool设置为true时禁用默认键盘关闭行为
AutoScrollbool内容溢出时启用自动滚动条
AutoScrollMarginSize滚动区域边距
AutoScrollMinSizeSize滚动区域最小尺寸
PopupHostForm承载弹出框的宿主窗体(在事件中访问)

Methods

方法

MethodDescription
ShowPopup(Point)Displays the popup at the specified screen coordinates
HidePopup()Hides the popup
HidePopup(PopupCloseType)Hides the popup with a specific close type
IsShowing()Returns true if the popup is currently visible
方法说明
ShowPopup(Point)在指定屏幕坐标处显示弹出框
HidePopup()隐藏弹出框
HidePopup(PopupCloseType)按指定关闭类型隐藏弹出框
IsShowing()弹出框当前可见时返回true

Events

事件

EventWhen RaisedKey Use Cases
BeforePopupBefore popup is shownResize popup, customize appearance, cancel showing
PopupAfter popup is shownSet focus, enable mnemonics
CloseUpWhen popup is closedTransfer data, restore focus, handle close types
事件触发时机核心使用场景
BeforePopup弹出框显示前调整弹出框大小、自定义外观、取消显示
Popup弹出框显示完成后设置焦点、启用助记键
CloseUp弹出框关闭时传输数据、恢复焦点、处理不同关闭类型

Common Use Cases

常见使用场景

Use Case 1: Custom Date Picker

场景1:自定义日期选择器

Create a popup containing a calendar control attached to a textbox.
创建承载日历控件的弹出框,关联到文本框。

Use Case 2: Color Selector Popup

场景2:颜色选择弹出框

Build a color picker panel that pops up when clicking a button, with OK/Cancel buttons.
构建点击按钮时弹出的颜色选择面板,内置确认/取消按钮。

Use Case 3: Context-Sensitive Toolbar

场景3:上下文工具栏

Show a popup toolbar with formatting options when text is selected in a RichTextBox.
在RichTextBox中选中文本时显示带格式化选项的弹出工具栏。

Use Case 4: Multi-Select Dropdown

场景4:多选下拉框

Create a popup with checkboxes for multi-selection, closing only when "Done" is clicked.
创建带复选框的多选弹出框,仅在点击「完成」时关闭。

Use Case 5: Cascading Popups

场景5:级联弹出框

Host a ComboBoxBase within a popup, maintaining proper focus and preventing premature closure.
在弹出框中承载ComboBoxBase,维持正常焦点逻辑,避免提前关闭。

Troubleshooting Tips

故障排查提示

Popup closes immediately:
  • Set
    IgnoreMouseMessages = true
    to prevent auto-close
  • Check if
    IgnoreDialogKey
    needs to be enabled
  • Verify event handlers aren't calling
    HidePopup()
    unintentionally
Child controls don't respond to mnemonics:
  • Handle the
    Popup
    event and call
    this.popupControlContainer1.Focus()
Popup appears at wrong position:
  • Use
    PointToScreen()
    to convert parent control coordinates to screen coordinates
  • Consider parent control size and screen boundaries
Content is cut off:
  • Enable
    AutoScroll = true
  • Set appropriate
    AutoScrollMinSize
  • Adjust popup size in
    BeforePopup
    event
ComboBoxBase dropdown closes popup:
  • Implement custom PopupControlContainer with overridden
    OnPopup()
  • Set parent-child relationship in ComboBoxBase's
    DropDown
    event
  • See references/advanced-scenarios.md for complete implementation

For detailed implementation guidance, code examples, and edge case handling, navigate to the appropriate reference file using the Documentation and Navigation Guide above.
弹出框立即关闭:
  • 设置
    IgnoreMouseMessages = true
    阻止自动关闭
  • 检查是否需要启用
    IgnoreDialogKey
  • 确认事件处理程序没有意外调用
    HidePopup()
子控件不响应助记键:
  • 处理
    Popup
    事件,调用
    this.popupControlContainer1.Focus()
弹出框显示位置错误:
  • 使用
    PointToScreen()
    将父控件坐标转换为屏幕坐标
  • 考虑父控件尺寸与屏幕边界
内容被截断:
  • 启用
    AutoScroll = true
  • 设置合适的
    AutoScrollMinSize
  • BeforePopup
    事件中调整弹出框尺寸
ComboBoxBase下拉框关闭父弹出框:
  • 实现自定义PopupControlContainer,重写
    OnPopup()
    方法
  • 在ComboBoxBase的
    DropDown
    事件中设置父子关系
  • 查看references/advanced-scenarios.md获取完整实现方案

如需详细实现指南、代码示例与边界场景处理方案,请参考上方文档与导航指南跳转至对应的参考文件。