syncfusion-winforms-group-view

GroupView コントロールの実装

GroupView コントロールは、テキストと画像を表示する Windows Forms 用のリスト型コントロールです。外観、動作、インタラクティブ機能を柔軟にカスタマイズできるため、VS.NET ツールボックス風のインターフェイス、OutlookBar のクローン、ナビゲーションパネルの作成に最適です。

このスキルを使用する場面

以下が必要な場合に、このスキルを使用してください。

• Windows Forms でテキストと画像を含む項目のリストを表示する
• VS.NET ツールボックス風のインターフェイスを作成する
• Microsoft OutlookBar または Visual Studio ツールボックスウィンドウのクローンを作成する
• ドラッグ＆ドロップに対応した項目リストを実装する
• 選択項目を強調表示するナビゲーションパネルを構築する
• GroupView を GroupBar のクライアントコントロールとして追加する
• 項目の外観、色、オフセットを設定する
• 項目の選択、強調表示、名前変更のイベントを処理する
• ツールチップとコンテキストメニューを備えたインタラクティブな項目リストを作成する

コンポーネントの概要

GroupView コントロールには GroupViewItems のコレクションが表示されます。各項目は以下に対応しています。

• 書式設定や強調表示が可能なテキストラベル
• ImageList の小さい画像と大きい画像
• インタラクティブな状態（選択済み、強調表示、選択中）
• ドラッグ＆ドロップによる並べ替え
• インプレースでの名前変更
• ツールチップとコンテキストメニュー
• さまざまな状態に応じたカスタムの色とオフセット
• 水平および垂直方向の表示

主な機能：

• フラットまたは 3D の外観
• 押下状態を視覚的に表示する ButtonView
• 画像を中心にしたレイアウトを実現する FlowView
• 多数の項目に対応したスクロール機能
• 選択、強調表示、名前変更、並べ替えに関するイベント通知

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• アセンブリの配置（Syncfusion.Shared.Base）
• デザイナーからの GroupView の追加
• コードからの GroupView の追加
• GroupViewItems コレクションへの項目の追加
• 小さい画像と大きい画像用の ImageList の設定
• 選択項目の設定

コントロールの設定

📄 参照： references/control-settings.md

• 外観の設定（FlatLook、BorderStyle）
• ドラッグ＆ドロップの動作
• 項目間および境界線との間隔
• スクロール機能
• 方向と FlowView モード

項目のカスタマイズ

📄 参照： references/item-customization.md

• テキストの強調表示、オフセット、書式設定
• 項目とテキストの色設定（強調表示、選択状態）
• 画像の強調表示、オフセット、間隔
• インプレースでの名前変更機能

インタラクティブ機能

📄 参照： references/interactive-features.md

• ButtonView と ClipSelectionBounds
• ツールチップの設定
• コンテキストメニューの実装
• 選択時の動作

イベント

📄 参照： references/events.md

• GroupViewItemSelected イベント
• GroupViewItemHighlighted イベント
• GroupViewItemRenamed イベント
• GroupViewItemsReordered イベント
• GroupViewItemDoubleClick イベント
• ShowContextMenu イベント

GroupBar との連携

📄 参照： references/groupbar-integration.md

• GroupView の GroupBar への追加
• VS.NET ツールボックス風インターフェイスの作成
• クライアントコントロールのアタッチ

クイックスタート

基本的な GroupView の設定

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 ツールボックス風インターフェイス

// 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;

よくあるパターン

パターン 1：項目を動的に追加する

// 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")
});

パターン 2：強調表示と選択を設定する

// 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;

パターン 3：ドラッグ＆ドロップを設定する

// 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();
};

パターン 4：インプレースで名前を変更する

// 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}'");
};

パターン 5：コンテキストメニューを実装する

// 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));
}

主なプロパティ

基本プロパティ

• GroupViewItems - コントロールに表示される項目のコレクション
• SelectedItem - 現在選択されている項目のインデックス
• HighlightedItem - 現在強調表示されている項目のインデックス
• ContextMenuItem - コンテキストメニューを表示する際にマウスの下にある項目のインデックス

外観のプロパティ

• FlatLook - アイテムの3Dエッジを取り除きます
• BorderStyle - コントロールの境界線のスタイルです
• SmallImageView - 小さな画像とともにアイテムを表示します
• FlowView - アイテムをフローレイアウトモードで表示します

動作のプロパティ

• AllowDragDrop - ドラッグ＆ドロップ機能を有効にします
• IntegratedScrolling - オーバーフロー時のスクロールを有効にします
• Orientation - アイテムの配置を水平または垂直に設定します
• ButtonView - 選択したアイテムを押された状態で表示します

画像のプロパティ

• SmallImageList - 小さなアイコン（16x16）用のImageListです
• LargeImageList - 大きなアイコン（32x32）用のImageListです
• HighlightImage - ホバー時の画像の強調表示を有効にします
• ImageSpacing - 画像の端とアイテムの端の間隔です

テキストのプロパティ

• HighlightText - ホバー時のテキストの強調表示を有効にします
• TextWrap - 長いテキストを折り返します
• TextUnderline - アイテムのテキストに下線を引きます
• TextSpacing - テキストとほかの要素との間隔です

色のプロパティ

• HighlightItemColor - マウスをアイテムに重ねたときの色です
• HighlightTextColor - マウスを重ねたときのテキストの色です
• SelectedItemColor - 選択したアイテムの背景色です
• SelectedTextColor - 選択したアイテムのテキストの色です

一般的な使用例

使用例 1：ナビゲーションパネル

アイコンとテキストを使ってアプリケーションの各セクションを表示し、アイテムをクリックして移動できるようにします。

使用例 2：ツールパレット

VS.NETのツールボックス風のパレットを作成し、分類されたリストからツールやコンポーネントを選択できるようにします。

使用例 3：ファイルブラウザー

さまざまなファイルの種類を表すアイコンを備え、ドラッグ＆ドロップ操作に対応したファイル／フォルダーのブラウザーを作成します。

使用例 4：設定メニュー

階層化された設定カテゴリをアイコン付きで表示し、設定オプションにすばやくアクセスできるようにします。

使用例 5：ダッシュボードウィジェット

ダッシュボードのウィジェットオプションを表示し、キャンバスに選択してドラッグできるようにします。

トラブルシューティング

問題： 画像が表示されない

• ImageListがSmallImageListまたはLargeImageListに割り当てられていることを確認します
• 小さな画像を使用する場合は、SmallImageViewがtrueに設定されていることを確認します
• GroupViewItem.ImageIndexがImageList内の有効なインデックスと一致していることを確認します

問題： イベントが発生しない

• イベントハンドラーが正しく登録されていることを確認します
• コントロールがフォームのControlsコレクションに追加されていることを確認します
• GroupViewItemsコレクションにアイテムが存在することを確認します

問題： ドラッグ＆ドロップが機能しない

• AllowDragDropをtrueに設定します
• 外部オブジェクトの場合はAllowDragAnyObjectを検討します
• 外部ソースからドラッグする場合、フォームでドロップ操作が許可されていることを確認します

問題： 選択状態が表示されない

• SelectedItemColorとSelectedTextColorを設定します
• 押された状態を視覚的に表示するには、ButtonViewをtrueに設定します
• 選択範囲の境界線について、ClipSelectionBoundsプロパティを確認します