syncfusion-winforms-color-ui-control
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing ColorUIControl
实现ColorUIControl
When to Use This Skill
何时使用本指南
Use this skill when you need to implement color selection functionality in Windows Forms applications using Syncfusion's ColorUIControl. This skill is relevant when users:
- Need to add color picker UI to Windows Forms applications
- Want to provide Visual Studio-style color selection interface
- Require inline color selection controls (not just dialogs)
- Need customizable color palettes with predefined color groups
- Want to integrate color pickers into popup menus or dropdowns
- Need to implement color selection with System, Standard, Custom, or User-defined colors
- Are working with .NET Framework Windows Forms applications
- Want to provide ColorPickerButton dropdown functionality
The ColorUIControl provides a palette-style interface similar to Visual Studio's color picker, offering four color groupings (SystemColors, StandardColors, CustomColors, UserColors) that can be displayed inline in your application or as a dropdown.
当你需要在Windows Forms应用中使用Syncfusion的ColorUIControl实现颜色选择功能时可参考本指南,适用场景包括:
- 需要为Windows Forms应用添加颜色拾取器UI
- 想要提供Visual Studio风格的颜色选择界面
- 需要行内颜色选择控件(不只是对话框形式)
- 需要支持预定义颜色分组的可自定义调色板
- 想要将颜色拾取器集成到弹出菜单或下拉菜单中
- 需要实现支持系统、标准、自定义或用户定义颜色的颜色选择功能
- 正在开发.NET Framework Windows Forms应用
- 想要提供ColorPickerButton下拉功能
ColorUIControl提供了类似Visual Studio颜色拾取器的调色板式界面,支持四种颜色分组(系统颜色、标准颜色、自定义颜色、用户颜色),可以在应用中行内展示,也可以作为下拉控件使用。
Component Overview
组件概述
ColorUIControl is a Windows Forms control that provides a rich color selection interface with predefined color palettes. Unlike the standard ColorDialog which appears as a modal dialog, ColorUIControl can be placed inline within your application's layout or used as a dropdown control.
Key Capabilities:
- Four predefined color groups (System, Standard, Custom, User)
- Inline placement within application layout
- Popup/dropdown integration via PopupControlContainer
- Customizable color palettes and tab names
- Visual Studio-style color picker interface
- Programmatic and interactive color selection
- Border style customization and panel stretching
ColorUIControl是一款Windows Forms控件,提供了带预定义调色板的丰富颜色选择界面。和标准的模态ColorDialog不同,ColorUIControl可以直接嵌入到应用布局中,也可以作为下拉控件使用。
核心功能:
- 四种预定义颜色分组(系统、标准、自定义、用户)
- 支持嵌入应用布局行内展示
- 可通过PopupControlContainer实现弹出/下拉集成
- 支持自定义调色板和标签名称
- Visual Studio风格的颜色拾取器界面
- 支持编程式和交互式颜色选择
- 边框样式自定义和面板拉伸适配
Documentation and Navigation Guide
文档与导航指南
Getting Started
快速开始
📄 Read: references/getting-started.md
When users need to:
- Install and set up the ColorUIControl component
- Add ColorUIControl via designer or code
- Understand assembly dependencies (Syncfusion.Shared.Base)
- Initialize the control in C# or VB.NET
- Set initial selected color and color group
- Import required namespaces (Syncfusion.Windows.Forms)
📄 阅读: references/getting-started.md
适用场景:
- 安装并配置ColorUIControl组件
- 通过设计器或代码添加ColorUIControl
- 了解程序集依赖(Syncfusion.Shared.Base)
- 使用C#或VB.NET初始化控件
- 设置初始选中颜色和颜色分组
- 导入必要的命名空间(Syncfusion.Windows.Forms)
Color Groups and Selection
颜色分组与选择
📄 Read: references/color-groups.md
When users need to:
- Understand the four color groups (System, Standard, Custom, User)
- Control which color groups are displayed
- Select default color groups programmatically
- Customize UserColors and UserCustomColors collections
- Add or remove specific color groups
- Programmatically populate custom color cells
📄 阅读: references/color-groups.md
适用场景:
- 了解四种颜色分组(系统、标准、自定义、用户)
- 控制展示哪些颜色分组
- 通过代码设置默认选中的颜色分组
- 自定义UserColors和UserCustomColors集合
- 添加或删除指定颜色分组
- 通过代码填充自定义颜色单元格
Appearance and Customization
外观与自定义
📄 Read: references/appearance-customization.md
When users need to:
- Set border styles (FixedSingle, Fixed3D, None)
- Enable panel stretching for Custom and User color groups
- Customize tab text for each color group
- Change font styles for tab text
- Reset tab names to defaults
- Adjust visual appearance of the control
📄 阅读: references/appearance-customization.md
适用场景:
- 设置边框样式(FixedSingle、Fixed3D、None)
- 为自定义和用户颜色分组启用面板拉伸适配
- 自定义每个颜色分组的标签文本
- 修改标签文本的字体样式
- 重置标签名称为默认值
- 调整控件的视觉外观
Events and Interaction
事件与交互
📄 Read: references/events.md
When users need to:
- Handle the ColorSelected event
- Close popups when colors are selected
- Access selected color from event handlers
- Work with PopupControlContainer in events
- Implement color selection callbacks
📄 阅读: references/events.md
适用场景:
- 处理ColorSelected事件
- 选中颜色后关闭弹出框
- 从事件处理程序中获取选中的颜色
- 在事件中使用PopupControlContainer
- 实现颜色选择回调逻辑
Advanced Scenarios
高级场景
📄 Read: references/popup-integration.md
When users need to:
- Add ColorUIControl to popup menus
- Integrate with PopupMenu and PopupControlContainer
- Configure DropDownBarItem for color pickers
- Show color picker on mouse clicks
- Use ColorPickerButton for dropdown functionality
- Create complete popup color selection workflows
📄 阅读: references/popup-integration.md
适用场景:
- 向弹出菜单添加ColorUIControl
- 与PopupMenu和PopupControlContainer集成
- 为颜色拾取器配置DropDownBarItem
- 点击鼠标时展示颜色拾取器
- 使用ColorPickerButton实现下拉功能
- 构建完整的弹出式颜色选择工作流
Quick Start Example
快速入门示例
Here's a minimal example to add ColorUIControl to a Windows Forms application:
csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms;
public class ColorPickerForm : Form
{
private ColorUIControl colorUIControl1;
public ColorPickerForm()
{
InitializeComponent();
}
private void InitializeComponent()
{
// Create ColorUIControl instance
this.colorUIControl1 = new ColorUIControl();
// Set size
this.colorUIControl1.Size = new Size(210, 200);
this.colorUIControl1.Location = new Point(20, 20);
// Set initial color and group
this.colorUIControl1.SelectedColor = Color.OrangeRed;
this.colorUIControl1.SelectedColorGroup =
ColorUISelectedGroup.StandardColors;
// Handle color selection
this.colorUIControl1.ColorSelected += ColorUIControl1_ColorSelected;
// Add to form
this.Controls.Add(this.colorUIControl1);
// Form settings
this.Text = "Color Picker Example";
this.Size = new Size(300, 300);
}
private void ColorUIControl1_ColorSelected(object sender, EventArgs e)
{
Color selectedColor = this.colorUIControl1.SelectedColor;
MessageBox.Show($"Selected Color: {selectedColor.Name}");
}
}VB.NET:
vb
Imports System.Drawing
Imports System.Windows.Forms
Imports Syncfusion.Windows.Forms
Public Class ColorPickerForm
Inherits Form
Private colorUIControl1 As ColorUIControl
Public Sub New()
InitializeComponent()
End Sub
Private Sub InitializeComponent()
' Create ColorUIControl instance
Me.colorUIControl1 = New ColorUIControl()
' Set size
Me.colorUIControl1.Size = New Size(210, 200)
Me.colorUIControl1.Location = New Point(20, 20)
' Set initial color and group
Me.colorUIControl1.SelectedColor = Color.OrangeRed
Me.colorUIControl1.SelectedColorGroup = _
ColorUISelectedGroup.StandardColors
' Handle color selection
AddHandler Me.colorUIControl1.ColorSelected, _
AddressOf ColorUIControl1_ColorSelected
' Add to form
Me.Controls.Add(Me.colorUIControl1)
' Form settings
Me.Text = "Color Picker Example"
Me.Size = New Size(300, 300)
End Sub
Private Sub ColorUIControl1_ColorSelected(sender As Object, e As EventArgs)
Dim selectedColor As Color = Me.colorUIControl1.SelectedColor
MessageBox.Show($"Selected Color: {selectedColor.Name}")
End Sub
End Class以下是向Windows Forms应用添加ColorUIControl的最简示例:
csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms;
public class ColorPickerForm : Form
{
private ColorUIControl colorUIControl1;
public ColorPickerForm()
{
InitializeComponent();
}
private void InitializeComponent()
{
// Create ColorUIControl instance
this.colorUIControl1 = new ColorUIControl();
// Set size
this.colorUIControl1.Size = new Size(210, 200);
this.colorUIControl1.Location = new Point(20, 20);
// Set initial color and group
this.colorUIControl1.SelectedColor = Color.OrangeRed;
this.colorUIControl1.SelectedColorGroup =
ColorUISelectedGroup.StandardColors;
// Handle color selection
this.colorUIControl1.ColorSelected += ColorUIControl1_ColorSelected;
// Add to form
this.Controls.Add(this.colorUIControl1);
// Form settings
this.Text = "Color Picker Example";
this.Size = new Size(300, 300);
}
private void ColorUIControl1_ColorSelected(object sender, EventArgs e)
{
Color selectedColor = this.colorUIControl1.SelectedColor;
MessageBox.Show($"Selected Color: {selectedColor.Name}");
}
}VB.NET版本:
vb
Imports System.Drawing
Imports System.Windows.Forms
Imports Syncfusion.Windows.Forms
Public Class ColorPickerForm
Inherits Form
Private colorUIControl1 As ColorUIControl
Public Sub New()
InitializeComponent()
End Sub
Private Sub InitializeComponent()
' Create ColorUIControl instance
Me.colorUIControl1 = New ColorUIControl()
' Set size
Me.colorUIControl1.Size = New Size(210, 200)
Me.colorUIControl1.Location = New Point(20, 20)
' Set initial color and group
Me.colorUIControl1.SelectedColor = Color.OrangeRed
Me.colorUIControl1.SelectedColorGroup = _
ColorUISelectedGroup.StandardColors
' Handle color selection
AddHandler Me.colorUIControl1.ColorSelected, _
AddressOf ColorUIControl1_ColorSelected
' Add to form
Me.Controls.Add(Me.colorUIControl1)
' Form settings
Me.Text = "Color Picker Example"
Me.Size = New Size(300, 300)
End Sub
Private Sub ColorUIControl1_ColorSelected(sender As Object, e As EventArgs)
Dim selectedColor As Color = Me.colorUIControl1.SelectedColor
MessageBox.Show($"Selected Color: {selectedColor.Name}")
End Sub
End ClassCommon Patterns
常用实现模式
Pattern 1: Inline Color Picker with Specific Groups
模式1:仅展示指定分组的行内颜色拾取器
Show only Standard and Custom colors for a simplified picker:
csharp
// Display only Standard and Custom color groups
this.colorUIControl1.ColorGroups =
ColorUIGroups.StandardColors | ColorUIGroups.CustomColors;
// Enable panel stretching for better visual layout
this.colorUIControl1.CustomColorsStretchOnResize = true;
// Set border style
this.colorUIControl1.BorderStyle = BorderStyle.FixedSingle;仅展示标准和自定义颜色,简化拾取器样式:
csharp
// Display only Standard and Custom color groups
this.colorUIControl1.ColorGroups =
ColorUIGroups.StandardColors | ColorUIGroups.CustomColors;
// Enable panel stretching for better visual layout
this.colorUIControl1.CustomColorsStretchOnResize = true;
// Set border style
this.colorUIControl1.BorderStyle = BorderStyle.FixedSingle;Pattern 2: Custom Tab Names
模式2:自定义标签名称
Customize tab text for better context:
csharp
// Customize tab names
this.colorUIControl1.StandardTabName = "Web Colors";
this.colorUIControl1.SystemTabName = "System";
this.colorUIControl1.UserTabName = "My Colors";
this.colorUIControl1.CustomTabName = "Theme Palette";
// Customize font
this.colorUIControl1.Font = new Font("Segoe UI", 9F);自定义标签文本适配业务场景:
csharp
// Customize tab names
this.colorUIControl1.StandardTabName = "Web Colors";
this.colorUIControl1.SystemTabName = "System";
this.colorUIControl1.UserTabName = "My Colors";
this.colorUIControl1.CustomTabName = "Theme Palette";
// Customize font
this.colorUIControl1.Font = new Font("Segoe UI", 9F);Pattern 3: Popup Color Picker
模式3:弹出式颜色拾取器
Integrate ColorUIControl into a popup menu:
csharp
// Setup: Create PopupMenu, PopupControlContainer, and ColorUIControl
private PopupMenu popupMenu1;
private PopupControlContainer popupContainer1;
private ColorUIControl colorUIControl1;
private Panel colorButton;
private void InitializePopupColorPicker()
{
// Create and configure ColorUIControl
colorUIControl1 = new ColorUIControl();
colorUIControl1.Size = new Size(210, 200);
// Create PopupControlContainer and add ColorUI
popupContainer1 = new PopupControlContainer();
popupContainer1.Controls.Add(colorUIControl1);
// Create PopupMenu
popupMenu1 = new PopupMenu();
// Add DropDownBarItem to popup menu
var dropDownItem = new DropDownBarItem();
dropDownItem.PopupControlContainer = popupContainer1;
popupMenu1.ParentBarItem.Items.Add(dropDownItem);
// Handle panel click to show popup
colorButton.MouseUp += ColorButton_MouseUp;
// Close popup when color selected
colorUIControl1.ColorSelected += ColorUIControl1_ColorSelected;
}
private void ColorButton_MouseUp(object sender, MouseEventArgs e)
{
popupMenu1.Show(colorButton, new Point(e.X, e.Y));
}
private void ColorUIControl1_ColorSelected(object sender, EventArgs e)
{
// Update UI with selected color
colorButton.BackColor = colorUIControl1.SelectedColor;
// Close the popup
var cuiControl = sender as ColorUIControl;
var pcc = cuiControl.Parent as PopupControlContainer;
pcc.HidePopup(PopupCloseType.Done);
}将ColorUIControl集成到弹出菜单中:
csharp
// Setup: Create PopupMenu, PopupControlContainer, and ColorUIControl
private PopupMenu popupMenu1;
private PopupControlContainer popupContainer1;
private ColorUIControl colorUIControl1;
private Panel colorButton;
private void InitializePopupColorPicker()
{
// Create and configure ColorUIControl
colorUIControl1 = new ColorUIControl();
colorUIControl1.Size = new Size(210, 200);
// Create PopupControlContainer and add ColorUI
popupContainer1 = new PopupControlContainer();
popupContainer1.Controls.Add(colorUIControl1);
// Create PopupMenu
popupMenu1 = new PopupMenu();
// Add DropDownBarItem to popup menu
var dropDownItem = new DropDownBarItem();
dropDownItem.PopupControlContainer = popupContainer1;
popupMenu1.ParentBarItem.Items.Add(dropDownItem);
// Handle panel click to show popup
colorButton.MouseUp += ColorButton_MouseUp;
// Close popup when color selected
colorUIControl1.ColorSelected += ColorUIControl1_ColorSelected;
}
private void ColorButton_MouseUp(object sender, MouseEventArgs e)
{
popupMenu1.Show(colorButton, new Point(e.X, e.Y));
}
private void ColorUIControl1_ColorSelected(object sender, EventArgs e)
{
// Update UI with selected color
colorButton.BackColor = colorUIControl1.SelectedColor;
// Close the popup
var cuiControl = sender as ColorUIControl;
var pcc = cuiControl.Parent as PopupControlContainer;
pcc.HidePopup(PopupCloseType.Done);
}Pattern 4: Customizing User Color Palette
模式4:自定义用户调色板
Programmatically populate custom colors:
csharp
// Customize UserColors collection with blue gradient
for (int i = 0; i < colorUIControl1.UserColors.Count; i++)
{
colorUIControl1.UserColors[i] = Color.FromArgb(0, 0, i * 5);
}
// Customize UserCustomColors collection with red gradient
for (int i = 0; i < colorUIControl1.UserCustomColors.Count; i++)
{
colorUIControl1.UserCustomColors[i] = Color.FromArgb(i * 15, 0, 0);
}
// Make sure UserColors group is displayed
colorUIControl1.ColorGroups =
ColorUIGroups.StandardColors |
ColorUIGroups.CustomColors |
ColorUIGroups.UserColors;
// Select UserColors group by default
colorUIControl1.SelectedColorGroup = ColorUISelectedGroup.UserColors;
// Enable stretching
colorUIControl1.UserColorsStretchOnResize = true;通过代码填充自定义颜色:
csharp
// Customize UserColors collection with blue gradient
for (int i = 0; i < colorUIControl1.UserColors.Count; i++)
{
colorUIControl1.UserColors[i] = Color.FromArgb(0, 0, i * 5);
}
// Customize UserCustomColors collection with red gradient
for (int i = 0; i < colorUIControl1.UserCustomColors.Count; i++)
{
colorUIControl1.UserCustomColors[i] = Color.FromArgb(i * 15, 0, 0);
}
// Make sure UserColors group is displayed
colorUIControl1.ColorGroups =
ColorUIGroups.StandardColors |
ColorUIGroups.CustomColors |
ColorUIGroups.UserColors;
// Select UserColors group by default
colorUIControl1.SelectedColorGroup = ColorUISelectedGroup.UserColors;
// Enable stretching
colorUIControl1.UserColorsStretchOnResize = true;Key Properties
核心属性
Selection Properties
选择相关属性
- (Color): Gets or sets the currently selected color
SelectedColor - (ColorUISelectedGroup): Gets or sets which color group tab is active
SelectedColorGroup- Options: ,
SystemColors,StandardColors,CustomColors,UserColorsNone
- Options:
- (Color):获取或设置当前选中的颜色
SelectedColor - (ColorUISelectedGroup):获取或设置当前激活的颜色分组标签
SelectedColorGroup- 可选值:、
SystemColors、StandardColors、CustomColors、UserColorsNone
- 可选值:
Display Properties
展示相关属性
- (ColorUIGroups): Controls which color groups are visible (flags enum)
ColorGroups- Combine with:
ColorUIGroups.StandardColors | ColorUIGroups.CustomColors
- Combine with:
- (BorderStyle): Sets border appearance (
BorderStyle,FixedSingle,Fixed3D)None
- (ColorUIGroups):控制可见的颜色分组(标志枚举)
ColorGroups- 组合用法:
ColorUIGroups.StandardColors | ColorUIGroups.CustomColors
- 组合用法:
- (BorderStyle):设置边框外观(
BorderStyle、FixedSingle、Fixed3D)None
Customization Properties
自定义属性
- (bool): Enables stretching of Custom colors panel
CustomColorsStretchOnResize - (bool): Enables stretching of User colors panel
UserColorsStretchOnResize - (string): Custom text for Standard colors tab
StandardTabName - (string): Custom text for System colors tab
SystemTabName - (string): Custom text for Custom colors tab
CustomTabName - (string): Custom text for User colors tab
UserTabName - (Font): Font style for tab text
Font
- (bool):启用自定义颜色面板拉伸适配
CustomColorsStretchOnResize - (bool):启用用户颜色面板拉伸适配
UserColorsStretchOnResize - (string):标准颜色标签的自定义文本
StandardTabName - (string):系统颜色标签的自定义文本
SystemTabName - (string):自定义颜色标签的自定义文本
CustomTabName - (string):用户颜色标签的自定义文本
UserTabName - (Font):标签文本的字体样式
Font
Collection Properties
集合属性
- (ColorCollection): Collection of colors in the User colors group
UserColors - (ColorCollection): Additional custom colors in User group
UserCustomColors
- (ColorCollection):用户颜色分组中的颜色集合
UserColors - (ColorCollection):用户分组中的额外自定义颜色集合
UserCustomColors
Events
事件
- : Raised when a color is selected by the user
ColorSelected
- :用户选中颜色时触发
ColorSelected
Common Use Cases
常见使用场景
- Text Editor Color Selection: Add inline color picker for font colors, background colors, or highlighting
- Design Tools: Provide color palette for drawing applications or design tools
- Theme Configuration: Allow users to customize application themes with color selection
- Chart/Graph Customization: Let users select colors for data series in charts
- Form Control Styling: Enable runtime color customization for form controls
- Color Property Editors: Integrate into property grids for color-based settings
- Popup Color Pickers: Create ColorPickerButton-style dropdowns for toolbar buttons
- Custom Color Schemes: Allow users to define and save custom color palettes
- 文本编辑器颜色选择: 为字体颜色、背景色或高亮功能添加行内颜色拾取器
- 设计工具: 为绘图应用或设计工具提供调色板
- 主题配置: 支持用户自定义应用主题的颜色选择
- 图表自定义: 允许用户选择图表中数据系列的颜色
- 表单控件样式: 支持运行时自定义表单控件的颜色
- 颜色属性编辑器: 集成到属性网格中,用于颜色相关设置项
- 弹出式颜色拾取器: 为工具栏按钮实现ColorPickerButton风格的下拉控件
- 自定义配色方案: 允许用户定义并保存自定义调色板
Tips and Best Practices
提示与最佳实践
- Use SelectedColorGroup to automatically focus the appropriate color tab based on user context
- Enable panel stretching (,
CustomColorsStretchOnResize) for better visual layout in larger containersUserColorsStretchOnResize - Customize tab names to match your application's terminology (e.g., "Theme Colors", "Brand Colors")
- Handle ColorSelected event to close popups or update UI immediately when colors are chosen
- For dropdown functionality, consider using ColorPickerButton instead of manually creating popup infrastructure
- Limit visible groups using property to simplify the UI when users only need specific color types
ColorGroups - Programmatically set UserColors when you have a predefined color scheme or theme
- Reset methods (,
ResetSelectedColor()) are useful for "Clear" or "Default" buttonsResetSelectedColorGroup()
For ColorPickerButton dropdown functionality, refer to the Syncfusion documentation on using ColorUIControl as a drop-down control.
- 可以根据用户上下文使用自动聚焦到合适的颜色标签
SelectedColorGroup - 启用面板拉伸(、
CustomColorsStretchOnResize)可以在更大容器中获得更好的视觉效果UserColorsStretchOnResize - 自定义标签名称适配应用的术语体系(比如“主题色”、“品牌色”)
- 处理事件可以在选中颜色后立即关闭弹出框或更新UI
ColorSelected - 如需下拉功能,建议直接使用ColorPickerButton,无需手动搭建弹出层基础设施
- 当用户仅需要特定类型的颜色时,可以通过属性限制可见分组,简化UI
ColorGroups - 如果有预定义的配色方案或主题,可以通过代码提前设置
UserColors - 重置方法(、
ResetSelectedColor())非常适合用于“清除”或“恢复默认”按钮ResetSelectedColorGroup()
如需了解ColorPickerButton下拉功能,请参考Syncfusion官方文档中关于将ColorUIControl用作下拉控件的说明。