syncfusion-winforms-wizard-control

Windows Forms での WizardControl の実装

このスキルでは、Windows Forms アプリケーションに Syncfusion WizardControl コンポーネントを実装する方法を説明します。WizardControl は、複雑なタスクをシンプルな連続ステップに分割し、ガイド付きナビゲーションを提供する、豊富な機能を備えたインタラクティブなインターフェイスです。

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

次のようなニーズがある場合に、このスキルを使用してください。

• 複数ステップのインストールウィザードやセットアップウィザードを作成する
• 戻る／次へナビゲーションを備えた連続フォームを実装する
• 複雑なデータ入力のためのガイド付きワークフローを構築する
• ステップごとの設定インターフェイスを設計する
• 複数ページからなるオンボーディングエクスペリエンスを作成する
• タスクを完了するためのウィザード形式のダイアログを実装する
• 分類されたデータ収集をユーザーに案内する
• 進行状況を追跡できる登録やチェックアウトのプロセスを構築する

コンポーネントの概要

WizardControl は、連続したタスクをユーザーに案内する複数ページのコンテナーで、ナビゲーションボタンを自動的に管理します。

主な機能：

• 複数ページの管理 - 柔軟な順序設定が可能な WizardControlPage コレクション
• ナビゲーションボタン - 戻る、次へ、キャンセル、完了、ヘルプ。ページごとに表示を制御できます
• バナーパネル - コンテキストを示すタイトル、説明、画像を含むヘッダー
• ページ検証 - ナビゲーション前にデータを検証する ValidatePage イベント
• デザイン時のサポート - スマートタグ、コレクションエディター、視覚的なページナビゲーション
• 柔軟なレイアウト - FullPage モード、ボタンの配置設定、BannerPanel のカスタマイズ
• イベントシステム - ページのライフサイクルイベント、ボタンクリックイベント、ナビゲーションイベント
• テーマのサポート - Style プロパティによる外観の完全なカスタマイズ
• RTL のサポート - 国際対応アプリケーション向けの右から左へのレイアウト

アセンブリ： Syncfusion.Tools.Windows.dll
名前空間： Syncfusion.Windows.Forms.Tools
依存関係： 6 個のアセンブリ（Grid.Base、Grid.Windows、Shared.Base、Shared.Windows、Tools.Base、Tools.Windows）

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

はじめに

📄 参照： references/getting-started.md

参照する場面：

• 初めて WizardControl をセットアップする
• アセンブリ要件とインストール方法を確認する
• デザイナーまたはコードからコントロールを追加する
• 複数ページを持つ基本的なウィザードを作成する
• WizardContainer と WizardControlPages を設定する
• セットアップ時の問題をトラブルシューティングする

ウィザードページ

📄 参照： references/wizard-pages.md

参照する場面：

• WizardControlPage コレクションを作成、管理する
• ページのタイトルと説明を設定する
• FullPage プロパティを設定してバナーを非表示にする
• コレクションエディターまたはプロパティを使用してページの順序を変更する
• カスタムの順序を設定するため NextPage と PreviousPage を指定する
• デザイン時および実行時にページへアクセスする
• 動的なコンテンツを含む複数ページのウィザードを構築する

ナビゲーションボタン

📄 参照： references/navigation-buttons.md

参照する場面：

• ボタンの表示を制御する（BackVisible、NextVisible など）
• ページごとにボタンを有効化／無効化する
• 最終ページに完了ボタンを追加する
• ウィザードにカスタムボタンを作成する
• GridBagLayout を使用してボタンの順序を変更する
• ボタンの外観をカスタマイズする（FlatStyle、色、画像）
• BackButton、NextButton、CancelButton の各プロパティにアクセスする

バナーの設定

📄 参照： references/banner-configuration.md

参照する場面：

• グラデーション背景を使用して BannerPanel を設定する
• ヘッダー画像に Banner プロパティを設定する
• Title ラベルと Description ラベルをカスタマイズする
• AutoLayoutBanner／Title／Description プロパティを使用する
• バナー領域にカスタムコントロールを追加する
• タイトルと説明のテキストをスタイル設定する
• ブランドに合わせたウィザードヘッダーを作成する

ページの検証とイベント

📄 参照： references/page-validation-events.md

参照するタイミング：

