Implementing Popup Controls (PopupControlContainer)

When to Use This Skill

• 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

Component Overview

• 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)

• 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

Documentation and Navigation Guide

Getting Started

• Assembly deployment and NuGet packages
• Adding control via designer and code
• Basic parent control association
• ShowPopup and HidePopup methods
• Complete working examples

Popup Behavior Configuration

• Default auto-close on outside click
• IgnoreMouseMessages property
• PopupCloseType modes (Done, Canceled, Deactivated)
• Conditional closing scenarios

• Enabling automatic scrollbars
• AutoScrollMargin and AutoScrollMinSize
• Handling content overflow

• Default dialog key behavior
• IgnoreDialogKey property
• Custom keyboard handling

Events and Lifecycle

• 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

Advanced Scenarios

• Hosting ComboBoxBase controls
• Creating transparent popups
• Checking popup state with IsShowing()
• BeforeCloseUp workarounds
• Edge cases and troubleshooting

Quick Start Example

Basic Popup Setup

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

// 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

// 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

// 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

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

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

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

Key Properties and Methods

Properties

Methods

Events

Common Use Cases

Use Case 1: Custom Date Picker

Use Case 2: Color Selector Popup

Use Case 3: Context-Sensitive Toolbar

Use Case 4: Multi-Select Dropdown

Use Case 5: Cascading Popups

Troubleshooting Tips

• Set

  IgnoreMouseMessages = true

  to prevent auto-close
• Check if

  IgnoreDialogKey

  needs to be enabled
• Verify event handlers aren't calling

  HidePopup()

  unintentionally

• Handle the

  Popup

  event and call

  this.popupControlContainer1.Focus()

• Use

  PointToScreen()

  to convert parent control coordinates to screen coordinates
• Consider parent control size and screen boundaries

• Enable

  AutoScroll = true

• Set appropriate

  AutoScrollMinSize

• Adjust popup size in

  BeforePopup

  event

• Implement custom PopupControlContainer with overridden

  OnPopup()

• Set parent-child relationship in ComboBoxBase's

  DropDown

  event
• See references/advanced-scenarios.md for complete implementation