syncfusion-winforms-color-ui-control

ColorUIControl の実装

このスキルを使用するタイミング

Syncfusion の ColorUIControl を使用して Windows Forms アプリケーションに色選択機能を実装する必要がある場合は、このスキルを使用してください。次のような場合に役立ちます。

• Windows Forms アプリケーションにカラーピッカー UI を追加する必要がある
• Visual Studio のような色選択インターフェイスを提供したい
• インラインの色選択コントロールが必要である（ダイアログだけではない）
• 定義済みの色グループを使って、カスタマイズ可能なカラーパレットが必要である
• ポップアップメニューやドロップダウンにカラーピッカーを統合したい
• System、Standard、Custom、User-defined の色を使った色選択を実装する必要がある
• .NET Framework の Windows Forms アプリケーションを開発している
• ColorPickerButton のドロップダウン機能を提供したい

ColorUIControl は、Visual Studio のカラーピッカーに似たパレット形式のインターフェイスを提供し、4 つの色グループ（SystemColors、StandardColors、CustomColors、UserColors）をアプリケーション内にインライン表示したり、ドロップダウンとして表示したりできます。

コンポーネントの概要

ColorUIControl は、定義済みのカラーパレットを備えた色選択インターフェイスを提供する Windows Forms コントロールです。モーダルダイアログとして表示される標準の ColorDialog とは異なり、ColorUIControl はアプリケーションのレイアウト内にインラインで配置したり、ドロップダウンコントロールとして使用したりできます。

主な機能：

• 4 つの定義済み色グループ（System、Standard、Custom、User）
• アプリケーションのレイアウト内へのインライン配置
• PopupControlContainer によるポップアップ／ドロップダウンとの統合
• カラーパレットとタブ名のカスタマイズ
• Visual Studio のようなカラーピッカーインターフェイス
• プログラムによる色選択と対話的な色選択
• 境界線スタイルのカスタマイズとパネルの伸縮

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

はじめに

📄 参照： references/getting-started.md

次のような場合に参照してください。

• ColorUIControl コンポーネントをインストールしてセットアップする
• デザイナーまたはコードから ColorUIControl を追加する
• アセンブリの依存関係（Syncfusion.Shared.Base）を確認する
• C# または VB.NET でコントロールを初期化する
• 初期選択色と色グループを設定する
• 必要な名前空間（Syncfusion.Windows.Forms）をインポートする

色グループと選択

📄 参照： references/color-groups.md

次のような場合に参照してください。

• 4 つの色グループ（System、Standard、Custom、User）を理解する
• 表示する色グループを制御する
• プログラムで既定の色グループを選択する
• UserColors および UserCustomColors コレクションをカスタマイズする
• 色グループを追加または削除する
• カスタム色セルにプログラムで色を設定する

外観とカスタマイズ

📄 参照： references/appearance-customization.md

次のような場合に参照してください。

• 境界線スタイル（FixedSingle、Fixed3D、None）を設定する
• Custom および User の色グループでパネルの伸縮を有効にする
• 各色グループのタブテキストをカスタマイズする
• タブテキストのフォントスタイルを変更する
• タブ名を既定値にリセットする
• コントロールの外観を調整する

イベントと操作

📄 参照： references/events.md

次のような場合に参照してください。

• ColorSelected イベントを処理する
• 色が選択されたときにポップアップを閉じる
• イベントハンドラーから選択色にアクセスする
• イベント内で PopupControlContainer を使用する
• 色選択のコールバックを実装する

高度なシナリオ

📄 参照： references/popup-integration.md

次のような場合に参照してください。

• ColorUIControl をポップアップメニューに追加する
• PopupMenu および PopupControlContainer と統合する
• カラーピッカー用に DropDownBarItem を設定する
• マウスクリックでカラーピッカーを表示する
• ドロップダウン機能に ColorPickerButton を使用する
• ポップアップでの色選択ワークフローを一通り作成する

クイックスタートの例

Windows Forms アプリケーションに ColorUIControl を追加する最小限の例を示します。

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：

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

よくあるパターン

