syncfusion-winforms-banner-text-provider（syncfusion winforms 横幅文本提供程序）

Implementing Syncfusion WinForms BannerTextProvider

When to Use This Skill

Use this skill when:

• User needs watermark/placeholder text - Displaying hint text in empty editor controls
• Implementing BannerTextProvider - Adding banner text to TextBoxExt, ComboBoxAdv, CurrencyTextBox, or other editor controls
• Customizing banner appearance - Setting text color, font, visibility modes
• Configuring text display modes - Choosing between FocusMode (disappear on focus) or EditMode (disappear on input)
• Supporting multiple editor controls - Applying banner text across various Syncfusion or Microsoft controls
• User mentions: watermark, placeholder text, hint text, banner text, BannerTextProvider, BannerTextInfo

Component Overview

The BannerTextProvider is an extender control that displays watermark text in editor controls. It provides visual hints when controls are empty and automatically hides the text when users interact with the control.

Key Features:

• Text Modes: FocusMode and EditMode for controlling when banner text disappears
• Customization: Text color, font, and visibility control
• Multi-Control Support: Works with 14+ editor controls (TextBoxExt, ComboBoxAdv, CurrencyTextBox, etc.)
• Designer & Code Support: Add via Form designer or programmatically

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Assembly deployment and NuGet installation
• Adding BannerTextProvider via Form Designer
• Adding BannerTextProvider via Code
• Assigning banner text to controls
• Basic BannerTextInfo setup

Banner Text Configuration

📄 Read: references/banner-text-configuration.md

• Text property and visibility control
• Setting text color (BannerTextInfo.Color)
• Customizing font (BannerTextInfo.Font)
• Mode property: FocusMode vs EditMode
• Complete configuration examples

Supported Controls

📄 Read: references/supported-controls.md

• Complete list of 14+ supported controls
• Control categories (Editors, Menu, Ribbon, Toolbar)
• Compatibility matrix
• Best practices per control type
• Limitations and workarounds

Practical Examples

📄 Read: references/practical-examples.md

• Complete end-to-end code examples
• Designer-based implementation walkthrough
• Code-based implementation patterns
• Multiple controls with different settings
• Dynamic banner text changes at runtime

Customization and Tips

📄 Read: references/customization-and-tips.md

• Advanced styling techniques
• Performance optimization
• Common pitfalls and troubleshooting
• Edge cases and best practices
• Accessibility considerations

Quick Start Example

// 1. Create BannerTextProvider (usually in Form designer or Form_Load)
BannerTextProvider bannerTextProvider = new BannerTextProvider(this.components);

// 2. Create TextBoxExt control
TextBoxExt textBox = new TextBoxExt()
{
    Size = new System.Drawing.Size(200, 30),
    Location = new System.Drawing.Point(20, 20)
};
this.Controls.Add(textBox);

// 3. Set banner text
BannerTextInfo bannerInfo = new BannerTextInfo()
{
    Text = "Enter your name...",
    Visible = true,
    Font = new System.Drawing.Font("Verdana", 9, System.Drawing.FontStyle.Italic),
    Color = System.Drawing.Color.Gray,
    Mode = BannerTextMode.EditMode  // Disappears when user types
};

bannerTextProvider.SetBannerText(textBox, bannerInfo);

Common Patterns

Pattern 1: Simple Placeholder Text

When you need basic hint text that disappears on user input:

bannerTextProvider.SetBannerText(textBox,
    new BannerTextInfo("Type here...", true));

Pattern 2: Styled Watermark (EditMode)

For a more prominent watermark that only hides when content is added:

var bannerInfo = new BannerTextInfo(
    Text = "Email address",
    Visible = true,
    Font = new Font("Verdana", 8.25f, FontStyle.Italic),
    Color = Color.RoyalBlue,
    Mode = BannerTextMode.EditMode
);
bannerTextProvider.SetBannerText(emailTextBox, bannerInfo);

Pattern 3: Focus-Based Banner (FocusMode)

For temporary hints that disappear when control receives focus:

var bannerInfo = new BannerTextInfo(
    Text = "Click to edit",
    Visible = true,
    Color = Color.LightGray,
    Mode = BannerTextMode.FocusMode  // Disappears on focus
);
bannerTextProvider.SetBannerText(textBox, bannerInfo);

Pattern 4: Multi-Control Setup

Apply banner text to multiple editor controls efficiently:

var controls = new[] { nameTextBox, emailTextBox, phoneTextBox };
var placeholders = new[] { "Full Name", "Email Address", "Phone Number" };

for (int i = 0; i < controls.Length; i++)
{
    bannerTextProvider.SetBannerText(controls[i],
        new BannerTextInfo(placeholders[i], true));
}

Key Modes Explained

Note: Clear the control's default Text property before setting banner text for optimal results.

Important Considerations

⚠️ Clear default text: Always clear the Text property of the control before setting banner text ⚠️ Supported controls only: BannerTextProvider works with 14+ specific controls (see supported-controls.md) ⚠️ Assembly reference: Requires Syncfusion.Shared.Base assembly ⚠️ EditMode best practice: Use EditMode when you need the banner to persist until the user enters text

Next steps: Start with Getting Started to set up the component, then refer to other guides based on your specific needs.