syncfusion-winforms-popup
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing 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
📄 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
📄 Read: references/autoscroll.md
- Enabling automatic scrollbars
- AutoScrollMargin and AutoScrollMinSize
- Handling content overflow
Keyboard Navigation
📄 Read: references/keyboard-navigation.md
📄 Read: references/keyboard-navigation.md
- Default dialog key behavior
- IgnoreDialogKey property
- Custom keyboard handling
自动关闭行为
📄 阅读: references/auto-close-behavior.md
📄 阅读: references/auto-close-behavior.md
- 点击外部区域默认自动关闭逻辑
- IgnoreMouseMessages属性说明
- PopupCloseType模式(Done、Canceled、Deactivated)
- 条件关闭场景实现
自动滚动
📄 阅读: references/autoscroll.md
📄 阅读: references/autoscroll.md
- 启用自动滚动条
- AutoScrollMargin与AutoScrollMinSize配置
- 内容溢出处理
键盘导航
📄 阅读: references/keyboard-navigation.md
📄 阅读: 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
属性
| Property | Type | Description |
|---|---|---|
| ParentControl | Control | The control to which the popup is associated |
| IgnoreMouseMessages | bool | Prevents auto-close on outside clicks when true |
| IgnoreDialogKey | bool | Disables default keyboard closing behavior when true |
| AutoScroll | bool | Enables automatic scrollbars when content overflows |
| AutoScrollMargin | Size | Margin around scroll region |
| AutoScrollMinSize | Size | Minimum size for scroll region |
| PopupHost | Form | The host form containing the popup (access in events) |
| 属性 | 类型 | 说明 |
|---|---|---|
| ParentControl | Control | 弹出框关联的父控件 |
| IgnoreMouseMessages | bool | 设置为true时可阻止点击外部区域自动关闭 |
| IgnoreDialogKey | bool | 设置为true时禁用默认键盘关闭行为 |
| AutoScroll | bool | 内容溢出时启用自动滚动条 |
| AutoScrollMargin | Size | 滚动区域边距 |
| AutoScrollMinSize | Size | 滚动区域最小尺寸 |
| PopupHost | Form | 承载弹出框的宿主窗体(在事件中访问) |
Methods
方法
| Method | Description |
|---|---|
| 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
事件
| Event | When Raised | Key Use Cases |
|---|---|---|
| BeforePopup | Before popup is shown | Resize popup, customize appearance, cancel showing |
| Popup | After popup is shown | Set focus, enable mnemonics |
| CloseUp | When popup is closed | Transfer 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 to prevent auto-close
IgnoreMouseMessages = true - Check if needs to be enabled
IgnoreDialogKey - Verify event handlers aren't calling unintentionally
HidePopup()
Child controls don't respond to mnemonics:
- Handle the event and call
Popupthis.popupControlContainer1.Focus()
Popup appears at wrong position:
- Use to convert parent control coordinates to screen coordinates
PointToScreen() - Consider parent control size and screen boundaries
Content is cut off:
- Enable
AutoScroll = true - Set appropriate
AutoScrollMinSize - Adjust popup size in event
BeforePopup
ComboBoxBase dropdown closes popup:
- Implement custom PopupControlContainer with overridden
OnPopup() - Set parent-child relationship in ComboBoxBase's event
DropDown - 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()
子控件不响应助记键:
- 处理事件,调用
Popupthis.popupControlContainer1.Focus()
弹出框显示位置错误:
- 使用将父控件坐标转换为屏幕坐标
PointToScreen() - 考虑父控件尺寸与屏幕边界
内容被截断:
- 启用
AutoScroll = true - 设置合适的
AutoScrollMinSize - 在事件中调整弹出框尺寸
BeforePopup
ComboBoxBase下拉框关闭父弹出框:
- 实现自定义PopupControlContainer,重写方法
OnPopup() - 在ComboBoxBase的事件中设置父子关系
DropDown - 查看references/advanced-scenarios.md获取完整实现方案
如需详细实现指南、代码示例与边界场景处理方案,请参考上方文档与导航指南跳转至对应的参考文件。