syncfusion-winforms-tooltip

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion Windows Forms Tooltips

实现Syncfusion Windows Forms工具提示

The Syncfusion
SfToolTip
component provides rich tooltip functionality for Windows Forms applications, appearing automatically as a popup when the user hovers over a control. It supports multiple tooltip items, custom controls, images, and extensive appearance customization.
Syncfusion的
SfToolTip
组件为Windows Forms应用提供了丰富的工具提示功能,当用户悬停在控件上时会自动弹出。它支持多个工具提示项、自定义控件、图片以及广泛的外观定制。

When to Use This Skill

适用场景

Use this skill when you need to:
  • Add tooltips to Windows Forms controls with basic or advanced content
  • Display multi-item tooltips with multiple lines of information or sections
  • Show balloon-style tooltips with beaks pointing to controls
  • Customize tooltip appearance with colors, borders, gradients, images
  • Host custom controls inside tooltips for rich interactive content
  • Programmatically control tooltip display timing and positioning
  • Implement contextual help with hover-based information panels
  • Support RTL layouts for internationalized applications
  • Create custom-drawn tooltips with specialized rendering
当你需要以下功能时,可以使用本技能:
  • 为Windows Forms控件添加工具提示,支持基础或高级内容
  • 显示多项目工具提示,包含多行信息或多个板块
  • 展示气泡样式工具提示,带有指向控件的喙状箭头
  • 定制工具提示外观,包括颜色、边框、渐变、图片
  • 在工具提示中嵌入自定义控件,实现丰富的交互式内容
  • 通过代码控制工具提示的显示时机和位置
  • 实现上下文帮助,基于悬停展示信息面板
  • 支持RTL布局,适配国际化应用
  • 创建自定义绘制的工具提示,实现特殊渲染效果

Component Overview

组件概述

The
SfToolTip
component offers:
  • Multiple items: Add multiple tooltip items with individual styling
  • Custom controls: Host any user control in tooltip items
  • Rich content: Text, images, gradients, and separators
  • Balloon style: Display tooltips with directional beaks
  • Appearance: Extensive customization (colors, fonts, borders, shadows)
  • Events: Control display behavior and custom drawing
  • Programmatic control: Show/hide tooltips on demand
Comparison: Choose
SfToolTip
over
SuperToolTip
when you need multi-item support, individual tooltip item customization, or custom control hosting.
SfToolTip
offers richer styling and flexibility.
SfToolTip
组件具备以下特性:
  • 多项目支持:添加多个工具提示项,每个项可单独设置样式
  • 自定义控件:在工具提示项中嵌入任意用户控件
  • 丰富内容:支持文本、图片、渐变和分隔符
  • 气泡样式:显示带有方向箭头的工具提示
  • 外观定制:全面的样式自定义(颜色、字体、边框、阴影)
  • 事件支持:控制显示行为和自定义绘制
  • 代码控制:按需显示/隐藏工具提示
对比说明:当你需要多项目支持、单个工具提示项定制或嵌入自定义控件时,选择
SfToolTip
而非
SuperToolTip
SfToolTip
提供更丰富的样式和灵活性。

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When implementing basic tooltips:
  • Assembly deployment and required dependencies
  • Setting tooltips using simple text (designer and code)
  • Setting tooltips using ToolTipInfo for structured content
  • Programmatically showing and hiding tooltips
  • Configuring tooltip delay times (InitialDelay, AutoPopDelay)
  • Basic balloon style setup
📄 阅读文档references/getting-started.md
实现基础工具提示时:
  • 程序集部署和所需依赖
  • 通过简单文本设置工具提示(设计器和代码方式)
  • 使用ToolTipInfo设置结构化内容的工具提示
  • 通过代码显示和隐藏工具提示
  • 配置工具提示延迟时间(InitialDelay、AutoPopDelay)
  • 基础气泡样式设置

Tooltip Items and Content

工具提示项与内容

📄 Read: references/tooltip-items-and-content.md
When working with tooltip content structure:
  • Creating and configuring ToolTipItem objects
  • Adding multiple items to a single tooltip
  • Configuring spacing and padding between items
  • Adding images using Image or ImageList properties
  • Setting image alignment (Left, Top, Right)
  • Configuring image size and spacing
  • Hosting custom user controls in tooltips
