syncfusion-winforms-group-view

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing 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属性配置选中边框