syncfusion-winforms-form

Windows Forms（SfForm）の実装

Syncfusion の SfForm は、Windows Forms アプリケーション向けの高度なウィンドウコントロールです。フォームの外観を包括的にカスタマイズでき、タイトルバーにカスタムユーザーインターフェイスを配置できるほか、包括的な MDI（マルチドキュメントインターフェイス）をサポートします。

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

次のような場合は、SfForm を使用します。

• タイトルバーの外観をカスタマイズする - 色、テキストの配置、ボタンのスタイル、カスタムアイコン
• タイトルバーにカスタムコントロールを読み込む - 検索ボックス、ナビゲーションコントロール、任意のユーザーコントロールを追加する
• MDI アプリケーションを構築する - 複数の子ウィンドウを持つ親フォーム
• プロフェッショナルなテーマを適用する - Office 2016/2019 およびハイコントラストの組み込みテーマ
• フォームの境界線をカスタマイズする - アクティブ／非アクティブ状態、色、太さ、角丸
• 影の効果を追加する - モダンな外観に合わせて影の不透明度をカスタマイズする
• タイトルバーでリッチテキストをサポートする - フォームのタイトルに書式設定されたテキストを表示する
• フォーム要素をローカライズする - グローバルアプリケーション向けに多言語をサポートする

SfForm、MetroForm、Office2007Form の比較：

• カスタムのタイトルバーコントロールと外観全体の制御が必要なモダンなアプリケーションには、SfForm を使用します
• 組み込みスキンでキャプション画像とラベルのみが必要な場合は、MetroForm を使用します
• 組み込みの配色で Microsoft Office 2007 スタイルの UI が必要な場合は、Office2007Form を使用します

主な機能

• タイトルバーのカスタマイズ - 高さ、色、テキストの配置、ボタンのカスタマイズ
• ユーザーコントロールの読み込み - 任意の WinForms コントロールをタイトルバーに配置
• MDI のサポート - 親フォームと子フォームの包括的な管理
• 境界線のカスタマイズ - アクティブ／非アクティブ状態の境界線の色と太さ
• テーマのサポート - 6 種類の組み込みプロフェッショナルテーマ
• リッチテキストのサポート - タイトルバーのテキストで RTF 書式を使用
• 影の効果 - 影の不透明度を調整可能
• 角丸 - Windows 11 スタイルの角丸
• ローカライズ - リソースファイルを完全にサポート

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

はじめに

📄 参照： references/getting-started.md

• アセンブリの配置と依存関係
• 標準の Form から SfForm への変換
• 基本的な設定と初期化
• 初期カスタマイズの例
• タイトルバーへのユーザーコントロールの読み込み

タイトルバーのカスタマイズ

📄 参照： references/titlebar-customization.md

• タイトルバーの高さの調整
• テキストの配置（水平および垂直）
• タイトルバーボタンのカスタマイズ（アイコン、色、状態）
• ボタン（最小化、最大化、閉じる）の非表示
• タイトルバーのテキストのリッチテキスト書式設定
• タイトルバーへのユーザーコントロールの読み込み
• アイコンとキャプションのカスタマイズ

フォームのカスタマイズ

📄 参照： references/form-customization.md

• フォームアイコンの設定と配置
• 境界線のカスタマイズ（アクティブ／非アクティブ状態）
• 影の効果の設定
• 影の不透明度の設定
• 角丸（Windows 11 以降）

MDI のカスタマイズ

📄 参照： references/mdi-customization.md

• MDI 親フォームの作成
• MDI 子フォームの追加
• 子フォームの外観のカスタマイズ
• アクティブな MDI 子フォームの取得
• MDI 子フォームのキーイベント処理

テーマ設定

📄 参照： references/theming.md

• テーマアセンブリの読み込み
• フォームへのテーマの適用
• 利用可能なテーマ（Office2016/2019、HighContrast）
• テーマのカスタマイズオプション

ローカライズ

📄 参照： references/localization.md

• ローカライズ用リソースファイルの作成
• カルチャと UI カルチャの設定
• サンプルレベルでのローカライズ
• 既定のリソースファイルの編集
• アセンブリ／名前空間のさまざまな構成

クイックスタート

手順 1：アセンブリ参照の追加

次の参照をプロジェクトに追加します。

