syncfusion-winforms-gradient-label

GradientLabel の実装

グラデーション背景、魅力的な陰影、カスタム境界線、ビジュアルスタイル機能を備えた、Windows Forms 用の拡張ラベルコントロールです。魅力的な UI ラベルを作成できます。

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

次のような場合に、このスキルを使用してください。

• グラデーションラベル：グラデーション背景や色の変化を持つラベルを作成する
• 装飾的なヘッダー：見栄えのよいセクションヘッダーやタイトルをデザインする
• スタイル付きテキスト表示：カスタムの陰影や境界線を持つ装飾的なラベルを実装する
• UI の強化：フォームのラベルや説明テキストに視覚的な魅力を加える
• カスタムブランディング：特定の配色を使ったブランドラベルを作成する
• 情報パネル：背景効果を持つ見栄えのよい情報ラベルを作成する

コンポーネントの概要

GradientLabel は、標準の Windows Forms Label を継承した拡張ラベルコントロールで、次の機能を備えています。

• 複数のグラデーションスタイル（Horizontal、Vertical、Diagonal、PathRectangle、PathEllipse）
• 単色およびパターンの背景オプション
• カスタマイズ可能な 3D および 2D の境界線
• 複数色のグラデーションに対応
• 状態を保持するための XML シリアル化
• 標準 Label 機能との完全な互換性

主な機能：

• BrushInfo クラスを使用したグラデーション背景
• さまざまな視覚効果を実現する 6 種類のグラデーションスタイル
• 複数のスタイルに対応したパターン背景
• 境界線のカスタマイズ（辺、スタイル、色）
• 無効状態を含むテキストの表示制御
• グラデーション設定の XML への保存と読み込み
• 標準 Label のすべての機能（テキスト、フォント、配置）を継承

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

はじめに

📄 参照： references/getting-started.md

参照する場面： 新しい実装を開始するとき、依存関係を設定するとき、初めて使用するとき

説明するトピック：

• アセンブリの配置と NuGet パッケージ
• GradientLabel のコントロール依存関係
• Visual Studio デザイナーからの追加（ツールボックスからドラッグ＆ドロップ）
• コードからの追加（手動でのインスタンス化）
• 基本的な初期化と設定
• 簡単なグラデーション設定の例
• 名前空間の要件

---

背景のスタイル設定

📄 参照： references/background-styling.md

参照する場面： グラデーションを設定するとき、色を指定するとき、背景の外観をカスタマイズするとき

説明するトピック：

• BackgroundColor プロパティと BrushInfo クラス
• ブラシスタイル（Solid、Pattern、Gradient、None）
• グラデーションスタイル（ForwardDiagonal、BackwardDiagonal、Horizontal、Vertical、PathRectangle、PathEllipse）
• BackColor プロパティと ForeColor プロパティ
• パターン背景の PatternStyle オプション
• 複数色のグラデーションに使用する GradientColors 配列
• カスタムの色の変化を作成する方法
• スタイル設定の完全な例

---

境界線の設定

📄 参照： references/border-configuration.md

参照する場面： 境界線を追加するとき、境界線のスタイルをカスタマイズするとき、境界線の外観を制御するとき

説明するトピック：

• BorderSides プロパティ（Left、Top、Right、Bottom、Middle、All）
• BorderStyle オプション（Raised、Sunken、Flat、Etched、Bump など）
• 2D 境界線の色を指定する BorderColor
• Border3DStyle 列挙型
• FixedSingle 境界線モード
• 特定の辺の境界線
• 3D 境界線効果
• 境界線設定の完全な例

---

前景とテキストの設定

📄 参照： references/foreground-text-settings.md

参照する場面： テキストの外観を設定するとき、フォントのプロパティを指定するとき、無効状態を管理するとき

説明するトピック：

• ラベルの内容を指定する Text プロパティ
• テキストの色を指定する ForeColor
• DrawActiveWhenDisabled プロパティ
• Label から継承される Font プロパティ
• テキスト配置オプション（継承）
• TextAlign プロパティの使用方法
• 無効状態の外観制御
• テキストの表示とスタイル設定

---

シリアル化

📄 読む: references/serialization.md

読むタイミング: グラデーション設定の保存／読み込み、視覚的な状態の永続化、テーマの実装

取り上げるトピック:

• XML シリアル化の概要
• BackgroundColor の XML ファイルへの保存
• XML ファイルからの BackgroundColor の読み込み
• XmlSerializer クラスの使用方法
• FileStream と XmlTextWriter の実装
• セッションをまたいだグラデーション状態の永続化
• テーマの保存／読み込みパターン
• シリアル化の完全なサンプル

---

クイックスタート

基本的なグラデーションラベルの設定

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

// Create and configure GradientLabel
GradientLabel gradientLabel = new GradientLabel();
gradientLabel.Size = new Size(200, 60);
gradientLabel.Location = new Point(20, 20);

// Set gradient background (horizontal red to blue)
gradientLabel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.Red,
    Color.MediumBlue
);

// Set text properties
gradientLabel.Text = "Welcome";
gradientLabel.ForeColor = Color.White;
gradientLabel.Font = new Font("Arial", 14, FontStyle.Bold);

// Add to form
this.Controls.Add(gradientLabel);

境界線のスタイル設定

