syncfusion-winforms-color-picker

Color Picker (ColorPickerUIAdv) の実装

Windows Forms アプリケーションで Syncfusion ColorPickerUIAdv コントロールを実装するためのガイドです。

概要

ColorPickerUIAdv コントロールは、Windows Forms アプリケーション向けに Microsoft Word 2007 スタイルの色選択インターフェイスを提供します。整理された色グループ（最近使用した色、標準色、テーマ色）、カスタマイズ可能なカラーパレット、複数のビジュアルスタイル、さらに高度な色選択用のオプションの「その他の色」ダイアログを利用できます。

主な機能：

• 色グループ： 最近使用した色、標準色、テーマ色
• カスタムグループ： ユーザー定義の色コレクションを追加できます
• ビジュアルスタイル： Office2007、Office2010、Office2016、Metro
• 色ダイアログ： 高度な選択用の「その他の色」ボタン
• サブ項目： 色のバリエーションと色合い
• イベント： Picked（選択時）、ItemSelection（ホバー時）
• 自動色： 設定可能なデフォルト色ボタン
• 実行時の選択： ダイアログから色を動的に追加できます

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

次のような場合に、このスキルを使用します。

• Windows Forms アプリケーションで色選択を実装する
• Microsoft Word スタイルのカラーピッカーインターフェイスを提供する
• 色をグループ（最近使用した色、標準色、テーマ色、カスタム色）に整理する
• 定義済みのカラーパレットからユーザーが選択できるようにする
• テーマベースの色選択に対応する
• Office スタイルの色入力コントロールを追加する
• 高度な選択用の「その他の色」ダイアログを実装する
• デスクトップアプリケーションで色選択イベントを処理する
• 特定の用途に合わせてカスタム色コレクションを作成する

コンポーネントの機能概要

機能	説明
色グループ	最近使用した色、標準色、テーマ色、カスタム色のグループ
サブ項目	各ベースカラーのバリエーション／色合い
ビジュアルスタイル	Office2007、Office2010、Office2016、Metro
イベント	Picked（選択）、ItemSelection（ホバー）
ダイアログ	高度な選択用の「その他の色」オプション
カスタマイズ	項目のサイズ、間隔、ヘッダー、境界線
実行時	ダイアログから色を動的に追加できます
テーマ	Office の配色（Blue、Silver、Black）

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

はじめに

📄 参照先： references/getting-started.md
次の情報が必要な場合：

• アセンブリの依存関係と NuGet パッケージ
• デザイナーまたはコードから ColorPickerUIAdv を追加する方法
• 名前空間のインポート（Syncfusion.Windows.Forms.Tools）
• SelectedColor プロパティを使った基本的な色選択
• 初期セットアップと構成
• 最小限の動作例

色グループと整理

📄 参照先： references/color-groups.md
次の情報が必要な場合：

• 既定のグループ（最近使用した色、標準色、テーマ色）の理解
• CustomGroups プロパティを使ったカスタム色グループの作成
• グループへの色項目とサブ項目の追加
• GroupColorItem クラスと ColorItem クラスの使用
• IsSubItemsVisible と SubItemsDepth の構成
• グループ名とヘッダーの高さの設定
• 色をカテゴリまたはテーマ別に整理する方法

外観とスタイル設定

📄 参照先： references/appearance-styling.md
次の情報が必要な場合：

• ビジュアルスタイル（Office2007、Office2010、Office2016、Metro）の適用
• Office2007 の配色（Blue、Silver、Black）の構成
• Managed テーマでのカスタム色の使用
• アプリケーション全体のテーマ設定に使用する ApplyManagedColors メソッド
• 境界線スタイル（Fixed3D、FixedSingle、None）
• BorderStyle プロパティと BorderOffset プロパティ
• UseOffice2007Style プロパティの構成

イベントと実行時の選択

📄 参照先： references/events-selection.md
次の情報が必要な場合：

• 色が選択されたときの Picked イベントの処理
• ホバー操作での ItemSelection イベントの使用
• ColorPickedEventArgs とイベントプロパティ
• 実行時の色選択ダイアログ（「その他の色」）
• AutomaticColor プロパティの構成
• 自動ボタンのサイズ設定に使用する ButtonHeight
• イベント駆動型の色処理パターン

カスタマイズとレイアウト

📄 参照： references/customization.md
必要に応じて、以下を確認してください。

• ColorItemSize プロパティによるカラー項目のサイズ設定
• 項目間の水平および垂直方向の間隔
• HorizontalItemsSpacing および VerticalItemsSpacing
• TextAlignment によるヘッダーテキストの配置
• グループヘッダーのフォントのカスタマイズ
• プロパティグリッドでのデザイン時の色編集
• 高度なレイアウトおよび間隔のオプション

クイックスタート

ColorPickerUIAdv の基本的な実装

using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

public partial class ColorPickerForm : Form
{
    private ColorPickerUIAdv colorPickerUIAdv1;
    