• Syncfusion.Core.WinForms.dll
• Syncfusion.Shared.Base.dll

手順 2：Form を SfForm に変換

using Syncfusion.WinForms.Controls;

namespace MyApplication
{
    public partial class Form1 : SfForm  // Change from Form to SfForm
    {
        public Form1()
        {
            InitializeComponent();
            
            // Basic customization
            this.Style.TitleBar.BackColor = Color.FromArgb(46, 46, 46);
            this.Style.TitleBar.ForeColor = Color.White;
        }
    }
}

VB.NET：

Imports Syncfusion.WinForms.Controls

Public Class Form1
    Inherits SfForm  ' Change from Form to SfForm
    
    Public Sub New()
        InitializeComponent()
        
        ' Basic customization
        Me.Style.TitleBar.BackColor = Color.FromArgb(46, 46, 46)
        Me.Style.TitleBar.ForeColor = Color.White
    End Sub
End Class

手順 3：外観のカスタマイズ

// Title bar button colors
this.Style.TitleBar.CloseButtonForeColor = Color.White;
this.Style.TitleBar.MinimizeButtonForeColor = Color.White;
this.Style.TitleBar.MaximizeButtonForeColor = Color.White;

// Button hover colors
this.Style.TitleBar.CloseButtonHoverBackColor = Color.Red;
this.Style.TitleBar.MinimizeButtonHoverBackColor = Color.DarkGray;
this.Style.TitleBar.MaximizeButtonHoverBackColor = Color.DarkGray;

// Form border
this.Style.Border = new Pen(Color.FromArgb(0, 122, 204), 2);
this.Style.InactiveBorder = new Pen(Color.Gray, 2);

よくあるパターン

パターン 1：ダークテーマのフォーム

public Form1()
{
    InitializeComponent();
    
    // Dark title bar
    this.Style.TitleBar.BackColor = Color.FromArgb(30, 30, 30);
    this.Style.TitleBar.ForeColor = Color.White;
    this.Style.TitleBar.Height = 35;
    
    // Button styling
    this.Style.TitleBar.CloseButtonForeColor = Color.White;
    this.Style.TitleBar.CloseButtonHoverBackColor = Color.FromArgb(232, 17, 35);
    this.Style.TitleBar.MinimizeButtonForeColor = Color.White;
    this.Style.TitleBar.MaximizeButtonForeColor = Color.White;
    
    // Border and shadow
    this.Style.Border = new Pen(Color.FromArgb(0, 122, 204), 2);
    this.Style.ShadowOpacity = 150;
    
    // Client area
    this.Style.BackColor = Color.FromArgb(45, 45, 48);
}

パターン 2：検索コントロール付きのカスタムタイトルバー

public Form1()
{
    InitializeComponent();
    
    // Create search panel
    FlowLayoutPanel searchPanel = new FlowLayoutPanel();
    searchPanel.Size = new Size(250, 28);
    searchPanel.FlowDirection = FlowDirection.LeftToRight;
    
    // Add search label
    Label searchLabel = new Label();
    searchLabel.Text = "Search:";
    searchLabel.ForeColor = Color.White;
    searchLabel.AutoSize = true;
    searchLabel.Margin = new Padding(5, 5, 5, 0);
    
    // Add search textbox
    TextBox searchBox = new TextBox();
    searchBox.Width = 180;
    searchBox.Margin = new Padding(5, 2, 0, 0);
    
    searchPanel.Controls.Add(searchLabel);
    searchPanel.Controls.Add(searchBox);
    
    // Load to title bar
    this.TitleBarTextControl = searchPanel;
    
    // Style title bar
    this.Style.TitleBar.BackColor = Color.FromArgb(0, 120, 215);
    this.Style.TitleBar.Height = 35;
}

パターン 3：子フォームを持つ MDI 親フォーム

// Parent Form
public class MainForm : SfForm
{
    public MainForm()
    {
        InitializeComponent();
        
        // Enable MDI container
        this.IsMdiContainer = true;
        
        // Customize parent appearance
        this.Style.TitleBar.BackColor = Color.FromArgb(0, 122, 204);
        this.Style.TitleBar.ForeColor = Color.White;
    }
    
