syncfusion-winforms-autolabel

Syncfusion WinForms AutoLabel コントロール

AutoLabel コントロールは Label を参考にしたコントロールで、ラベルをほかの任意のコントロールと組み合わせることができます。組み合わせると、ラベルが付けられたコントロールの位置が変わるたびに AutoLabel が自動的に位置を調整するため、ラベルとコントロールの位置を常に同期できます。

この機能を使用する場面

次のような場合に AutoLabel コントロールを使用します。

• 関連付けられたコントロールに自動的に追従するラベルを追加する
• コントロールが移動する動的なフォームレイアウトを作成する
• FlowLayout マネージャーを使用して複雑なフォームデザインを実装する
• コントロールに対するラベルの位置を常に適切に保つ
• コントロールを動的にサイズ変更または再配置するフォームを作成する
• ラベルとコントロールの間隔が統一された、プロフェッショナルなフォームを作成する
• 自動配置によってフォームレイアウトの管理を簡素化する

インストール

NuGet によるインストール

Install-Package Syncfusion.Shared.Base

アセンブリ参照

次のアセンブリへの参照を追加します。

• Syncfusion.Shared.Base.dll

クイックスタート

基本設定

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

namespace AutoLabelDemo
{
    public partial class Form1 : Form
    {
        private AutoLabel autoLabel1;
        private TextBoxExt textBoxExt1;
        
        public Form1()
        {
            InitializeComponent();
            
            // Create a control to label (e.g., TextBox)
            textBoxExt1 = new TextBoxExt();
            textBoxExt1.Location = new System.Drawing.Point(150, 50);
            textBoxExt1.Size = new System.Drawing.Size(200, 20);
            
            // Create AutoLabel
            autoLabel1 = new AutoLabel();
            autoLabel1.Text = "Username:";
            autoLabel1.Font = new System.Drawing.Font("Segoe UI", 9F, System.Drawing.FontStyle.Regular);
            
            // Pair the label with the control
            autoLabel1.LabeledControl = textBoxExt1;
            autoLabel1.Position = AutoLabelPosition.Left;
            autoLabel1.Gap = 10;
            
            // Add to form
            this.Controls.Add(textBoxExt1);
            this.Controls.Add(autoLabel1);
        }
    }
}

デザイナーでの設定

1. ツールボックスから AutoLabel コントロールをフォームにドラッグします
2. 別のコントロール（例：TextBox）をフォームにドラッグします
3. AutoLabel を右クリックし、［Properties］を選択して、LabeledControl に対象のコントロールを設定します
4. Position と Gap のプロパティを設定します
5. ラベルがコントロールに対して自動的に配置されます

基本概念

ラベルとコントロールのペアリング

AutoLabel は LabeledControl プロパティを通じて任意のコントロールとペアになります。ペアになると、ラベルはコントロールの位置を自動的に追跡します。

自動的な位置調整

ラベルが付けられたコントロールが移動すると、AutoLabel は Position と Gap の設定に基づいて自動的に位置を調整します。

FlowLayout との連携

FlowLayout マネージャーは、AutoLabel とラベルが付けられたコントロールのペアを単一のまとまりとして扱い、柔軟な動的フォームレイアウトを実現します。

ナビゲーションガイド

🚀 はじめに

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

• インストールとアセンブリの配置
• デザイナーでの AutoLabel の追加
• プログラムによる AutoLabel の追加
• コントロールへのラベル付け
• 基本設定
• 最初の AutoLabel アプリケーションの実行

📐 位置と間隔

📄 参照先： references/positioning-spacing.md

• Position プロパティ（Left、Top、Side、Custom）
• ラベルとコントロールの間隔を設定する Gap
• 細かな調整に使う DX プロパティと DY プロパティ
• マウスによるカスタム配置
• 間隔設定のベストプラクティス

🎨 外観とテーマ設定

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

• ラベルのサイズを自動調整する AutoSize
• BackColor と ForeColor のカスタマイズ
• フォント設定
• TextAlign プロパティ
• SkinManager によるテーマ設定（Office 2016 スタイル）
• ビジュアルスタイル

⚡ イベント

📄 参照先： references/events.md

• PropertyChanged イベント
• ラベルとコントロールの更新処理
• イベント引数
• 一般的なイベントの使用例

🎯 概要と使用例

📄 参照先： references/overview.md

• コンポーネントのアーキテクチャ
• FlowLayout との連携
• フォームレイアウトのパターン
• AutoLabel と標準の Label の使い分け

一般的なパターン

パターン 1：ラベルを左揃えにしたシンプルなフォーム

// Create form fields with left-aligned labels
AutoLabel nameLabel = new AutoLabel();
nameLabel.Text = "Name:";
nameLabel.LabeledControl = nameTextBox;
nameLabel.Position = AutoLabelPosition.Left;
nameLabel.Gap = 10;

AutoLabel emailLabel = new AutoLabel();
emailLabel.Text = "Email:";
emailLabel.LabeledControl = emailTextBox;
emailLabel.Position = AutoLabelPosition.Left;
emailLabel.Gap = 10;

this.Controls.Add(nameTextBox);
this.Controls.Add(nameLabel);
this.Controls.Add(emailTextBox);
this.Controls.Add(emailLabel);

パターン 2：ラベルを上揃えにしたフォーム（縦型フォーム）

