syncfusion-winforms-gradientpanelext

GradientPanelExt の実装

グラデーション背景、角丸、境界線プリミティブ、折りたたみ／展開機能を備えた、Windows Forms 用の拡張パネルコントロールです。洗練されたコンテナパネルを作成できます。

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

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

• グラデーションコンテナパネル：ほかのコントロールを配置できる、グラデーション背景のパネルを作成する
• 角丸パネル：角の半径をカスタマイズして、モダンな UI のパネルをデザインする
• 境界線プリミティブ：パネルの境界線にテキスト、画像、ボタン、コントロールを追加する（独自の機能）
• 折りたたみ可能なセクション：アニメーション付きの展開／折りたたみ可能なパネルセクションを実装する
• スタイル付きコンテナ：カスタム背景で、見た目に魅力的なコンテナパネルを作成する
• ログイン／ダイアログパネル：グラデーションを使った魅力的なログインフォームやダイアログボックスを作成する
• ダッシュボードセクション：境界線にタイトルやコントロールを配置したダッシュボードパネルをデザインする

コンポーネントの概要

GradientPanelExt は標準の Panel コントロールを拡張したもので、次の機能を備えています。

• 複数のグラデーションスタイル（Horizontal、Vertical、Diagonal、PathRectangle、PathEllipse）
• 半径を設定できる角丸
• プリミティブシステム — テキスト、画像、折りたたみコントロール、.NET コントロールをパネルの境界線に配置
• パターンと単色の背景オプション
• 折りたたみ／展開アニメーションのサポート
• 複数色のグラデーションのサポート
• ほかの WinForms コントロールのコンテナとして機能

主な機能：

• BrushInfo クラスを使用したグラデーション背景
• 角丸四角形を表示する CornerRadius
• プリミティブコレクション（CollapsePrimitive、ImagePrimitive、TextPrimitive、HostPrimitive）
• 間隔を調整する BorderGap
• 速度と遅延を設定できる、アニメーション付きの折りたたみ／展開
• 背景画像のサポート
• 標準の Panel と同様に子コントロールを配置

独自の機能 — プリミティブ： GradientPanelExt の最も強力な機能は、パネルの境界線に「プリミティブ」を追加できることです。テキストラベル、画像、折りたたみボタン、さらには .NET コントロール全体を、上、下、左、右の境界線に配置できます。

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

はじめに

📄 参照： references/getting-started.md

読むタイミング： 新しい実装を始めるとき、依存関係を設定するとき、初めて使用するとき

対象トピック：

• アセンブリの配置（Syncfusion.Shared.Base）
• NuGet パッケージのインストール
• Visual Studio デザイナーで追加する方法（ツールボックスからのドラッグ＆ドロップ）
• コードで追加する方法（手動でのインスタンス化）
• パネルの基本的な初期化と設定
• パネルへの子コントロールの追加
• PrimitiveCollection エディターの概要
• シンプルなグラデーションパネルの例
• 名前空間の要件（Syncfusion.Windows.Forms.Tools）

---

背景のスタイル設定

📄 参照： references/background-styling.md

読むタイミング： グラデーションを設定するとき、背景色を設定するとき、パネルの外観をカスタマイズするとき

対象トピック：

• BackgroundColor プロパティと BrushInfo クラス
• 背景スタイル（Solid、Pattern、Gradient、None）
• グラデーションスタイル（Horizontal、Vertical、ForwardDiagonal、BackwardDiagonal、PathRectangle、PathEllipse）
• BackColor プロパティと ForeColor プロパティ
• GradientColors 配列を使った複数色のグラデーション
• PatternStyle を使ったパターン背景
• BackgroundImage と BackgroundImageLayout
• 複雑な色の変化の作成
• コードを含むスタイル設定の完全な例

---

境界線と角の設定

📄 参照： references/border-corner-settings.md

読むタイミング： 角をカスタマイズするとき、境界線の外観を調整するとき、角丸パネルを作成するとき

対象トピック：

• 角丸を設定する CornerRadius プロパティ
• 角丸を解除する方法（CornerRadius = 0）
• 余白を設定する BorderGap プロパティ
• シャープな角と角丸のデザイン
• 角とグラデーションの調整
• さまざまな半径値を使った完全な例
• モダンなデザインとクラシックなデザインそれぞれのベストプラクティス

---

プリミティブ

📄 参照： references/primitives.md

参照するタイミング： 境界線要素の追加、折りたたみ機能の実装、境界線内へのコントロールの配置

対象トピック：