📄 阅读文档references/tooltip-items-and-content.md
处理工具提示内容结构时:
  • 创建和配置ToolTipItem对象
  • 为单个工具提示添加多个项
  • 配置项之间的间距和内边距
  • 使用Image或ImageList属性添加图片
  • 设置图片对齐方式(左、上、右)
  • 配置图片尺寸和间距
  • 在工具提示中嵌入自定义用户控件

Balloon Style and Beak

气泡样式与箭头

📄 Read: references/balloon-style-and-beak.md
When implementing balloon-style tooltips:
  • Enabling ToolTipStyle.Balloon
  • Understanding balloon vs rectangle styles
  • Customizing beak back color
  • Positioning balloons relative to controls
  • Use cases for balloon-style tooltips
📄 阅读文档references/balloon-style-and-beak.md
实现气泡样式工具提示时:
  • 启用ToolTipStyle.Balloon
  • 了解气泡样式与矩形样式的区别
  • 自定义箭头背景色
  • 设置气泡相对于控件的位置
  • 气泡样式工具提示的适用场景

Appearance Customization

外观定制

📄 Read: references/appearance-customization.md
When customizing tooltip visual appearance:
  • Border color and thickness
  • Individual ToolTipItem styling (colors, fonts, alignment)
  • Gradient background implementation
  • Separator customization between items
  • Shadow effects
  • RTL (Right-to-Left) layout support
📄 阅读文档references/appearance-customization.md
定制工具提示视觉外观时:
  • 边框颜色和厚度
  • 单个ToolTipItem的样式设置(颜色、字体、对齐方式)
  • 渐变背景实现
  • 项之间的分隔符定制
  • 阴影效果
  • RTL(从右到左)布局支持

Advanced Usage and Events

高级用法与事件

📄 Read: references/advanced-usage.md
When implementing advanced tooltip features:
  • Getting and setting tooltip text/info programmatically
  • Using ToolTipShowing event for conditional display
  • Customizing appearance per control dynamically
  • Changing tooltip location before display
  • Setting minimum and maximum widths
  • Custom drawing with DrawToolTipItem event
  • Canceling default rendering
📄 阅读文档references/advanced-usage.md
实现高级工具提示功能时:
  • 通过代码获取和设置工具提示文本/信息
  • 使用ToolTipShowing事件实现条件显示
  • 动态为每个控件定制外观
  • 显示前修改工具提示位置
  • 设置最小和最大宽度
  • 使用DrawToolTipItem事件实现自定义绘制
  • 取消默认渲染

Quick Start

快速开始

Basic Tooltip with Text

基础文本工具提示

csharp
using Syncfusion.Windows.Forms;

// Add SfToolTip component to form
SfToolTip sfToolTip1 = new SfToolTip();

// Set simple text tooltip
sfToolTip1.SetToolTip(this.button1, "Click to submit the form");
csharp
using Syncfusion.Windows.Forms;

// 向窗体添加SfToolTip组件
SfToolTip sfToolTip1 = new SfToolTip();

// 设置简单文本工具提示
sfToolTip1.SetToolTip(this.button1, "点击提交表单");

Tooltip with Multiple Items

多项目工具提示

csharp
using Syncfusion.Windows.Forms;
using Syncfusion.WinForms.Controls;

SfToolTip sfToolTip1 = new SfToolTip();

// Create ToolTipInfo with multiple items
ToolTipInfo toolTipInfo = new ToolTipInfo();

ToolTipItem item1 = new ToolTipItem();
item1.Text = "User Information";
item1.Style.Font = new Font("Arial", 10f, FontStyle.Bold);

ToolTipItem item2 = new ToolTipItem();
item2.Text = "Name: John Doe\nEmail: john@example.com";

toolTipInfo.Items.AddRange(new ToolTipItem[] { item1, item2 });
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);
csharp
using Syncfusion.Windows.Forms;
using Syncfusion.WinForms.Controls;

SfToolTip sfToolTip1 = new SfToolTip();

// 创建包含多个项的ToolTipInfo
ToolTipInfo toolTipInfo = new ToolTipInfo();

ToolTipItem item1 = new ToolTipItem();
item1.Text = "用户信息";
item1.Style.Font = new Font("Arial", 10f, FontStyle.Bold);

ToolTipItem item2 = new ToolTipItem();
item2.Text = "姓名: John Doe\n邮箱: john@example.com";