• ValidatePage イベントを使用してページの検証を実装するとき
• ナビゲーションイベント（BeforeNext、BeforeBack、BeforeFinish）を処理するとき
• ボタンクリック（BackClick、NextClick など）に応答するとき
• PageLoad イベントを使用してページを初期化するとき
• カスタムページシーケンスを実装するとき
• 検証結果に基づいてナビゲーションをキャンセルするとき
• BackButtonCausesValidation プロパティを使用するとき

外観のカスタマイズ

📄 参照： references/appearance-customization.md

参照するタイミング：

• ウィザードとページの背景をカスタマイズするとき
• テキストのフォントと色を設定するとき
• 境界線スタイル（Fixed3D、FixedSingle）を設定するとき
• BannerPanel にグラデーションを適用するとき
• Style プロパティでテーマを適用するとき
• ライトモード／ダークモードのウィザードを作成するとき
• アプリケーションのブランドイメージに合わせるとき

デザイン時の機能

📄 参照： references/design-time-features.md

参照するタイミング：

• ウィザードの操作にスマートタグを使用するとき
• デザイン時にページを追加／削除するとき
• デザイナーでページ間を移動するとき
• ページ管理にコレクションエディターを使用するとき
• プロパティグリッドでプロパティを設定するとき
• SelectedWizardPage プロパティについて理解するとき
• CardLayout プロパティを使用するとき

クイックスタートの例

基本的なインストールウィザード

C#:

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

public partial class InstallationWizard : Form
{
    private WizardControl wizardControl1;
    private WizardControlPage welcomePage;
    private WizardControlPage licensePage;
    private WizardControlPage installPage;
    private WizardControlPage finishPage;
    
    public InstallationWizard()
    {
        InitializeComponent();
        CreateWizard();
    }
    
    private void CreateWizard()
    {
        // Create wizard control
        wizardControl1 = new WizardControl
        {
            Dock = DockStyle.Fill,
            Style = Syncfusion.Windows.Forms.Tools.Wizard.Style.Metro
        };
        
        // Create pages
        welcomePage = new WizardControlPage
        {
            Title = "Welcome",
            Description = "Welcome to the Installation Wizard",
            BackVisible = false  // Hide Back on first page
        };
        
        licensePage = new WizardControlPage
        {
            Title = "License Agreement",
            Description = "Please read and accept the license terms"
        };
        
        installPage = new WizardControlPage
        {
            Title = "Installing",
            Description = "Please wait while files are being installed"
        };
        
        finishPage = new WizardControlPage
        {
            Title = "Completed",
            Description = "Installation completed successfully",
            NextVisible = false,
            CancelVisible = false,
            FinishVisible = true
        };
        
        // Add pages to wizard
        wizardControl1.WizardPages = new WizardControlPage[]
        {
            welcomePage,
            licensePage,
            installPage,
            finishPage
        };
        
        // Add wizard to form
        this.Controls.Add(wizardControl1);
        this.Text = "Setup Wizard";
        this.Size = new Size(600, 450);
    }
}

VB.NET:

Imports System
Imports System.Drawing
Imports System.Windows.Forms
Imports Syncfusion.Windows.Forms.Tools

Public Partial Class InstallationWizard
    Inherits Form
    
    Private wizardControl1 As WizardControl
    Private welcomePage As WizardControlPage
    Private licensePage As WizardControlPage
    Private installPage As WizardControlPage
    Private finishPage As WizardControlPage
    
    Public Sub New()
        InitializeComponent()
        CreateWizard()
    End Sub
    
    Private Sub CreateWizard()
        ' Create wizard control
        wizardControl1 = New WizardControl With {
            .Dock = DockStyle.Fill,
            .Style = Syncfusion.Windows.Forms.Tools.Wizard.Style.Metro
        }
        
        ' Create pages
        welcomePage = New WizardControlPage With {
            .Title = "Welcome",
            .Description = "Welcome to the Installation Wizard",
            .BackVisible = False
        }
        
        licensePage = New WizardControlPage With {
            .Title = "License Agreement",
            .Description = "Please read and accept the license terms"
        }
        
        installPage = New WizardControlPage With {
            .Title = "Installing",
            .Description = "Please wait while files are being installed"
        }
        
        finishPage = New WizardControlPage With {
            .Title = "Completed",
            .Description = "Installation completed successfully",
            .NextVisible = False,
            .CancelVisible = False,
            .FinishVisible = True
        }
        
        ' Add pages to wizard
        wizardControl1.WizardPages = New WizardControlPage() {
            welcomePage,
            licensePage,
            installPage,
            finishPage
        }
        
        ' Add wizard to form
        Me.Controls.Add(wizardControl1)
        Me.Text = "Setup Wizard"
        Me.Size = New Size(600, 450)
    End Sub