// Add 3D border effect
gradientLabel.BorderStyle = Border3DStyle.Raised;
gradientLabel.BorderSides = Border3DSide.All;

よく使われるパターン

パターン 1：垂直グラデーションのセクション見出し

// Create attractive section header
GradientLabel header = new GradientLabel
{
    Size = new Size(300, 50),
    Location = new Point(10, 10),
    Text = "User Information",
    Font = new Font("Segoe UI", 16, FontStyle.Bold),
    TextAlign = ContentAlignment.MiddleCenter,
    ForeColor = Color.White
};

// Vertical gradient from dark to light blue
header.BackgroundColor = new BrushInfo(
    GradientStyle.Vertical,
    Color.DarkBlue,
    Color.LightSkyBlue
);

// Raised 3D border
header.BorderStyle = Border3DStyle.Raised;

パターン 2：マルチカラーグラデーションのラベル

// Create label with multiple gradient colors
GradientLabel colorfulLabel = new GradientLabel
{
    Size = new Size(250, 80),
    Text = "Special Offer!",
    Font = new Font("Arial", 18, FontStyle.Bold),
    ForeColor = Color.White,
    TextAlign = ContentAlignment.MiddleCenter
};

// Path rectangle gradient with 5 colors
colorfulLabel.BackgroundColor = new BrushInfo(
    GradientStyle.PathRectangle,
    new Color[]
    {
        Color.LavenderBlush,
        Color.LemonChiffon,
        Color.DarkKhaki,
        Color.SandyBrown,
        Color.LightSeaGreen
    }
);

パターン 3：スタイル設定されたステータスラベル

// Create status indicator label
GradientLabel statusLabel = new GradientLabel
{
    Size = new Size(150, 30),
    Text = "Active",
    TextAlign = ContentAlignment.MiddleCenter,
    ForeColor = Color.DarkGreen,
    Font = new Font("Arial", 10, FontStyle.Bold)
};

// Horizontal gradient (light green)
statusLabel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.LightGreen,
    Color.PaleGreen
);

// Flat border with custom color
statusLabel.BorderStyle = Border3DStyle.Flat;
statusLabel.BorderSides = Border3DSide.All;
statusLabel.BorderColor = Color.DarkGreen;

主なプロパティ

背景プロパティ

• BackgroundColor：BrushInfo クラスを使用して、背景色とスタイルを取得／設定します
• BackgroundColor.Style：ブラシのスタイル（Solid、Pattern、Gradient、None）
• BackgroundColor.GradientStyle：グラデーションの方向（Horizontal、Vertical、ForwardDiagonal、BackwardDiagonal、PathRectangle、PathEllipse）
• BackgroundColor.BackColor：グラデーションの開始色
• BackgroundColor.ForeColor：グラデーションの終了色
• BackgroundColor.PatternStyle：Pattern モード使用時のパターンスタイル
• BackgroundColor.GradientColors：マルチカラーグラデーション用の色の配列

境界線プロパティ

• BorderSides：境界線を表示する辺（Left、Top、Right、Bottom、Middle、All）
• BorderStyle：3D 境界線のスタイル（Raised、RaisedOuter、RaisedInner、Sunken、SunkenOuter、SunkenInner、Etched、Bump、Adjust、Flat）
• BorderColor：2D 境界線の色（BorderStyle が FixedSingle の場合に有効）

テキストプロパティ（Label から継承）

• Text：ラベルのテキスト内容
• Font：テキスト表示に使用するフォント
• ForeColor：テキストの色
• TextAlign：テキストの配置（ContentAlignment enum）
• DrawActiveWhenDisabled：コントロールが無効な場合でも、テキストを通常どおり描画するかどうか

標準の Label プロパティ

• System.Windows.Forms.Label のすべてのプロパティを使用できます
• Size、Location、Enabled、Visible など

よくある用途

フォームのセクション見出し

フォーム内の関連するコントロールをグループ化する、視覚的に目立つセクション見出しを作成します。

ダッシュボードパネル

ダッシュボードアプリケーションで、見栄えのよい情報パネルやステータス表示を作成します。

ブランディング要素

独自の配色やグラデーション効果を用いて、企業のブランディングを実装します。

ステータスインジケーター

色分けされたグラデーション（成功、警告、エラー）を使用して、目を引くステータスラベルをデザインします。

装飾テキスト

重要なテキスト、お知らせ、プロモーションメッセージに視覚的な魅力を加えます。

テーマに基づくラベル表示

シリアル化による保存と読み込みが可能な、テーマに沿ったラベルを作成します。

注意事項

• GradientLabel は System.Windows.Forms.Label から派生しているため、標準の Label の機能をすべて使用できます
• BrushInfo クラスはグラデーションとスタイル設定の機能を提供します
• BackgroundColor プロパティがカスタマイズの鍵となります
• BorderColor は BorderStyle が Border3DStyle.Flat に設定されている場合にのみ機能します
• グラデーションカラー配列の最初の要素は BackColor に、最後の要素は ForeColor に対応します
• XML シリアル化を使うと、アプリケーションのセッションをまたいでグラデーション設定を永続化できます
• 一般的な用途向けにパフォーマンスが最適化されています。多数のコントロールで過度に複雑なグラデーションを使用しないでください