AutoLabel addressLabel = new AutoLabel();
addressLabel.Text = "Address:";
addressLabel.LabeledControl = addressTextBox;
addressLabel.Position = AutoLabelPosition.Top;
addressLabel.Gap = 5;
addressLabel.AutoSize = true;

パターン 3：ラベルのカスタム配置

AutoLabel customLabel = new AutoLabel();
customLabel.Text = "Custom:";
customLabel.LabeledControl = myControl;
customLabel.Position = AutoLabelPosition.Custom;
customLabel.DX = -100;  // 100 pixels to the left
customLabel.DY = 15;    // 15 pixels down from control top

パターン 4：AutoLabel を使ったテーマ設定済みフォーム

using Syncfusion.Windows.Forms;

// Apply Office 2016 theme to all labels
SkinManager.SetVisualStyle(label1, VisualTheme.Office2016Colorful);
SkinManager.SetVisualStyle(label2, VisualTheme.Office2016Colorful);
SkinManager.SetVisualStyle(label3, VisualTheme.Office2016Colorful);

パターン 5：AutoLabel ペアを使った FlowLayout

FlowLayoutPanel flowPanel = new FlowLayoutPanel();
flowPanel.FlowDirection = FlowDirection.TopDown;
flowPanel.Dock = DockStyle.Fill;

// FlowLayout treats AutoLabel + Control as one unit
flowPanel.Controls.Add(firstNameTextBox);
flowPanel.Controls.Add(firstNameLabel);  // Paired with firstNameTextBox
flowPanel.Controls.Add(lastNameTextBox);
flowPanel.Controls.Add(lastNameLabel);   // Paired with lastNameTextBox

// Labels automatically move with their controls
this.Controls.Add(flowPanel);

主要プロパティのリファレンス

プロパティ	型	デフォルト	説明
LabeledControl	Control	null	このラベルが対応するコントロール
Position	AutoLabelPosition	Left	相対位置：Left、Top、Side、Custom
Gap	int	0	ラベルとコントロール間の水平および垂直方向の間隔
DX	int	0	ラベルの左端からコントロールの左端までの水平方向の距離
DY	int	0	ラベルの上端からコントロールの上端までの垂直方向の距離
AutoSize	bool	false	フォントサイズに応じて自動的にサイズを変更します
Text	string	""	ラベルのテキスト内容
TextAlign	ContentAlignment	TopLeft	ラベル内のテキストの配置
BackColor	Color	Control	ラベルの背景色
ForeColor	Color	ControlText	ラベルのテキスト色
Font	Font	-	ラベルのテキストに使用するフォント

位置オプション

位置	動作
Left	ラベルをコントロールの左側に表示します
Top	ラベルをコントロールの上側に表示します
Side	ラベルをコントロールの横（右側）に表示します
Custom	DX と DY、またはマウスでのドラッグを使用して手動で位置を指定します

イベント

イベント	説明
PropertyChanged	LabeledControl、Gap、Position のプロパティが変更されたときに発生します

ベストプラクティス

1. 追加する前にペアを設定する：適切に初期化するため、フォームに追加する前に LabeledControl を設定します

2. 間隔には Gap を使用する：一貫した間隔を保つため、手動で位置を指定する代わりに Gap プロパティを使用します

3. 適切な位置を選択する：

   • 横方向のフォームでは Left を使用します
   • 縦方向に積み重ねるフォームでは Top を使用します
   • 必要な場合に限り Custom を使用します

4. AutoSize を有効にする：テキストを折り返さないラベルでは、AutoSize = true を設定します

5. FlowLayout との連携：FlowLayout を活用して、ラベルとコントロールのペアをひとまとまりとして扱います

6. テーマを統一する：フォーム内のすべての AutoLabel に同じビジュアルスタイルを適用します

7. 移動をテストする：コントロールの位置を動的に変更したとき、ラベルが追従することを確認します

8. 重なりを避ける：Gap と位置の設定により、ラベルとコントロールが重ならないようにします

ビジュアルスタイル

SkinManager でサポートされているテーマ：

• Office2016Colorful
• Office2016Black
• Office2016DarkGray
• Office2016White

SkinManager.SetVisualStyle(this.autoLabel1, VisualTheme.Office2016Colorful);

フレームワークのサポート

• .NET Framework 4.5 以降
• .NET 6.0、.NET 7.0、.NET 8.0（Windows）
• .NET Core 3.1（Windows）

追加リソース

• Syncfusion AutoLabel のドキュメント
• API リファレンス
• ナレッジベースの記事
• GitHub のサンプル

トラブルシューティング

問題：ラベルがコントロールと一緒に移動しない

• LabeledControl プロパティが設定されていることを確認します
• ラベルとコントロールの両方が同じコンテナーに追加されていることを確認します
• コントロールの位置が実際に変更されていることを確認します

問題：ラベルの位置がずれている

• 間隔を調整するには Gap プロパティを変更します
• 必要に応じて DX と DY を使用して微調整します
• Position プロパティが正しく設定されていることを確認します

問題：ラベルがコントロールに重なる

• Gap の値を大きくします
• 別の Position を選択します（例：Left ではなく Top）
• コントロールのサイズに十分な余裕があることを確認します

問題：テーマが適用されない

• SkinManager アセンブリが参照されていることを確認します
• テーマがサポートされていることを確認します（Office 2016 のバリエーションのみ）
• コントロールをフォームに追加した後でテーマを適用します