toolTipInfo.Items.AddRange(new ToolTipItem[] { item1, item2 });
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

Balloon Style Tooltip with Image

带图片的气泡样式工具提示

csharp
SfToolTip sfToolTip1 = new SfToolTip();

ToolTipInfo toolTipInfo = new ToolTipInfo();
toolTipInfo.ToolTipStyle = ToolTipStyle.Balloon;
toolTipInfo.BeakBackColor = Color.LightSkyBlue;

ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Text = "David Carter\nPhone: +1 919.494.1974\nEmail: david@syncfusion.com";
toolTipItem.Image = Properties.Resources.UserImage;
toolTipItem.Style.ImageSize = new Size(80, 80);
toolTipItem.Style.ImageAlignment = ToolTipImageAlignment.Left;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);
csharp
SfToolTip sfToolTip1 = new SfToolTip();

ToolTipInfo toolTipInfo = new ToolTipInfo();
toolTipInfo.ToolTipStyle = ToolTipStyle.Balloon;
toolTipInfo.BeakBackColor = Color.LightSkyBlue;

ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Text = "David Carter\n电话: +1 919.494.1974\n邮箱: david@syncfusion.com";
toolTipItem.Image = Properties.Resources.UserImage;
toolTipItem.Style.ImageSize = new Size(80, 80);
toolTipItem.Style.ImageAlignment = ToolTipImageAlignment.Left;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

Common Patterns

常见模式

Pattern 1: Rich Formatted Tooltip with Gradient

模式1:带渐变效果的富格式工具提示

csharp
ToolTipInfo toolTipInfo = new ToolTipInfo();
toolTipInfo.BorderColor = Color.DarkGray;
toolTipInfo.BorderThickness = 2;

ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Text = "Important Information";
toolTipItem.EnableGradientBackground = true;
toolTipItem.Style.GradientBrush = new BrushInfo(
    GradientStyle.Horizontal, 
    new Color[] { Color.LightBlue, Color.LightGreen }
);
toolTipItem.Style.Font = new Font("Arial", 10f, FontStyle.Bold);
toolTipItem.Style.ForeColor = Color.DarkBlue;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.control, toolTipInfo);
csharp
ToolTipInfo toolTipInfo = new ToolTipInfo();
toolTipInfo.BorderColor = Color.DarkGray;
toolTipInfo.BorderThickness = 2;

ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Text = "重要信息";
toolTipItem.EnableGradientBackground = true;
toolTipItem.Style.GradientBrush = new BrushInfo(
    GradientStyle.Horizontal, 
    new Color[] { Color.LightBlue, Color.LightGreen }
);
toolTipItem.Style.Font = new Font("Arial", 10f, FontStyle.Bold);
toolTipItem.Style.ForeColor = Color.DarkBlue;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.control, toolTipInfo);

Pattern 2: Conditional Tooltip Display

模式2:条件性显示工具提示

csharp
sfToolTip1.ToolTipShowing += (sender, e) =>
{
    // Customize tooltip based on control state
    if (e.Control is Button button && !button.Enabled)
    {
        e.Cancel = true; // Don't show tooltip for disabled controls
    }
    
    // Or modify appearance dynamically
    if (e.Control.Tag?.ToString() == "Warning")
    {
        e.ToolTipInfo.Items[0].Style.BackColor = Color.LightCoral;
        e.ToolTipInfo.BorderColor = Color.Red;
    }
};
csharp
sfToolTip1.ToolTipShowing += (sender, e) =>
{
    // 根据控件状态定制工具提示
    if (e.Control is Button button && !button.Enabled)
    {
        e.Cancel = true; // 不为禁用控件显示工具提示
    }
    
    // 或动态修改外观
    if (e.Control.Tag?.ToString() == "Warning")
    {
        e.ToolTipInfo.Items[0].Style.BackColor = Color.LightCoral;
        e.ToolTipInfo.BorderColor = Color.Red;
    }
};

Pattern 3: Programmatic Tooltip Display

模式3:通过代码控制工具提示显示

csharp
// Show tooltip at specific location
Point location = new Point(300, 200);
sfToolTip1.Show("Processing complete!", location);

// Show tooltip at cursor position with duration
ToolTipInfo info = new ToolTipInfo();
ToolTipItem item = new ToolTipItem { Text = "Operation successful!" };
info.Items.Add(item);
sfToolTip1.Show(info);

