syncfusion-winforms-progress-bar

Windows Forms プログレスバー（ProgressBarAdv）

Syncfusion の Windows Forms ProgressBarAdv コントロールは、インストール、コピー、印刷、ダウンロードなどの時間がかかる操作中に進捗情報を表示します。カスタマイズ可能なテキスト形式、色、向き、ビジュアルスタイルで進捗を表示できます。

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

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

• 時間がかかる操作（ファイル操作、インストール、ダウンロード）の進捗情報を表示する
• 完了率または合計に対する現在の値を表示する
• カスタムテキストやアニメーションを使った読み込みインジケーターを実装する
• 横向きまたは縦向きのプログレスバーを作成する
• 色、グラデーション、境界線、画像でプログレスバーの外観をカスタマイズする
• ビジュアルテーマ（Office 2016、System、Tube、Gradient の各スタイル）を適用する
• 進捗イベント（ValueChanged、カスタム描画）を処理する
• プログレスバーにカスタムテキスト（「読み込み中...」「処理中...」など）を表示する
• 視覚的なフィードバックで時間のかかる操作を追跡する

コンポーネントの概要

主な機能：

• テキスト形式： パーセンテージ、値、またはカスタムテキストの表示
• 進捗画像： 進捗表示に画像を使用
• 色のカスタマイズ： 前景色、背景色、グラデーション、境界線の色
• 向き： 横向きまたは縦向きのプログレスバー
• ビジュアルスタイル： Office2016Colorful、Office2016White、Office2016DarkGray、Office2016Black、System、Tube、Gradient
• イベント： ValueChanged、カスタム描画用の DrawWaitingCustomRender
• テーマ： ThemesEnabled プロパティによる組み込みテーマのサポート

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

はじめに

📄 参照先： references/getting-started.md

次の内容については、このリファレンスを参照してください。

• NuGet またはデザイナーから ProgressBarAdv コントロールをインストールする
• Windows Forms プロジェクトにコントロールを追加する
• ProgressBarAdv インスタンスをプログラムで作成する
• 基本プロパティ（Value、Minimum、Maximum）を設定する
• 初期プログレスバーの設定を構成する
• アセンブリの配置要件を理解する

テキストと表示設定

📄 参照先： references/text-display.md

次の内容については、このリファレンスを参照してください。

• TextStyle（Percentage、Value、Custom）を構成する
• CustomText プロパティでカスタムテキストを設定する
• テキストの配置（Left、Center、Right）を調整する
• テキストの向きを構成する
• テキストの色とフォントをカスタマイズする
• 表示形式のパターンを実装する

外観とスタイル設定

📄 参照先： references/appearance-styling.md

次の内容については、このリファレンスを参照してください。

• 前景色とグラデーションをカスタマイズする
• 背景色と画像を設定する
• 境界線の設定（スタイル、色、辺）を構成する
• 進捗画像を追加する
• ProgressStyle のオプションを使用する
• 背景スタイルを適用する
• 色のカスタマイズパターンを実装する

向きとレイアウト

📄 参照先： references/orientation-layout.md

次の内容については、このリファレンスを参照してください。

• 横向きまたは縦向きの向きを設定する
• プログレスバーのレイアウトを構成する
• サイズと位置を処理する
• レスポンシブデザインのパターンを実装する
• さまざまなフォームレイアウトに合わせて調整する

テーマ

📄 参照先： references/themes.md

次の内容については、このリファレンスを参照してください。

• ThemesEnabled でテーマのサポートを有効にする
• 組み込みのビジュアルスタイル（Office2016Colorful、Office2016White など）を適用する
• ProgressStyle のオプションを構成する
• アプリケーションに適したテーマを選択する
• テーマ選択のガイドラインを理解する

イベントと高度なカスタマイズ

📄 参照先： references/events-advanced.md

次の内容については、このリファレンスを参照してください。

• ValueChanged イベントを処理する
• DrawWaitingCustomRender イベントを実装する
• カスタム描画パターンを作成する
• WaitingCustomRender モードを使用する
• ProgressFallBackStyle のオプションを構成する
• 高度なカスタマイズのシナリオを実装する

クイックスタート

基本的なプログレスバー

using Syncfusion.Windows.Forms.Tools;

// Create ProgressBarAdv instance
ProgressBarAdv progressBarAdv1 = new ProgressBarAdv();
progressBarAdv1.Location = new Point(20, 20);
progressBarAdv1.Size = new Size(300, 30);

// Set range and value
progressBarAdv1.Minimum = 0;
progressBarAdv1.Maximum = 100;
progressBarAdv1.Value = 60;

// Configure text display
progressBarAdv1.TextStyle = ProgressBarTextStyles.Percentage;
progressBarAdv1.TextAlignment = TextAlignment.Center;

