syncfusion-winforms-group-view
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing GroupView Control
实现GroupView控件
The GroupView control is a list-type control for Windows Forms that displays items with text and images. It provides rich customization options for appearance, behavior, and interactive features, making it ideal for creating VS.NET toolbox-style interfaces, OutlookBar clones, and navigation panels.
GroupView控件是适用于Windows Forms的列表类型控件,可展示带文本和图片的项。它提供了丰富的外观、行为和交互功能自定义选项,非常适合创建VS.NET工具箱风格界面、OutlookBar复刻版以及导航面板。
When to Use This Skill
何时使用本技能
Use this skill when you need to:
- Display a list of items with text and images in Windows Forms
- Create VS.NET toolbox-style interfaces
- Clone Microsoft OutlookBar or Visual Studio toolbox window
- Implement drag-and-drop item lists
- Build navigation panels with highlighted selections
- Add GroupView as a client control to GroupBar
- Configure item appearance, colors, and offsets
- Handle item selection, highlighting, and renaming events
- Create interactive item lists with tooltips and context menus
当你需要完成以下场景时可使用本技能:
- 在Windows Forms中展示带文本和图片的项列表
- 创建VS.NET工具箱风格的界面
- 复刻Microsoft OutlookBar或Visual Studio工具箱窗口
- 实现支持拖拽的项列表
- 构建带高亮选中效果的导航面板
- 将GroupView作为客户端控件添加到GroupBar中
- 配置项的外观、颜色和间距
- 处理项选中、高亮和重命名事件
- 创建带工具提示和右键菜单的交互项列表
Component Overview
组件概述
GroupView Control displays a collection of GroupViewItems, each supporting:
- Text labels with formatting and highlighting
- Small and large images from ImageList
- Interactive states (selected, highlighted, selecting)
- Drag-and-drop reordering
- In-place renaming
- ToolTips and context menus
- Custom colors and offsets for various states
- Horizontal and vertical orientation
Key Capabilities:
- Flat or 3D appearance
- ButtonView for pressed state visualization
- FlowView for image-focused layouts
- Integrated scrolling for large item sets
- Event notifications for selection, highlighting, renaming, and reordering
GroupView控件用于展示GroupViewItem集合,每个项支持以下特性:
- 支持格式化和高亮的文本标签
- 来自ImageList的小尺寸和大尺寸图片
- 多种交互状态(选中、高亮、选中中)
- 拖拽重排序
- 就地重命名
- 工具提示和右键菜单
- 适配不同状态的自定义颜色和间距
- 水平和垂直布局方向
核心能力:
- 平面或3D外观
- ButtonView模式支持按下状态可视化
- FlowView模式适配图片优先的布局
- 针对大量项的集成滚动功能
- 选中、高亮、重命名、重排序相关的事件通知
Documentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- Assembly deployment (Syncfusion.Shared.Base)
- Adding GroupView via designer
- Adding GroupView via code
- Adding items to GroupViewItems collection
- Setting up ImageList for small and large images
- Configuring selected item
📄 阅读: references/getting-started.md
- 程序集部署(Syncfusion.Shared.Base)
- 通过设计器添加GroupView
- 通过代码添加GroupView
- 向GroupViewItems集合添加项
- 配置存放小图和大图的ImageList
- 配置默认选中项
Control Configuration
控件配置
📄 Read: references/control-settings.md
- Appearance settings (FlatLook, BorderStyle)
- Drag-and-drop behavior
- Spacing between items and borders
- Integrated scrolling
- Orientation and FlowView modes
📄 阅读: references/control-settings.md
- 外观设置(FlatLook、BorderStyle)
- 拖拽行为配置
- 项与边框的间距设置
- 集成滚动功能
- 布局方向与FlowView模式
Item Customization
项自定义
📄 Read: references/item-customization.md
- Text highlighting, offset, and formatting
- Color settings for items and text (highlight, selection states)
- Image highlighting, offset, and spacing
- In-place renaming functionality
📄 阅读: references/item-customization.md
- 文本高亮、间距和格式化
- 项和文本的颜色设置(高亮、选中状态)
- 图片高亮、间距和边距
- 就地重命名功能
Interactive Features
交互功能
📄 Read: references/interactive-features.md
- ButtonView and ClipSelectionBounds
- ToolTips configuration
- Context menu implementation
- Selection behavior
📄 阅读: references/interactive-features.md
- ButtonView与ClipSelectionBounds
- 工具提示配置
- 右键菜单实现
- 选中行为配置
Events
事件
📄 Read: references/events.md
- GroupViewItemSelected event
- GroupViewItemHighlighted event
- GroupViewItemRenamed event
- GroupViewItemsReordered event
- GroupViewItemDoubleClick event
- ShowContextMenu event
📄 阅读: references/events.md
- GroupViewItemSelected事件
- GroupViewItemHighlighted事件
- GroupViewItemRenamed事件
- GroupViewItemsReordered事件
- GroupViewItemDoubleClick事件
- ShowContextMenu事件
GroupBar Integration
GroupBar集成
📄 Read: references/groupbar-integration.md
- Adding GroupView to GroupBar
- Creating VS.NET toolbox interface
- Client control attachment
📄 阅读: references/groupbar-integration.md
- 向GroupBar添加GroupView
- 创建VS.NET工具箱界面
- 客户端控件挂载
Quick Start
快速开始
Basic GroupView Setup
基础GroupView设置
csharp
using Syncfusion.Windows.Forms.Tools;
public class MyForm : Form
{
private GroupView groupView1;
private ImageList imageList1;
public MyForm()
{
InitializeComponent();
// Create GroupView
this.groupView1 = new GroupView();
this.groupView1.Location = new Point(10, 10);
this.groupView1.Size = new Size(200, 300);
this.groupView1.FlatLook = true;
// Setup ImageList
this.imageList1 = new ImageList();
this.imageList1.Images.Add(Image.FromFile("icon1.png"));
this.imageList1.Images.Add(Image.FromFile("icon2.png"));
this.imageList1.Images.Add(Image.FromFile("icon3.png"));
// Assign ImageList
this.groupView1.SmallImageList = this.imageList1;
this.groupView1.SmallImageView = true;
// Add items
this.groupView1.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("My Computer", 0, true, null, "Item0"),
new GroupViewItem("Network", 1, true, null, "Item1"),
new GroupViewItem("Recycle Bin", 2, true, null, "Item2")
});
// Handle selection event
this.groupView1.GroupViewItemSelected += GroupView1_ItemSelected;
// Add to form
this.Controls.Add(this.groupView1);
}
private void GroupView1_ItemSelected(object sender, EventArgs e)
{
int selectedIndex = this.groupView1.SelectedItem;
string selectedText = this.groupView1.GroupViewItems[selectedIndex].Text;
MessageBox.Show($"Selected: {selectedText}");
}
}csharp
using Syncfusion.Windows.Forms.Tools;
public class MyForm : Form
{
private GroupView groupView1;
private ImageList imageList1;
public MyForm()
{
InitializeComponent();
// Create GroupView
this.groupView1 = new GroupView();
this.groupView1.Location = new Point(10, 10);
this.groupView1.Size = new Size(200, 300);
this.groupView1.FlatLook = true;
// Setup ImageList
this.imageList1 = new ImageList();
this.imageList1.Images.Add(Image.FromFile("icon1.png"));
this.imageList1.Images.Add(Image.FromFile("icon2.png"));
this.imageList1.Images.Add(Image.FromFile("icon3.png"));
// Assign ImageList
this.groupView1.SmallImageList = this.imageList1;
this.groupView1.SmallImageView = true;
// Add items
this.groupView1.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("My Computer", 0, true, null, "Item0"),
new GroupViewItem("Network", 1, true, null, "Item1"),
new GroupViewItem("Recycle Bin", 2, true, null, "Item2")
});
// Handle selection event
this.groupView1.GroupViewItemSelected += GroupView1_ItemSelected;
// Add to form
this.Controls.Add(this.groupView1);
}
private void GroupView1_ItemSelected(object sender, EventArgs e)
{
int selectedIndex = this.groupView1.SelectedItem;
string selectedText = this.groupView1.GroupViewItems[selectedIndex].Text;
MessageBox.Show($"Selected: {selectedText}");
}
}VS.NET Toolbox-Style Interface
VS.NET工具箱风格界面
csharp
// Create toolbox-style GroupView
this.groupView1.FlatLook = true;
this.groupView1.FlowView = true;
this.groupView1.ShowFlowViewItemText = true;
this.groupView1.IntegratedScrolling = true;
this.groupView1.SmallImageView = true;
this.groupView1.AllowDragDrop = true;
// Configure highlighting
this.groupView1.HighlightText = true;
this.groupView1.HighlightImage = true;
this.groupView1.HighlightItemColor = Color.LightBlue;
this.groupView1.HighlightTextColor = Color.DarkBlue;csharp
// Create toolbox-style GroupView
this.groupView1.FlatLook = true;
this.groupView1.FlowView = true;
this.groupView1.ShowFlowViewItemText = true;
this.groupView1.IntegratedScrolling = true;
this.groupView1.SmallImageView = true;
this.groupView1.AllowDragDrop = true;
// Configure highlighting
this.groupView1.HighlightText = true;
this.groupView1.HighlightImage = true;
this.groupView1.HighlightItemColor = Color.LightBlue;
this.groupView1.HighlightTextColor = Color.DarkBlue;Common Patterns
通用模式
Pattern 1: Adding Items Dynamically
模式1:动态添加项
csharp
// Add single item
GroupViewItem newItem = new GroupViewItem(
text: "New Item",
imageIndex: 3,
visible: true,
toolTipText: null,
name: "NewItem1"
);
this.groupView1.GroupViewItems.Add(newItem);
// Add multiple items
this.groupView1.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("Item 1", 0, true, null, "Item1"),
new GroupViewItem("Item 2", 1, true, null, "Item2"),
new GroupViewItem("Item 3", 2, true, null, "Item3")
});csharp
// Add single item
GroupViewItem newItem = new GroupViewItem(
text: "New Item",
imageIndex: 3,
visible: true,
toolTipText: null,
name: "NewItem1"
);
this.groupView1.GroupViewItems.Add(newItem);
// Add multiple items
this.groupView1.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("Item 1", 0, true, null, "Item1"),
new GroupViewItem("Item 2", 1, true, null, "Item2"),
new GroupViewItem("Item 3", 2, true, null, "Item3")
});Pattern 2: Configuring Highlighting and Selection
模式2:配置高亮与选中效果
csharp
// Enable highlighting
this.groupView1.HighlightText = true;
this.groupView1.HighlightImage = true;
// Set highlight colors
this.groupView1.HighlightItemColor = Color.LightGray;
this.groupView1.HighlightTextColor = Color.Black;
// Set selection colors
this.groupView1.SelectedItemColor = Color.Navy;
this.groupView1.SelectedTextColor = Color.White;
this.groupView1.SelectedHighlightItemColor = Color.Blue;
this.groupView1.SelectedHighlightTextColor = Color.Yellow;csharp
// Enable highlighting
this.groupView1.HighlightText = true;
this.groupView1.HighlightImage = true;
// Set highlight colors
this.groupView1.HighlightItemColor = Color.LightGray;
this.groupView1.HighlightTextColor = Color.Black;
// Set selection colors
this.groupView1.SelectedItemColor = Color.Navy;
this.groupView1.SelectedTextColor = Color.White;
this.groupView1.SelectedHighlightItemColor = Color.Blue;
this.groupView1.SelectedHighlightTextColor = Color.Yellow;Pattern 3: Drag-and-Drop Configuration
模式3:拖拽配置
csharp
// Enable drag-and-drop
this.groupView1.AllowDragDrop = true;
this.groupView1.AllowDragAnyObject = true;
// Handle reorder event
this.groupView1.GroupViewItemsReordered += (sender, e) => {
// Items have been reordered
UpdateItemPositions();
};csharp
// Enable drag-and-drop
this.groupView1.AllowDragDrop = true;
this.groupView1.AllowDragAnyObject = true;
// Handle reorder event
this.groupView1.GroupViewItemsReordered += (sender, e) => {
// Items have been reordered
UpdateItemPositions();
};Pattern 4: In-Place Renaming
模式4:就地重命名
csharp
// Enable in-place renaming for specific item
int itemIndexToRename = 2;
this.groupView1.InplaceRenameItem(itemIndexToRename);
// Handle rename event
this.groupView1.GroupViewItemRenamed += (sender, e) => {
GroupItemRenamedEventArgs args = (GroupItemRenamedEventArgs)e;
MessageBox.Show($"Renamed from '{args.OldLabel}' to '{args.NewLabel}'");
};csharp
// Enable in-place renaming for specific item
int itemIndexToRename = 2;
this.groupView1.InplaceRenameItem(itemIndexToRename);
// Handle rename event
this.groupView1.GroupViewItemRenamed += (sender, e) => {
GroupItemRenamedEventArgs args = (GroupItemRenamedEventArgs)e;
MessageBox.Show($"Renamed from '{args.OldLabel}' to '{args.NewLabel}'");
};Pattern 5: Context Menu Implementation
模式5:右键菜单实现
csharp
// Handle ShowContextMenu event
this.groupView1.ShowContextMenu += GroupView1_ShowContextMenu;
private void GroupView1_ShowContextMenu(object sender, EventArgs e)
{
ContextMenuStrip menu = new ContextMenuStrip();
// Add menu items
menu.Items.Add("Add New Item", null, AddNewItem_Click);
menu.Items.Add("Remove Item", null, RemoveItem_Click);
menu.Items.Add(new ToolStripSeparator());
menu.Items.Add("Properties", null, Properties_Click);
// Check if mouse is over an item
if (this.groupView1.ContextMenuItem != -1)
{
menu.Items[1].Enabled = true; // Enable Remove
}
else
{
menu.Items[1].Enabled = false; // Disable Remove
}
// Show context menu
menu.Show(this.groupView1, this.groupView1.PointToClient(Cursor.Position));
}csharp
// Handle ShowContextMenu event
this.groupView1.ShowContextMenu += GroupView1_ShowContextMenu;
private void GroupView1_ShowContextMenu(object sender, EventArgs e)
{
ContextMenuStrip menu = new ContextMenuStrip();
// Add menu items
menu.Items.Add("Add New Item", null, AddNewItem_Click);
menu.Items.Add("Remove Item", null, RemoveItem_Click);
menu.Items.Add(new ToolStripSeparator());
menu.Items.Add("Properties", null, Properties_Click);
// Check if mouse is over an item
if (this.groupView1.ContextMenuItem != -1)
{
menu.Items[1].Enabled = true; // Enable Remove
}
else
{
menu.Items[1].Enabled = false; // Disable Remove
}
// Show context menu
menu.Show(this.groupView1, this.groupView1.PointToClient(Cursor.Position));
}Key Properties
核心属性
Core Properties
基础属性
- GroupViewItems - Collection of items displayed in the control
- SelectedItem - Index of currently selected item
- HighlightedItem - Index of currently highlighted item
- ContextMenuItem - Index of item under mouse for context menu
- GroupViewItems - 控件中展示的项集合
- SelectedItem - 当前选中项的索引
- HighlightedItem - 当前高亮项的索引
- ContextMenuItem - 鼠标右键点击时指向的项索引
Appearance Properties
外观属性
- FlatLook - Removes 3D edge from items
- BorderStyle - Border style for the control
- SmallImageView - Display items with small images
- FlowView - Display items in flow layout mode
- FlatLook - 移除项的3D边缘效果
- BorderStyle - 控件的边框样式
- SmallImageView - 用小图展示项
- FlowView - 用流式布局展示项
Behavior Properties
行为属性
- AllowDragDrop - Enable drag-and-drop functionality
- IntegratedScrolling - Enable scrolling for overflow
- Orientation - Horizontal or Vertical item arrangement
- ButtonView - Display selected item in pressed state
- AllowDragDrop - 启用拖拽功能
- IntegratedScrolling - 内容溢出时启用滚动
- Orientation - 项的水平/垂直排列方向
- ButtonView - 选中项展示为按下状态
Image Properties
图片属性
- SmallImageList - ImageList for small icons (16x16)
- LargeImageList - ImageList for large icons (32x32)
- HighlightImage - Enable image highlighting on hover
- ImageSpacing - Spacing between image edge and item edge
- SmallImageList - 存放小图标(16x16)的ImageList
- LargeImageList - 存放大图标(32x32)的ImageList
- HighlightImage - 鼠标悬停时启用图片高亮
- ImageSpacing - 图片边缘与项边缘的间距
Text Properties
文本属性
- HighlightText - Enable text highlighting on hover
- TextWrap - Wrap long text
- TextUnderline - Underline item text
- TextSpacing - Spacing between text and other elements
- HighlightText - 鼠标悬停时启用文本高亮
- TextWrap - 长文本自动换行
- TextUnderline - 项文本添加下划线
- TextSpacing - 文本与其他元素的间距
Color Properties
颜色属性
- HighlightItemColor - Color when mouse hovers over item
- HighlightTextColor - Text color when mouse hovers
- SelectedItemColor - Background color of selected item
- SelectedTextColor - Text color of selected item
- HighlightItemColor - 鼠标悬停时的项背景色
- HighlightTextColor - 鼠标悬停时的文本颜色
- SelectedItemColor - 选中项的背景色
- SelectedTextColor - 选中项的文本颜色
Common Use Cases
常见用例
Use Case 1: Navigation Panel
用例1:导航面板
Display application sections with icons and text, allowing users to navigate by clicking items.
展示带图标和文本的应用功能模块,用户点击项即可完成跳转。
Use Case 2: Tool Palette
用例2:工具面板
Create a VS.NET toolbox-style palette where users can select tools or components from categorized lists.
创建VS.NET工具箱风格的面板,用户可从分类列表中选择工具或组件。
Use Case 3: File Browser
用例3:文件浏览器
Build a file/folder browser with icons representing different file types and support for drag-and-drop operations.
构建文件/文件夹浏览器,用不同图标代表不同文件类型,支持拖拽操作。
Use Case 4: Settings Menu
用例4:设置菜单
Display hierarchical settings categories with icons, enabling quick access to configuration options.
展示带图标的层级设置分类,支持快速访问配置选项。
Use Case 5: Dashboard Widgets
用例5:仪表盘组件面板
Present dashboard widget options that users can select and drag onto a canvas.
展示可选的仪表盘组件,用户可选中后拖拽到画布上使用。
Troubleshooting
故障排查
Issue: Images not displaying
- Verify ImageList is assigned to SmallImageList or LargeImageList
- Ensure SmallImageView is set to true for small images
- Check that GroupViewItem.ImageIndex matches valid index in ImageList
Issue: Events not firing
- Verify event handlers are properly subscribed
- Check that control is added to form's Controls collection
- Ensure items exist in GroupViewItems collection
Issue: Drag-and-drop not working
- Set AllowDragDrop to true
- Consider AllowDragAnyObject for external objects
- Verify form allows drop operations if dragging from external source
Issue: Selection not visible
- Configure SelectedItemColor and SelectedTextColor
- Set ButtonView to true for pressed state visualization
- Check ClipSelectionBounds property for selection borders
问题: 图片不展示
- 确认ImageList已经赋值给SmallImageList或LargeImageList
- 确保小图模式下SmallImageView设置为true
- 检查GroupViewItem.ImageIndex对应ImageList中的有效索引
问题: 事件不触发
- 确认事件处理程序已正确订阅
- 检查控件已添加到窗体的Controls集合中
- 确保GroupViewItems集合中存在有效项
问题: 拖拽功能不生效
- 将AllowDragDrop设置为true
- 如果需要拖拽外部对象可开启AllowDragAnyObject
- 如果从外部源拖拽,确认窗体允许放置操作
问题: 选中效果不可见
- 配置SelectedItemColor和SelectedTextColor属性
- 开启ButtonView以展示按下状态效果
- 检查ClipSelectionBounds属性配置选中边框