    public ColorPickerForm()
    {
        InitializeComponent();
        
        // Create ColorPickerUIAdv
        colorPickerUIAdv1 = new ColorPickerUIAdv();
        colorPickerUIAdv1.Size = new Size(200, 180);
        colorPickerUIAdv1.Location = new Point(20, 20);
        
        // Set initial selected color
        colorPickerUIAdv1.SelectedColor = Color.Blue;
        
        // Apply Office2016 style
        colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016Colorful;
        
        // Handle color selection
        colorPickerUIAdv1.Picked += ColorPickerUIAdv1_Picked;
        
        // Add to form
        this.Controls.Add(colorPickerUIAdv1);
    }
    
    private void ColorPickerUIAdv1_Picked(object sender, 
                                          ColorPickerUIAdv.ColorPickedEventArgs args)
    {
        // Update form background with selected color
        this.BackColor = args.Color;
        MessageBox.Show($"Selected Color: {args.Color.Name}");
    }
}

アセンブリ要件

必要なアセンブリ：

• Syncfusion.Grid.Base
• Syncfusion.Grid.Windows
• Syncfusion.Shared.Base
• Syncfusion.Shared.Windows
• Syncfusion.Tools.Base
• Syncfusion.Tools.Windows

NuGet パッケージ：

Install-Package Syncfusion.Tools.Windows

一般的なパターン

パターン 1：イベントハンドラーを使用した色の選択

// Setup
private void SetupColorPicker()
{
    colorPickerUIAdv1.SelectedColor = Color.White;
    colorPickerUIAdv1.Picked += OnColorPicked;
}

// Event handler
private void OnColorPicked(object sender, ColorPickerUIAdv.ColorPickedEventArgs e)
{
    // Apply color to target control
    targetLabel.ForeColor = e.Color;
    
    // Or update drawing operations
    currentBrush = new SolidBrush(e.Color);
    canvas.Invalidate();
}

パターン 2：Office2016 テーマの適用

// Office2016 Colorful style
colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016Colorful;

// Or Office2016 White
colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016White;

// Or Office2016 Black
colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016Black;

// Or Office2016 DarkGray
colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016DarkGray;

パターン 3：カスタムカラーグループの作成

// Create custom color group
ColorUIAdvGroup customGroup = new ColorUIAdvGroup();
customGroup.Name = "Brand Colors";
customGroup.HeaderHeight = 25;

// Create color items
GroupColorItem primaryColor = new GroupColorItem(customGroup, Color.FromArgb(0, 120, 215));
primaryColor.Index = 0;

// Add tint variations as sub-items
primaryColor.SubItems.Add(new ColorItem(primaryColor, Color.FromArgb(204, 228, 247)));
primaryColor.SubItems.Add(new ColorItem(primaryColor, Color.FromArgb(153, 204, 239)));
primaryColor.SubItems.Add(new ColorItem(primaryColor, Color.FromArgb(102, 163, 224)));

// Add to group and control
customGroup.Items.Add(primaryColor);
customGroup.SubItemsDepth = 1;
customGroup.IsSubItemsVisible = true;

colorPickerUIAdv1.CustomGroups.Add(customGroup);

パターン 4：カスタムカラーを使用した Office2007 テーマ

// Set Managed theme
colorPickerUIAdv1.UseOffice2007Style = true;
colorPickerUIAdv1.Office2007Theme = Office2007Theme.Managed;

// Apply custom color scheme
Office2007Colors.ApplyManagedColors(this, Color.Teal);

パターン 5：ItemSelection イベントを使用したホバープレビュー

// Setup hover event
colorPickerUIAdv1.ItemSelection += ColorPickerUIAdv1_ItemSelection;

// Event handler for hover preview
private void ColorPickerUIAdv1_ItemSelection(object sender, 
                                              ColorPickerUIAdv.ColorPickedEventArgs e)
{
    // Show preview without committing
    previewPanel.BackColor = e.Color;
    statusLabel.Text = $"Preview: {e.Color.Name} (RGB: {e.Color.R}, {e.Color.G}, {e.Color.B})";
}

パターン 6：自動カラーのボタンの設定

// Set automatic color (shown when "Automatic" button is clicked)
colorPickerUIAdv1.AutomaticColor = Color.Black;

// Adjust button height
colorPickerUIAdv1.ButtonHeight = 30;

主なプロパティ

色の選択

• SelectedColor - 現在選択されている色を取得または設定します
• SelectedItem - 選択されているカラー項目オブジェクトを取得します
• AutomaticColor - 「自動」ボタンの既定の色

カラーグループ

• RecentGroup - 最近使用した色のコレクション
• StandardGroup - 標準色のコレクション
• ThemeGroup - テーマカラーのコレクション
• CustomGroups - ユーザー定義のカラーグループのコレクション

ビジュアルスタイル

• Style - ビジュアルスタイル（Default、Office2007、Office2010、Office2016*、Metro）
• UseOffice2007Style - Office2007 のスタイル設定を有効または無効にします
• Office2007Theme - Office2007 の配色（Blue、Silver、Black、Managed）

レイアウトと外観