// Hide after delay
await Task.Delay(3000);
sfToolTip1.Hide();
csharp
// 在指定位置显示工具提示
Point location = new Point(300, 200);
sfToolTip1.Show("处理完成!", location);

// 在光标位置显示工具提示并设置持续时间
ToolTipInfo info = new ToolTipInfo();
ToolTipItem item = new ToolTipItem { Text = "操作成功!" };
info.Items.Add(item);
sfToolTip1.Show(info);

// 延迟后隐藏
await Task.Delay(3000);
sfToolTip1.Hide();

Pattern 4: Custom Control in Tooltip

模式4:工具提示中嵌入自定义控件

csharp
// Create custom control (e.g., PictureBox with animated GIF)
PictureBox pictureBox = new PictureBox();
pictureBox.Image = Image.FromFile("loading.gif");
pictureBox.SizeMode = PictureBoxSizeMode.CenterImage;
pictureBox.Size = new Size(200, 100);

ToolTipInfo toolTipInfo = new ToolTipInfo();
ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Control = pictureBox;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);
csharp
// 创建自定义控件(例如带动态GIF的PictureBox)
PictureBox pictureBox = new PictureBox();
pictureBox.Image = Image.FromFile("loading.gif");
pictureBox.SizeMode = PictureBoxSizeMode.CenterImage;
pictureBox.Size = new Size(200, 100);

ToolTipInfo toolTipInfo = new ToolTipInfo();
ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Control = pictureBox;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

Key Properties

关键属性

SfToolTip Properties

SfToolTip属性

PropertyTypeDescription
InitialDelay
intDelay before tooltip appears (milliseconds, default: 0)
AutoPopDelay
intDuration tooltip remains visible (milliseconds, default: 5000)
ShadowVisible
boolEnable shadow effect on tooltip
属性类型描述
InitialDelay
int工具提示出现前的延迟时间(毫秒,默认值:0)
AutoPopDelay
int工具提示保持可见的时长(毫秒,默认值:5000)
ShadowVisible
bool启用工具提示的阴影效果

ToolTipInfo Properties

ToolTipInfo属性

PropertyTypeDescription
Items
ToolTipItemCollectionCollection of tooltip items to display
ToolTipStyle
ToolTipStyleRectangle (default) or Balloon style
BeakBackColor
ColorBackground color of balloon beak
BorderColor
ColorBorder color of tooltip
BorderThickness
intBorder thickness in pixels
MinWidth
intMinimum tooltip width
MaxWidth
intMaximum tooltip width
RightToLeft
RightToLeftRTL layout support
属性类型描述
Items
ToolTipItemCollection要显示的工具提示项集合
ToolTipStyle
ToolTipStyle矩形(默认)或气泡样式
BeakBackColor
Color气泡箭头的背景色
BorderColor
Color工具提示的边框颜色
BorderThickness
int边框厚度(像素)
MinWidth
int工具提示的最小宽度
MaxWidth
int工具提示的最大宽度
RightToLeft
RightToLeftRTL布局支持

ToolTipItem Properties

ToolTipItem属性

PropertyTypeDescription
Text
stringTooltip item text content
Image
ImageImage to display in item
ImageList
ImageListImageList for multiple images
ImageIndex
intIndex when using ImageList
Control
ControlCustom control to host in item
EnableSeparator
boolShow separator line after item
EnableGradientBackground
boolEnable gradient background
Padding
PaddingSpacing around item content
Style
ToolTipStyleInfoComprehensive styling options
属性类型描述
Text
string工具提示项的文本内容
Image
Image项中显示的图片
ImageList
ImageList用于多图片的ImageList
ImageIndex
int使用ImageList时的索引
Control
Control项中嵌入的自定义控件
EnableSeparator
bool在项后显示分隔线
EnableGradientBackground
bool启用渐变背景
Padding
Padding项内容的内边距
Style
ToolTipStyleInfo全面的样式选项

ToolTipStyleInfo (Style) Properties

ToolTipStyleInfo(Style)属性