End Class

一般的なパターン

パターン 1：検証機能付きウィザード

次のページへの移動を許可する前にデータを検証します。

C#:

public partial class RegistrationWizard : Form
{
    private WizardControlPage personalInfoPage;
    private TextBox txtName;
    private TextBox txtEmail;
    
    private void SetupWizard()
    {
        personalInfoPage = new WizardControlPage
        {
            Title = "Personal Information",
            Description = "Please enter your details"
        };
        
        // Add controls to page
        txtName = new TextBox { Location = new Point(20, 20), Width = 300 };
        txtEmail = new TextBox { Location = new Point(20, 60), Width = 300 };
        
        personalInfoPage.Controls.Add(new Label 
        { 
            Text = "Name:", 
            Location = new Point(20, 0) 
        });
        personalInfoPage.Controls.Add(txtName);
        personalInfoPage.Controls.Add(new Label 
        { 
            Text = "Email:", 
            Location = new Point(20, 40) 
        });
        personalInfoPage.Controls.Add(txtEmail);
        
        // Subscribe to validation event
        personalInfoPage.ValidatePage += PersonalInfoPage_ValidatePage;
    }
    
    private void PersonalInfoPage_ValidatePage(object sender, 
        System.ComponentModel.CancelEventArgs e)
    {
        // Validate name
        if (string.IsNullOrWhiteSpace(txtName.Text))
        {
            MessageBox.Show("Please enter your name.", "Validation Error",
                MessageBoxButtons.OK, MessageBoxIcon.Warning);
            e.Cancel = true;
            txtName.Focus();
            return;
        }
        
        // Validate email
        if (string.IsNullOrWhiteSpace(txtEmail.Text) || 
            !txtEmail.Text.Contains("@"))
        {
            MessageBox.Show("Please enter a valid email address.", 
                "Validation Error",
                MessageBoxButtons.OK, MessageBoxIcon.Warning);
            e.Cancel = true;
            txtEmail.Focus();
            return;
        }
    }
}

パターン 2：動的なページシーケンス

ユーザーの選択に基づいてページの流れを制御します。

C#:

public partial class ConfigurationWizard : Form
{
    private WizardControlPage typePage;
    private WizardControlPage basicSettingsPage;
    private WizardControlPage advancedSettingsPage;
    private RadioButton rbBasic;
    private RadioButton rbAdvanced;
    
    private void SetupDynamicWizard()
    {
        typePage = new WizardControlPage
        {
            Title = "Configuration Type",
            Description = "Choose your configuration level"
        };
        
        rbBasic = new RadioButton 
        { 
            Text = "Basic Configuration", 
            Location = new Point(20, 20),
            Checked = true
        };
        rbAdvanced = new RadioButton 
        { 
            Text = "Advanced Configuration", 
            Location = new Point(20, 50) 
        };
        
        typePage.Controls.Add(rbBasic);
        typePage.Controls.Add(rbAdvanced);
        
        basicSettingsPage = new WizardControlPage
        {
            Title = "Basic Settings",
            Description = "Configure basic options"
        };
        
        advancedSettingsPage = new WizardControlPage
        {
            Title = "Advanced Settings",
            Description = "Configure advanced options"
        };
        
        // Set dynamic page sequence
        typePage.NextClick += TypePage_NextClick;
    }
    
    private void TypePage_NextClick(object sender, EventArgs e)
    {
        // Dynamically set next page based on selection
        if (rbBasic.Checked)
        {
            typePage.NextPage = basicSettingsPage;
        }
        else
        {
            typePage.NextPage = advancedSettingsPage;
        }
    }
}

パターン 3：進行状況を追跡するウィザード

バナーに現在のステップの進行状況を表示します。

C#:

public partial class DataImportWizard : Form
{
    private Label lblProgress;
    