    private void CreateChildForm()
    {
        // Create child form
        SfForm childForm = new SfForm();
        childForm.Text = "Child Window 1";
        childForm.MdiParent = this;
        
        // Customize child appearance
        childForm.Style.TitleBar.BackColor = Color.White;
        childForm.Style.TitleBar.ForeColor = Color.Black;
        childForm.Style.Border = new Pen(Color.LightGray, 1);
        
        childForm.Show();
    }
}

パターン 4：組み込みテーマを適用する

// In Program.cs
static class Program
{
    [STAThread]
    static void Main()
    {
        // Register Syncfusion license
        Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY");
        
        // Load theme assemblies
        SfSkinManager.LoadAssembly(typeof(Office2016Theme).Assembly);
        SfSkinManager.LoadAssembly(typeof(Office2019Theme).Assembly);
        
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.Run(new Form1());
    }
}

// In Form
public Form1()
{
    InitializeComponent();
    
    // Apply theme
    this.ThemeName = "Office2016Colorful";
}

パターン 5：ローカライズされたフォーム

public Form1()
{
    // Set culture before initialization
    System.Threading.Thread.CurrentThread.CurrentCulture = 
        new System.Globalization.CultureInfo("de-DE");
    System.Threading.Thread.CurrentThread.CurrentUICulture = 
        new System.Globalization.CultureInfo("de-DE");
    
    InitializeComponent();
}

主なプロパティ

フォームのプロパティ

• Style - 外観をカスタマイズするすべてのオプションにアクセスします
• TitleBarTextControl - タイトルバーにカスタムユーザーコントロールを読み込みます
• AllowRoundedCorners - Windows 11 スタイルの角丸を有効にします（bool）
• ThemeName - 組み込みテーマを適用します（string）
• IsMdiContainer - MDI 親モードを有効にします（bool）

タイトルバーのプロパティ（Style.TitleBar）

• Height - タイトルバーの高さ（int）
• BackColor - タイトルバーの背景色
• ForeColor - タイトルバーのテキスト色
• TextHorizontalAlignment - 左、中央、右
• TextVerticalAlignment - 上、中央、下
• IconHorizontalAlignment - アイコンの水平方向の位置
• IconVerticalAlignment - アイコンの垂直方向の位置
• AllowRichText - RTF 書式設定を有効にします（bool）

ボタンのプロパティ（Style.TitleBar）

• CloseButtonForeColor - 閉じるボタンのアイコン色
• MinimizeButtonForeColor - 最小化ボタンのアイコン色
• MaximizeButtonForeColor - 最大化ボタンのアイコン色
• CloseButtonHoverBackColor - 閉じるボタンのホバー時の背景色
• CloseButtonPressedBackColor - 閉じるボタンの押下時の背景色
• CloseButtonImage - カスタムの閉じるボタンアイコン
• CloseButtonHoverImage - カスタムの閉じるボタンのホバー時アイコン
• CloseButtonPressedImage - カスタムの閉じるボタンの押下時アイコン

境界線と影のプロパティ（Style）

• Border - アクティブ状態の境界線（Pen）
• InactiveBorder - 非アクティブ状態の境界線（Pen）
• ShadowOpacity - アクティブ状態の影の不透明度（0～255）
• InactiveShadowOpacity - 非アクティブ状態の影の不透明度（0～255）

一般的なユースケース

ユースケース 1：カスタムタイトルバーを備えたモダンなアプリケーション

シナリオ： タイトルバーにブランド要素を配置した、モダンなデスクトップアプリケーションを構築します
解決策： TitleBarTextControl を使用して、ロゴやナビゲーションコントロールを備えたパネルを読み込みます
参考資料： titlebar-customization.md

ユースケース 2：MDI 対応のドキュメントエディター

シナリオ： 複数のドキュメントを同時に開けるテキストエディターを作成します
解決策： MDI 親フォームを使用し、各ドキュメントに子フォームを割り当てます
参考資料： mdi-customization.md

ユースケース 3：一貫したブランド要素を持つエンタープライズアプリケーション

シナリオ： アプリケーション内のすべてのフォームに会社のテーマを適用します
解決策： 組み込みテーマを使用するか、Style プロパティでカスタムテーマを作成します
参考資料： theming.md

ユースケース 4：多言語アプリケーション

シナリオ： 海外のユーザー向けに複数の言語をサポートします
解決策： リソースファイルを使用してローカライズを実装します
参考資料： localization.md