• プリミティブの概要と PrimitiveCollection エディター
• CollapsePrimitive（画像を使った展開／折りたたみ）
• ImagePrimitive（境界線内の画像）
• TextPrimitive（境界線内のテキストラベル）
• HostPrimitive（境界線内への .NET コントロールの配置）
• Alignment プロパティ（Top、Bottom、Left、Right）
• ピクセル単位で配置する Position プロパティ
• プリミティブのサイズを指定する Size プロパティ
• すべてのプリミティブ型を使った完全なサンプル
• プリミティブを使ったログインパネルのサンプル

---

折りたたみと展開のアニメーション

📄 参照： references/collapse-expand-animation.md

参照するタイミング： アニメーション付きの折りたたみの実装、アニメーション動作の設定

対象トピック：

• Animated プロパティ（アニメーションの有効化／無効化）
• タイミングを設定する AnimationDelay プロパティ
• 速度を制御する AnimationSpeed プロパティ
• CollapsePrimitive との連携
• 滑らかな折りたたみと即時の折りたたみの動作
• アニメーションの完全なサンプル
• パフォーマンスに関する考慮事項

---

スクロール設定とイベント

📄 参照： references/scroll-settings-events.md

参照するタイミング： スクロール可能なコンテンツの処理、イベントへの応答、カスタムイベントの処理

対象トピック：

• スクロール可能なパネルの AutoScroll プロパティ
• スクロールバーの設定
• GradientPanelExt 固有のイベント
• 折りたたみ／展開イベントの処理
• プリミティブのクリックイベント
• カスタム描画用の Paint イベント
• イベントハンドラーの完全なサンプル
• メモリ管理とクリーンアップ

---

クイックスタート

基本的な Gradient Panel のセットアップ

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

// Create GradientPanelExt
GradientPanelExt gradientPanel = new GradientPanelExt();
gradientPanel.Size = new Size(400, 200);
gradientPanel.Location = new Point(20, 20);

// Set gradient background (horizontal blue gradient)
gradientPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.DarkBlue,
    Color.LightSkyBlue
);

// Rounded corners
gradientPanel.CornerRadius = 10;

// Add child controls
Label label = new Label
{
    Text = "Welcome",
    ForeColor = Color.White,
    BackColor = Color.Transparent,
    Location = new Point(20, 20),
    AutoSize = true
};
gradientPanel.Controls.Add(label);

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

境界線内にプリミティブを配置する場合

// Add title text primitive at top border
TextPrimitive titlePrimitive = new TextPrimitive
{
    Text = "User Login",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    TextColor = Color.White,
    TextFont = new Font("Arial", 12, FontStyle.Bold),
    Size = new Size(100, 25),
    BackColor = Color.Transparent
};

// Add button primitives at bottom border
TextPrimitive okButton = new TextPrimitive
{
    Text = "OK",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Bottom,
    Position = 100,
    Size = new Size(60, 25),
    BackColor = Color.White,
    TextColor = Color.Black
};

TextPrimitive cancelButton = new TextPrimitive
{
    Text = "Cancel",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Bottom,
    Position = 180,
    Size = new Size(60, 25),
    BackColor = Color.White,
    TextColor = Color.Black
};

// Add primitives to panel
gradientPanel.Primitives.AddRange(new Primitive[] { 
    titlePrimitive, 
    okButton, 
    cancelButton 
});

よくあるパターン

パターン 1：グラデーションとプリミティブを使ったログインパネル

// Create login panel
GradientPanelExt loginPanel = new GradientPanelExt
{
    Size = new Size(350, 180),
    Location = new Point(50, 50),
    CornerRadius = 12
};

// Dark gradient background
loginPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.FromArgb(40, 40, 40),
    Color.FromArgb(80, 80, 80)
);

// Title primitive at top
TextPrimitive title = new TextPrimitive
{
    Text = "Login",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    TextColor = Color.White,
    TextFont = new Font("Segoe UI", 14, FontStyle.Bold),
    Size = new Size(80, 30),
    BackColor = Color.Transparent
};
loginPanel.Primitives.Add(title);

// Add username and password textboxes inside panel
Label lblUsername = new Label
{
    Text = "Username:",
    Location = new Point(30, 40),
    ForeColor = Color.White,
    BackColor = Color.Transparent,
    AutoSize = true
};

TextBox txtUsername = new TextBox
{
    Location = new Point(110, 38),
    Size = new Size(180, 20)
};

loginPanel.Controls.Add(lblUsername);
loginPanel.Controls.Add(txtUsername);

パターン 2：折りたたみ可能なダッシュボードセクション

// Create collapsible panel
GradientPanelExt dashboardPanel = new GradientPanelExt
{
    Size = new Size(400, 250),
    Location = new Point(20, 20),
    CornerRadius = 8,
    Animated = true,
    AnimationSpeed = 3
};

// Vertical gradient
dashboardPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Vertical,
    Color.WhiteSmoke,
    Color.LightGray
);