    private void SetupProgressWizard()
    {
        // Create progress label in banner
        lblProgress = new Label
        {
            Text = "Step 1 of 4",
            Location = new Point(400, 10),
            AutoSize = true,
            Font = new Font("Arial", 9, FontStyle.Bold)
        };
        
        // Add to wizard's banner panel (assuming gradientPanel1 is banner)
        wizardControl1.BannerPanel.Controls.Add(lblProgress);
        
        // Subscribe to page changes
        wizardControl1.BeforePageSelect += WizardControl1_BeforePageSelect;
    }
    
    private void WizardControl1_BeforePageSelect(object sender, EventArgs e)
    {
        // Update progress based on current page
        int currentIndex = wizardControl1.WizardPages.IndexOf(
            wizardControl1.SelectedWizardPage);
        int totalPages = wizardControl1.WizardPages.Count;
        
        lblProgress.Text = $"Step {currentIndex + 1} of {totalPages}";
    }
}

主なプロパティ

WizardControl のプロパティ

プロパティ	型	説明
WizardPages	WizardControlPage[]	ウィザードページのコレクション
SelectedWizardPage	WizardControlPage	現在表示されているページ
BannerPanel	Panel	バナーコントロールを含むパネル
Banner	Control	バナー画像用のピクチャーボックス
Title	Label	ページタイトルを表示するラベル
Description	Label	ページの説明を表示するラベル
BackButton	Button	戻るナビゲーションボタン
NextButton	Button	次へナビゲーションボタン
CancelButton	Button	キャンセルボタン
FinishButton	Button	完了ボタン
HelpButton	Button	ヘルプボタン
Style	Wizard.Style	ビジュアルテーマ（Default、Metro、Office）
BackButtonCausesValidation	bool	戻るボタンで検証を実行するかどうか
AutoLayoutBanner	bool	バナーコントロールを自動でレイアウトするかどうか
AutoLayoutTitle	bool	タイトルラベルを自動でレイアウトするかどうか
AutoLayoutDescription	bool	説明ラベルを自動でレイアウトするかどうか

WizardControlPage のプロパティ

プロパティ	型	説明
Title	string	ページタイトルのテキスト
Description	string	ページ説明のテキスト
BackVisible	bool	戻るボタンの表示状態
NextVisible	bool	次へボタンの表示状態
CancelVisible	bool	キャンセルボタンの表示状態
FinishVisible	bool	完了ボタンの表示状態
HelpVisible	bool	ヘルプボタンの表示状態
BackEnabled	bool	戻るボタンの有効状態
NextEnabled	bool	次へボタンの有効状態
CancelEnabled	bool	キャンセルボタンの有効状態
FinishEnabled	bool	完了ボタンの有効状態
HelpEnabled	bool	ヘルプボタンの有効状態
FullPage	bool	全ページ表示用にバナーを非表示にする
NextPage	WizardPage	次のページのカスタム上書き
PreviousPage	WizardPage	前のページのカスタム上書き
CancelOverFinish	bool	キャンセルボタンを完了ボタンの位置に配置する
LayoutName	string	ページの一意な識別子

よくあるユースケース

1. インストールウィザード - ようこそ、ライセンス、オプション、インストール、完了の各ページで構成される、複数ステップのソフトウェアインストール

2. セットアップアシスタント - 初回起動時のセットアップや環境設定を行う、アプリケーションの構成ウィザード

3. 登録フォーム - 個人情報、アカウント情報、環境設定、確認を順に進める、ステップ形式のユーザー登録

4. データインポートウィザード - ソースの選択、マッピング、検証、インポートの実行をガイドするデータインポート

5. レポート生成ツール - パラメーターの選択、書式設定、プレビュー、エクスポートを行うレポート作成ウィザード

6. 構成マネージャー - 複雑な構成インターフェイスを論理的なカテゴリに分割し、ナビゲーションを備えたもの

7. チェックアウトプロセス - カート、配送、支払い、確認の各ページで構成される、E コマースのチェックアウトフロー

8. オンボーディング体験 - チュートリアルのステップ、機能紹介、セットアップの完了を含む、新規ユーザー向けオンボーディング

追加リソース

• WizardControl API ドキュメント
• コントロールの依存関係
• アセンブリ： Syncfusion.Tools.Windows.dll
• 名前空間： Syncfusion.Windows.Forms.Tools