• ColorItemSize - 個々のカラー項目のサイズ（既定：13x13）
• HorizontalItemsSpacing - 項目間の水平方向の間隔（既定：4）
• VerticalItemsSpacing - 項目間の垂直方向の間隔（既定：0）
• BorderStyle - 枠線の外観（None、FixedSingle、Fixed3D）
• BorderOffset - 枠線の高さ（既定：3）
• TextAlign - ヘッダーテキストの配置（既定：MiddleLeft）
• ButtonHeight - 自動ボタンの高さ（既定：23）

イベント

• Picked - 色が選択されたときに発生します
• ItemSelection - マウスがカラー項目に重なったときに発生します

一般的な使用例

使用例 1：テキストエディターでの色の選択

テキストエディターで文字色や背景色を変更するためのカラーピッカーを実装します。

private void SetupTextColorPicker()
{
    textColorPicker.Style = ColorPickerUIAdv.visualstyle.Office2016Colorful;
    textColorPicker.SelectedColor = richTextBox.SelectionColor;
    textColorPicker.Picked += (s, e) => richTextBox.SelectionColor = e.Color;
}

使用例 2：描画アプリケーションのカラーパレット

ホバー時にプレビューを表示する、描画ツール用の色選択機能を提供します。

private void SetupDrawingColorPicker()
{
    colorPicker.Style = ColorPickerUIAdv.visualstyle.Office2016Black;
    colorPicker.ItemSelection += (s, e) => ShowColorPreview(e.Color);
    colorPicker.Picked += (s, e) => SetActiveBrushColor(e.Color);
}

使用例 3：テーマカラーのカスタマイズ

整理されたグループを使用して、アプリケーションのテーマカラーをユーザーがカスタマイズできるようにします。

private void SetupThemeColorPicker()
{
    // Add custom theme colors group
    ColorUIAdvGroup themeGroup = new ColorUIAdvGroup();
    themeGroup.Name = "Theme Colors";
    
    // Add primary, accent, background colors
    themeGroup.Items.Add(CreateColorItem(primaryColor, "Primary"));
    themeGroup.Items.Add(CreateColorItem(accentColor, "Accent"));
    themeGroup.Items.Add(CreateColorItem(backgroundColor, "Background"));
    
    colorPicker.CustomGroups.Add(themeGroup);
    colorPicker.Picked += ApplyThemeColor;
}

使用例 4：フォームデザイナーのプロパティエディター

フォームデザイナーツールのプロパティ編集にカラーピッカーを組み込みます。

private void ShowColorPickerForProperty(Control control, string propertyName)
{
    ColorPickerUIAdv picker = new ColorPickerUIAdv();
    picker.SelectedColor = (Color)control.GetType()
                                   .GetProperty(propertyName)
                                   .GetValue(control);
    
    picker.Picked += (s, e) => {
        control.GetType()
               .GetProperty(propertyName)
               .SetValue(control, e.Color);
    };
    
    ShowPickerInPopup(picker);
}

使用例 5：条件付き書式での色の選択

データグリッドの条件付き書式ルール用にカラーピッカーを提供します。

private void SetupConditionalFormatColorPicker()
{
    // Create custom group with warning/info/success colors
    ColorUIAdvGroup formatGroup = new ColorUIAdvGroup();
    formatGroup.Name = "Formatting Colors";
    
    formatGroup.Items.Add(new GroupColorItem(formatGroup, Color.Red));      // Error
    formatGroup.Items.Add(new GroupColorItem(formatGroup, Color.Orange));   // Warning
    formatGroup.Items.Add(new GroupColorItem(formatGroup, Color.Yellow));   // Caution
    formatGroup.Items.Add(new GroupColorItem(formatGroup, Color.LightGreen)); // Success
    
    colorPicker.CustomGroups.Add(formatGroup);
    colorPicker.Picked += ApplyConditionalFormatting;
}

トラブルシューティング

問題：コントロールがツールボックスに表示されない

解決策： Syncfusion.Tools.WinForms NuGet パッケージをインストールし、ソリューションを再ビルドしてください。

問題：色が正しく表示されない

解決策： フォームに追加する前に、カラーグループが正しく初期化されていることを確認してください。SubItemsDepth および IsSubItemsVisible プロパティを確認してください。

問題：テーマが適用されない

解決策： Office2007 テーマの場合は、UseOffice2007Style = true を設定してください。その他のスタイルでは、Style プロパティを直接使用してください。

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

解決策： コントロールの初期化後、フォームの読み込み前にイベントハンドラーが登録されていることを確認してください。また、コントロールがフォームの Controls コレクションに追加されていることを確認してください。

問題：カスタムグループが表示されない

解決策： ColorUIAdvGroup の作成とデータ設定の後に CustomGroups.Add() が呼び出されていることを確認してください。HeaderHeight が適切に設定されていることを確認してください。

次のステップ

1. 初期設定については、getting-started.md をお読みください
2. 色を効果的に整理するには、color-groups.md をご確認ください
3. 見た目のカスタマイズについては、appearance-styling.md をご覧ください
4. events-selection.md を使ってイベント処理を実装してください
5. customization.md を使ってレイアウトを微調整してください