syncfusion-winforms-tooltip
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion Windows Forms Tooltips
实现Syncfusion Windows Forms工具提示
The Syncfusion 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.
SfToolTipSyncfusion的组件为Windows Forms应用提供了丰富的工具提示功能,当用户悬停在控件上时会自动弹出。它支持多个工具提示项、自定义控件、图片以及广泛的外观定制。
SfToolTipWhen 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 component offers:
SfToolTip- 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 over when you need multi-item support, individual tooltip item customization, or custom control hosting. offers richer styling and flexibility.
SfToolTipSuperToolTipSfToolTipSfToolTip- 多项目支持:添加多个工具提示项,每个项可单独设置样式
- 自定义控件:在工具提示项中嵌入任意用户控件
- 丰富内容:支持文本、图片、渐变和分隔符
- 气泡样式:显示带有方向箭头的工具提示
- 外观定制:全面的样式自定义(颜色、字体、边框、阴影)
- 事件支持:控制显示行为和自定义绘制
- 代码控制:按需显示/隐藏工具提示
对比说明:当你需要多项目支持、单个工具提示项定制或嵌入自定义控件时,选择而非。提供更丰富的样式和灵活性。
SfToolTipSuperToolTipSfToolTipDocumentation 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属性
| Property | Type | Description |
|---|---|---|
| int | Delay before tooltip appears (milliseconds, default: 0) |
| int | Duration tooltip remains visible (milliseconds, default: 5000) |
| bool | Enable shadow effect on tooltip |
| 属性 | 类型 | 描述 |
|---|---|---|
| int | 工具提示出现前的延迟时间(毫秒,默认值:0) |
| int | 工具提示保持可见的时长(毫秒,默认值:5000) |
| bool | 启用工具提示的阴影效果 |
ToolTipInfo Properties
ToolTipInfo属性
| Property | Type | Description |
|---|---|---|
| ToolTipItemCollection | Collection of tooltip items to display |
| ToolTipStyle | Rectangle (default) or Balloon style |
| Color | Background color of balloon beak |
| Color | Border color of tooltip |
| int | Border thickness in pixels |
| int | Minimum tooltip width |
| int | Maximum tooltip width |
| RightToLeft | RTL layout support |
| 属性 | 类型 | 描述 |
|---|---|---|
| ToolTipItemCollection | 要显示的工具提示项集合 |
| ToolTipStyle | 矩形(默认)或气泡样式 |
| Color | 气泡箭头的背景色 |
| Color | 工具提示的边框颜色 |
| int | 边框厚度(像素) |
| int | 工具提示的最小宽度 |
| int | 工具提示的最大宽度 |
| RightToLeft | RTL布局支持 |
ToolTipItem Properties
ToolTipItem属性
| Property | Type | Description |
|---|---|---|
| string | Tooltip item text content |
| Image | Image to display in item |
| ImageList | ImageList for multiple images |
| int | Index when using ImageList |
| Control | Custom control to host in item |
| bool | Show separator line after item |
| bool | Enable gradient background |
| Padding | Spacing around item content |
| ToolTipStyleInfo | Comprehensive styling options |
| 属性 | 类型 | 描述 |
|---|---|---|
| string | 工具提示项的文本内容 |
| Image | 项中显示的图片 |
| ImageList | 用于多图片的ImageList |
| int | 使用ImageList时的索引 |
| Control | 项中嵌入的自定义控件 |
| bool | 在项后显示分隔线 |
| bool | 启用渐变背景 |
| Padding | 项内容的内边距 |
| ToolTipStyleInfo | 全面的样式选项 |
ToolTipStyleInfo (Style) Properties
ToolTipStyleInfo(Style)属性
| Property | Type | Description |
|---|---|---|
| Color | Background color |
| Color | Text color |
| Font | Text font |
| ContentAlignment | Text alignment (MiddleLeft, etc.) |
| ToolTipImageAlignment | Image position (Left, Top, Right) |
| Size | Fixed image dimensions |
| int | Spacing between image and text |
| BrushInfo | Gradient configuration |
| Color | Separator line color |
| DashStyle | Separator line style |
| 属性 | 类型 | 描述 |
|---|---|---|
| Color | 背景色 |
| Color | 文本颜色 |
| Font | 文本字体 |
| ContentAlignment | 文本对齐方式(如MiddleLeft) |
| ToolTipImageAlignment | 图片位置(左、上、右) |
| Size | 固定图片尺寸 |
| int | 图片与文本之间的间距 |
| BrushInfo | 渐变配置 |
| Color | 分隔线颜色 |
| DashStyle | 分隔线样式 |
Common Use Cases
常见使用场景
- Form Field Help: Add descriptive tooltips to form controls explaining expected input
- Button Actions: Display action descriptions for toolbar buttons and icons
- Status Information: Show detailed status for status bar items or indicators
- User Profiles: Display rich profile cards with images on hover
- Data Validation: Show validation rules or error details on validation controls
- Dashboard Widgets: Provide detailed metrics in chart or widget tooltips
- Disabled Controls: Explain why a control is disabled and when it becomes available
- Progress Indicators: Show detailed progress information on hover
- Icon Tray Applications: Display application status in system tray tooltips
- Multi-language Support: Show translations or additional context with RTL support
- 表单字段帮助:为表单控件添加描述性工具提示,说明预期输入内容
- 按钮操作说明:为工具栏按钮和图标显示操作描述
- 状态信息展示:为状态栏项或指示器显示详细状态
- 用户资料展示:悬停时显示带图片的丰富资料卡片
- 数据验证提示:为验证控件显示验证规则或错误详情
- 仪表盘小部件:在图表或小部件的工具提示中提供详细指标
- 禁用控件说明:解释控件禁用的原因以及启用条件
- 进度指示器提示:悬停时显示详细进度信息
- 托盘应用提示:在系统托盘工具提示中显示应用状态
- 多语言支持:通过RTL支持显示翻译内容或额外上下文
Events
事件
| Event | Description | Use Case |
|---|---|---|
| Fires before tooltip displays | Customize appearance per control, cancel display conditionally, adjust location |
| Fires during tooltip rendering | Implement custom drawing, override default appearance |
| 事件 | 描述 | 适用场景 |
|---|---|---|
| 工具提示显示前触发 | 为每个控件定制外观、条件性取消显示、调整位置 |
| 工具提示渲染时触发 | 实现自定义绘制、覆盖默认外观 |
Assembly Dependencies
程序集依赖
Required Assembly:
- and
Syncfusion.Core.WinForms.dllSyncfusion.Shared.Base
NuGet Package:
Syncfusion.Core.WinForms
必需程序集:
- 和
Syncfusion.Core.WinForms.dllSyncfusion.Shared.Base
NuGet包:
Syncfusion.Core.WinForms
Best Practices
最佳实践
- Keep tooltips concise: Users read tooltips quickly; provide essential information only
- Use balloon style sparingly: Balloon tooltips draw more attention; use for important hints
- Avoid redundancy: Don't repeat control labels verbatim in tooltips
- Consider timing: Adjust and
InitialDelaybased on content complexityAutoPopDelay - Accessibility: Ensure tooltip text is readable with sufficient color contrast
- Performance: Avoid complex custom controls in tooltips for frequently-hovered controls
- Test RTL layouts: Verify tooltip appearance in right-to-left language configurations
- 保持工具提示简洁:用户会快速浏览工具提示,仅提供必要信息
- 谨慎使用气泡样式:气泡样式更吸引注意力,仅用于重要提示
- 避免冗余:不要在工具提示中重复控件标签内容
- 合理设置时机:根据内容复杂度调整和
InitialDelayAutoPopDelay - 注重可访问性:确保工具提示文本颜色对比度足够,便于阅读
- 考虑性能:对于频繁悬停的控件,避免在工具提示中嵌入复杂自定义控件
- 测试RTL布局:验证工具提示在从右到左语言配置下的显示效果