// Section title
TextPrimitive sectionTitle = new TextPrimitive
{
    Text = "Sales Statistics",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    TextColor = Color.DarkBlue,
    TextFont = new Font("Arial", 12, FontStyle.Bold),
    Size = new Size(150, 25)
};

// Collapse primitive
CollapsePrimitive collapseButton = new CollapsePrimitive
{
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    Position = 350,
    Size = new Size(30, 30),
    BackColor = Color.Transparent
};
// Set images in designer or load from resources

dashboardPanel.Primitives.AddRange(new Primitive[] { 
    sectionTitle, 
    collapseButton 
});

パターン 3：画像と HostPrimitive を使ったパネル

// Create styled panel
GradientPanelExt styledPanel = new GradientPanelExt
{
    Size = new Size(450, 300),
    CornerRadius = 10
};

// PathEllipse gradient with multiple colors
styledPanel.BackgroundColor = new BrushInfo(
    GradientStyle.PathEllipse,
    new Color[]
    {
        Color.LightBlue,
        Color.LightCyan,
        Color.PaleTurquoise
    }
);

// Image primitive at top-left
ImagePrimitive logo = new ImagePrimitive
{
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    Position = 10,
    Size = new Size(40, 40)
    // Set Image property from resources
};

// Host a ProgressBar at bottom
ProgressBar progressBar = new ProgressBar
{
    Value = 50,
    Style = ProgressBarStyle.Continuous
};

HostPrimitive progressHost = new HostPrimitive
{
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Bottom,
    Position = 100,
    Size = new Size(250, 20),
    HostControl = progressBar,
    BackColor = Color.Transparent
};

styledPanel.Primitives.AddRange(new Primitive[] { 
    logo, 
    progressHost 
});

主なプロパティ

背景プロパティ

• 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：複数色のグラデーション用の配列
• BackgroundImage：パネルの背景画像
• BackgroundImageLayout：背景画像のレイアウトスタイル

境界線と角のプロパティ

• CornerRadius：角を丸める半径（0 = 角を丸めない）
• BorderGap：境界線とマージンの間隔

プリミティブのプロパティ

• Primitives：プリミティブのコレクション（PrimitiveCollection エディターからアクセス）
• Primitive.Alignment：境界線上の位置（Top、Bottom、Left、Right）
• Primitive.Position：境界線に沿ったピクセル単位のオフセット
• Primitive.Size：プリミティブの幅と高さ
• Primitive.BackColor：プリミティブの背景色

アニメーションのプロパティ

• Animated：折りたたみアニメーションの有効化／無効化
• AnimationDelay：アニメーションの遅延時間（ミリ秒）
• AnimationSpeed：アニメーションの速度係数

コンテナーのプロパティ（Panel から継承）

• Controls：パネル内に配置される子コントロールのコレクション
• AutoScroll：コンテンツがあふれた場合にスクロールバーを有効化
• Padding：子コントロールの内部余白

よくある用途

ログイン／認証パネル

グラデーション背景、境界線内のタイトル、ボタンプリミティブを使って、見栄えのよいログインフォームを作成します。

ダッシュボードセクション

上部の境界線内にセクションタイトルを配置し、折りたたみ機能を備えたダッシュボードパネルを作成します。

設定パネル

カテゴリタイトルと整理されたコントロールグループを備えた設定用コンテナーを設計します。

情報ボックス

境界線内にアイコンを配置し、内部にリッチコンテンツを表示する、スタイル設定された情報パネルを作成します。

ウィザードのステップ

境界線内にステップ番号やアイコンを配置したウィザードのステップパネルを実装します。

グループ化されたコントロール

関連するフォームコントロールを、視覚的に区別できるグラデーションパネルに整理します。

折りたたみ可能なサイドバー

折りたたみプリミティブを使って、展開可能なサイドバーパネルを作成し、スペースを管理します。

注意事項

• GradientPanelExt は Panel を継承しているため、標準の Panel の機能をすべて利用できます
• Primitives 機能は GradientPanelExt 独自のもので、非常に強力です
• Primitives はメインパネル領域ではなく、境界線内に配置されます
• CornerRadius はデフォルトで角を丸くします（角を直角にするには 0 を設定します）
• 子コントロールは、通常の Panel と同様に Controls コレクションに追加します
• CollapsePrimitive を使うには、折りたたみ用と展開用の画像を設定する必要があります
• HostPrimitive は、カスタムコントロールを含む任意の .NET コントロールをホストできます
• アニメーションプロパティが折りたたみ／展開に影響するのは、CollapsePrimitive を使う場合のみです
• BackgroundColor と Primitives には、同じグラデーションまたは連動するグラデーションを使用できます
• 一般的な用途でのパフォーマンスは良好です。Primitives の過剰な使用は避けてください