パターン 1：特定のグループを使ったインラインカラーピッカー

簡易的なピッカーとして、Standard 色と Custom 色のみを表示します。

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

パターン 2：カスタムタブ名

コンテキストをより分かりやすくするために、タブのテキストをカスタマイズします。

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

パターン 3：ポップアップカラーピッカー

ColorUIControl をポップアップメニューに組み込みます。

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

パターン 4：ユーザーカラーパレットのカスタマイズ

カスタムカラーをプログラムから設定します。

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

主なプロパティ

選択プロパティ

• SelectedColor（Color）：現在選択されている色を取得または設定します
• SelectedColorGroup（ColorUISelectedGroup）：アクティブなカラーグループのタブを取得または設定します
  • 選択肢：SystemColors、StandardColors、CustomColors、UserColors、None

表示プロパティ

• ColorGroups（ColorUIGroups）：表示するカラーグループを制御します（フラグ列挙型）
  • 次のように組み合わせます：ColorUIGroups.StandardColors | ColorUIGroups.CustomColors
• BorderStyle（BorderStyle）：境界線の外観を設定します（FixedSingle、Fixed3D、None）

カスタマイズプロパティ

• CustomColorsStretchOnResize（bool）：カスタムカラーのパネルの伸縮を有効にします
• UserColorsStretchOnResize（bool）：ユーザーカラーのパネルの伸縮を有効にします
• StandardTabName（string）：標準カラータブのカスタムテキスト
• SystemTabName（string）：システムカラータブのカスタムテキスト
• CustomTabName（string）：カスタムカラータブのカスタムテキスト
• UserTabName（string）：ユーザーカラータブのカスタムテキスト
• Font（Font）：タブのテキストに使用するフォントスタイル

コレクションプロパティ

• UserColors（ColorCollection）：ユーザーカラーグループの色のコレクション
• UserCustomColors（ColorCollection）：ユーザーグループの追加カスタムカラー

イベント

• ColorSelected：ユーザーが色を選択したときに発生します

よくある使用例

1. テキストエディターでの色選択： フォントカラー、背景色、またはハイライト用のインラインカラーピッカーを追加します
2. デザインツール： 描画アプリケーションやデザインツールにカラーパレットを用意します
3. テーマの設定： 色を選択してアプリケーションのテーマをカスタマイズできるようにします
4. チャート／グラフのカスタマイズ： チャート内のデータ系列の色を選択できるようにします
5. フォームコントロールのスタイル設定： フォームコントロールの色を実行時にカスタマイズできるようにします
6. 色プロパティエディター： 色に基づく設定用にプロパティグリッドへ組み込みます
7. ポップアップカラーピッカー： ツールバーボタン用に ColorPickerButton のようなドロップダウンを作成します
8. カスタム配色： カスタムカラーパレットを定義して保存できるようにします

ヒントとベストプラクティス

• SelectedColorGroup を使用すると、ユーザーのコンテキストに基づいて適切なカラータブに自動的に切り替えられます
• より大きなコンテナーで見やすく配置できるよう、パネルの伸縮（CustomColorsStretchOnResize、UserColorsStretchOnResize）を有効にします
• アプリケーションの用語に合わせてタブ名をカスタマイズします（例：「テーマカラー」、「ブランドカラー」）
• ColorSelected イベントを処理すると、色の選択時にポップアップを閉じたり、UI をすぐに更新したりできます
• **ドロップダウン機能には、**ポップアップの仕組みを手動で作成する代わりに ColorPickerButton の使用を検討してください
• 特定の色タイプだけが必要な場合は、ColorGroups プロパティを使って表示するグループを絞り込み、UI を簡潔にします
• 定義済みの配色やテーマがある場合は、プログラムから UserColors を設定します
• 「クリア」または「デフォルト」ボタンには、リセットメソッド（ResetSelectedColor()、ResetSelectedColorGroup()）が便利です

ColorPickerButton のドロップダウン機能については、ColorUIControl をドロップダウンコントロールとして使用する方法に関する Syncfusion のドキュメントを参照してください。