PropertyTypeDescription
BackColor
ColorBackground color
ForeColor
ColorText color
Font
FontText font
TextAlignment
ContentAlignmentText alignment (MiddleLeft, etc.)
ImageAlignment
ToolTipImageAlignmentImage position (Left, Top, Right)
ImageSize
SizeFixed image dimensions
ImageToTextOffset
intSpacing between image and text
GradientBrush
BrushInfoGradient configuration
SeparatorColor
ColorSeparator line color
SeparatorStyle
DashStyleSeparator line style
属性类型描述
BackColor
Color背景色
ForeColor
Color文本颜色
Font
Font文本字体
TextAlignment
ContentAlignment文本对齐方式(如MiddleLeft)
ImageAlignment
ToolTipImageAlignment图片位置(左、上、右)
ImageSize
Size固定图片尺寸
ImageToTextOffset
int图片与文本之间的间距
GradientBrush
BrushInfo渐变配置
SeparatorColor
Color分隔线颜色
SeparatorStyle
DashStyle分隔线样式

Common Use Cases

常见使用场景

  1. Form Field Help: Add descriptive tooltips to form controls explaining expected input
  2. Button Actions: Display action descriptions for toolbar buttons and icons
  3. Status Information: Show detailed status for status bar items or indicators
  4. User Profiles: Display rich profile cards with images on hover
  5. Data Validation: Show validation rules or error details on validation controls
  6. Dashboard Widgets: Provide detailed metrics in chart or widget tooltips
  7. Disabled Controls: Explain why a control is disabled and when it becomes available
  8. Progress Indicators: Show detailed progress information on hover
  9. Icon Tray Applications: Display application status in system tray tooltips
  10. Multi-language Support: Show translations or additional context with RTL support
  1. 表单字段帮助:为表单控件添加描述性工具提示,说明预期输入内容
  2. 按钮操作说明:为工具栏按钮和图标显示操作描述
  3. 状态信息展示:为状态栏项或指示器显示详细状态
  4. 用户资料展示:悬停时显示带图片的丰富资料卡片
  5. 数据验证提示:为验证控件显示验证规则或错误详情
  6. 仪表盘小部件:在图表或小部件的工具提示中提供详细指标
  7. 禁用控件说明:解释控件禁用的原因以及启用条件
  8. 进度指示器提示:悬停时显示详细进度信息
  9. 托盘应用提示:在系统托盘工具提示中显示应用状态
  10. 多语言支持:通过RTL支持显示翻译内容或额外上下文

Events

事件

EventDescriptionUse Case
ToolTipShowing
Fires before tooltip displaysCustomize appearance per control, cancel display conditionally, adjust location
DrawToolTipItem
Fires during tooltip renderingImplement custom drawing, override default appearance
事件描述适用场景
ToolTipShowing
工具提示显示前触发为每个控件定制外观、条件性取消显示、调整位置
DrawToolTipItem
工具提示渲染时触发实现自定义绘制、覆盖默认外观

Assembly Dependencies

程序集依赖

Required Assembly:
  • Syncfusion.Core.WinForms.dll
    and
    Syncfusion.Shared.Base
NuGet Package:
  • Syncfusion.Core.WinForms
必需程序集:
  • Syncfusion.Core.WinForms.dll
    Syncfusion.Shared.Base
NuGet包:
  • Syncfusion.Core.WinForms

Best Practices

最佳实践

  1. Keep tooltips concise: Users read tooltips quickly; provide essential information only
  2. Use balloon style sparingly: Balloon tooltips draw more attention; use for important hints
  3. Avoid redundancy: Don't repeat control labels verbatim in tooltips
  4. Consider timing: Adjust
    InitialDelay
    and
    AutoPopDelay
    based on content complexity
  5. Accessibility: Ensure tooltip text is readable with sufficient color contrast
  6. Performance: Avoid complex custom controls in tooltips for frequently-hovered controls
  7. Test RTL layouts: Verify tooltip appearance in right-to-left language configurations
  1. 保持工具提示简洁:用户会快速浏览工具提示,仅提供必要信息
  2. 谨慎使用气泡样式:气泡样式更吸引注意力,仅用于重要提示
  3. 避免冗余:不要在工具提示中重复控件标签内容
  4. 合理设置时机:根据内容复杂度调整
    InitialDelay
    AutoPopDelay
  5. 注重可访问性:确保工具提示文本颜色对比度足够,便于阅读
  6. 考虑性能:对于频繁悬停的控件,避免在工具提示中嵌入复杂自定义控件
  7. 测试RTL布局:验证工具提示在从右到左语言配置下的显示效果