ユースケース 5：ミニマリストなフォームデザイン

シナリオ： UI を最小限に抑えた、すっきりとした邪魔の入らないフォームを作成します
解決策： タイトルバーのボタンを非表示にし、カスタムカラーを使用して、控えめな影を追加します
参考資料： form-customization.md

他のフォームコントロールとの比較

機能	SfForm	MetroForm	Office2007Form
カスタムタイトルバーコントロール	✅ はい	❌ いいえ	❌ いいえ
MDI サポート	✅ はい	✅ はい	✅ はい
アクティブ／非アクティブ境界線	✅ はい	⚠️ 制限あり	⚠️ 制限あり
リッチテキストのタイトル	✅ はい	❌ いいえ	❌ いいえ
影のカスタマイズ	✅ はい	❌ いいえ	❌ いいえ
角丸	✅ はい（Win11 以降）	❌ いいえ	❌ いいえ
テーマのサポート	✅ 6 種類のテーマ	✅ 組み込みスキン	✅ Office スキーム
キャプション画像	✅ はい	✅ はい	✅ はい

推奨： 柔軟性と最新機能を最大限に活用するには、SfForm を使用してください。MetroForm または Office2007Form は、レガシーアプリケーションや特定のスタイル要件がある場合にのみ使用してください。

ヒントとベストプラクティス

パフォーマンス

• フォームを表示する前に、コンストラクターですべてのスタイルプロパティを設定します
• 複数のコントロールを追加する場合は、SuspendLayout()/ResumeLayout() を使用します
• カスタム画像やリソースは適切に破棄します

デザイン

• 見た目を最適にするため、タイトルバーの高さを 30～40 ピクセルに保ちます
• プロフェッショナルな外観にするため、控えめな影（不透明度 100～150）を使用します
• タイトルバーとボタンの間に十分なコントラストを確保します
• カスタムタイトルバーのコントロールをさまざまな DPI 設定でテストします

MDI アプリケーション

• 子フォームを作成する前に IsMdiContainer = true を設定します
• すべての子フォームに一貫したスタイルを適用します
• 現在の子ウィンドウを管理するには ActiveMdiChild を使用します
• ウィンドウ管理にメニューストリップを使用することを検討します

テーマの使用

• フォームを作成する前に、Program.cs でテーマアセンブリを読み込みます
• アプリケーション内のすべてのフォームに一貫したテーマを適用します
• アクセシビリティのため、HighContrast テーマでテストします
• テーマ適用フォームとテーマ未適用フォームを混在させないでください

アクセシビリティ

• タイトルバーのテキストに十分な色のコントラストを確保します
• すべてのカスタムコントロールでキーボードナビゲーションをサポートします
• Windows のハイコントラスト設定でテストします
• カスタムタイトルバーのコントロールがアクセシブルであることを確認します

トラブルシューティング

タイトルバーのカスタムコントロールが表示されない：

• コントロールのサイズがタイトルバーの高さに収まっていることを確認します
• コントロールの Visible プロパティが true であることを確認します
• 背景色が透明になっていないことを確認します

テーマが適用されない：

• Program.cs でテーマアセンブリが読み込まれていることを確認します
• テーマ名のスペル（大文字と小文字を区別）を確認します
• InitializeComponent() の後に ThemeName が設定されていることを確認します

MDI 子フォームが表示されない：

• 親フォームの IsMdiContainer = true を確認します
• 子フォームの MdiParent が正しく設定されていることを確認します
• 子フォームが .Show() で表示され、.ShowDialog() ではないことを確認します

境界線が表示されない：

• FormBorderStyle が None でないことを確認します
• Border ペンの幅が 0 より大きいことを確認します
• 境界線の色と背景色にコントラストがあることを確認します

関連コンポーネント

• MetroForm - Metro スタイルが組み込まれた別のフォーム
• Office2007Form - Office 2007 の外観を備えた別のフォーム
• Ribbon - タイトルバー領域に Office スタイルのリボンインターフェイスを表示します
• SfSkinManager - テーマをグローバルに適用します

その他のリソース

• API リファレンス： SfForm Class Documentation
• サンプルアプリケーション： 完全な例については、インストールディレクトリを確認してください
• サポート： Syncfusion Community Forums