// Apply visual style
progressBarAdv1.ProgressStyle = ProgressBarStyles.Office2016Colorful;

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

よく使われるパターン

パターン 1：パーセンテージを表示するプログレスバー

// Display progress as percentage
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 45;
progressBar.TextStyle = ProgressBarTextStyles.Percentage;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

パターン 2：カスタムテキストのプログレスバー

// Display custom text (e.g., "Loading...")
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 30;
progressBar.TextStyle = ProgressBarTextStyles.Custom;
progressBar.CustomText = "Loading files...";
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

パターン 3：値形式のプログレスバー

// Display current value out of maximum (e.g., "60/100")
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 60;
progressBar.TextStyle = ProgressBarTextStyles.Value;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

パターン 4：垂直プログレスバー

// Create vertical progress bar
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.ProgressOrientation = Orientation.Vertical;
progressBar.Size = new Size(50, 200);
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 75;
progressBar.TextStyle = ProgressBarTextStyles.Percentage;

this.Controls.Add(progressBar);

パターン 5：カスタムカラーを使用したテーマ付きプログレスバー

// Apply theme and custom colors
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.ProgressStyle = ProgressBarStyles.Office2016Colorful;
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 50;

// Custom colors
progressBar.ForeColor = Color.Blue;
progressBar.BackColor = Color.LightGray;

// Text settings
progressBar.TextStyle = ProgressBarTextStyles.Percentage;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

パターン 6：ValueChanged イベントを使用したプログレスバー

// Create progress bar with event handling
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 0;
progressBar.TextStyle = ProgressBarTextStyles.Custom;
progressBar.CustomText = "Starting...";

// Subscribe to ValueChanged event
progressBar.ValueChanged += ProgressBar_ValueChanged;

this.Controls.Add(progressBar);

// Event handler
private void ProgressBar_ValueChanged(object sender, EventArgs e)
{
    ProgressBarAdv pb = sender as ProgressBarAdv;
    if (pb.Value < 100)
    {
        pb.CustomText = $"Processing... {pb.Value}%";
    }
    else
    {
        pb.CustomText = "Complete!";
    }
}

パターン 7：時間のかかる処理のシミュレーション

// Simulate a long-running operation with progress updates
private async void StartOperation()
{
    ProgressBarAdv progressBar = new ProgressBarAdv();
    progressBar.Location = new Point(20, 20);
    progressBar.Size = new Size(400, 30);
    progressBar.Minimum = 0;
    progressBar.Maximum = 100;
    progressBar.Value = 0;
    progressBar.TextStyle = ProgressBarTextStyles.Percentage;
    progressBar.ProgressStyle = ProgressBarStyles.Office2016Colorful;
    
    this.Controls.Add(progressBar);
    
    // Simulate operation
    for (int i = 0; i <= 100; i += 10)
    {
        progressBar.Value = i;
        await Task.Delay(500); // Simulate work
    }
    
    MessageBox.Show("Operation complete!");
}

主なプロパティ

プロパティ	型	説明
Value	int	現在の進捗値
Minimum	int	最小進捗値（既定値：0）
Maximum	int	最大進捗値（既定値：100）
TextStyle	ProgressBarTextStyles	テキスト形式：Percentage、Value、Custom
CustomText	string	表示するカスタムテキスト（TextStyle = Custom の場合）
TextAlignment	TextAlignment	テキストの配置：Left、Center、Right
ProgressOrientation	Orientation	水平または垂直の向き
ProgressStyle	ProgressBarStyles	ビジュアルスタイル：Office2016Colorful、Tube、Gradient など
ThemesEnabled	bool	テーマのサポートを有効にする
ForeColor	Color	前景色／進捗色
BackColor	Color	背景色
BackgroundStyle	ProgressBarBackgroundStyles	背景スタイルのオプション

主なイベント

イベント	説明
ValueChanged	Value プロパティが変更されたときに発生します
DrawWaitingCustomRender	待機中のグラデーションをカスタム描画できます

テキスト形式のオプション

TextStyle	表示形式	例
Percentage	パーセンテージを表示	"60%"
Value	値／最大値を表示	"60/100"
Custom	CustomText を表示	"Loading..."

ビジュアルスタイルのオプション

ProgressStyle	説明
Office2016Colorful	青のアクセントが特徴の鮮やかな Office 2016 テーマ
Office2016White	すっきりとした明るい Office 2016 テーマ
Office2016DarkGray	中程度の暗さの Office 2016 テーマ
Office2016Black	コントラストの強い暗色の Office 2016 テーマ
System	標準の Windows システムスタイル
Tube	チューブ型の進捗インジケーター
Gradient	グラデーションの進捗効果