syncfusion-winforms-textbox

テキストボックスの実装（TextBoxExt）

Windows Forms 用の拡張テキストボックスコントロールです。境界線のカスタムスタイル、Office テーマ、複数行テキスト、文字の大文字・小文字の変換、オーバーフローインジケーター、外観の詳細なカスタマイズに対応しています。

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

以下が必要な場合に、このスキルを使用してください。

• 拡張テキストボックス：標準の TextBox を、スタイルやテーマに対応した代替コントロールに置き換える
• カスタム境界線：境界線の色、3D スタイル、境界線を表示する辺の設定をカスタマイズする
• Office テーマ：テキストボックスの外観を Office 2016／2019 または Metro アプリケーションのテーマに合わせる
• 複数行テキスト：ワードラップ、スクロールバー、オーバーフローインジケーターを備えた複数行テキストを表示する
• テキストの書式設定：文字の大文字・小文字（大文字／小文字）、テキストの配置、RTL レイアウトを制御する
• 読み取り専用の表示：ラベルや編集不可の表示用に、スタイル設定された読み取り専用のテキストフィールドを作成する
• オーバーフローのツールチップ：テキストがテキストボックスの境界を超えたときにツールチップを表示する
• サイズ制約：テキストボックスの最小サイズまたは最大サイズを設定する

コンポーネントの概要

TextBoxExt は、標準の TextBox を継承した高度なテキストボックスコントロールで、以下の機能を備えています。

• 境界線の色と 3D 境界線スタイルのカスタマイズ
• 8 種類の組み込みビジュアルテーマ（Office2016、Office2019、Metro、Office2007、Office2010、Default）
• SkinManager とのテーマアセンブリ連携
• ワードラップと設定可能なスクロールバーに対応した複数行テキスト
• 文字の大文字・小文字の変換（Upper、Lower、Normal）
• テキストの配置（Left、Center、Right）
• 国際対応アプリケーション向けの右から左へのレイアウト
• カスタマイズ可能なツールチップ付きのオーバーフローインジケーター
• サイズ制約（MaximumSize／MinimumSize）
• 無効時も描画を有効にする ReadOnly モード
• カスタマイズ用の 12 個のプロパティ変更イベント

主な機能：

• カスタム境界線を設定する BorderColor と BorderStyle
• ビジュアルテーマを選択する Style プロパティ
• 実行時にテーマを切り替える ThemeName プロパティ
• 大文字・小文字を自動変換する CharacterCasing
• テキストのオーバーフローを検出する ShowOverflowIndicator
• 入力文字数を制限する MaxLength
• 無効時もアクティブな外観を維持する DrawActiveWhenDisabled

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

はじめに

📄 参照： references/getting-started.md

参照するタイミング： 新しい実装を始めるとき、依存関係を設定するとき、初めて使用するとき、基本的なテキストボックスを作成するとき

説明するトピック：

• アセンブリの配置（Syncfusion.Shared.Base.dll）
• NuGet パッケージのインストール（Syncfusion.Shared.WinForms）
• 名前空間の要件（Syncfusion.Windows.Forms.Tools）
• デザイナーを使用した TextBoxExt の追加（ドラッグ＆ドロップ）
• プログラムによる TextBoxExt の追加
• TextBoxExt の基本的なインスタンス化と設定
• サイズの設定（MaximumSize／MinimumSize）
• ワードラップとスクロールバーを使用した複数行テキストの設定
• 初期テキストの表示

---

テキストの設定

📄 参照： references/text-configuration.md

参照するタイミング： テキストのプロパティ、複数行テキスト、文字の大文字・小文字、配置、オーバーフローインジケーター、RTL 対応を設定するとき

説明するトピック：

• Text プロパティと SelectedText プロパティ
• CharacterCasing（大文字・小文字の変換：Upper、Lower、Normal）
• TextAlign（配置：Left、Center、Right）
• アラビア語／ヘブライ語アプリケーション向けの RightToLeft レイアウト
• DrawActiveWhenDisabled（無効時もアクティブな外観を維持）
• 複数行テキストの設定
• 行を折り返すための WordWrap プロパティ
• ScrollBars（Horizontal、Vertical、Both、None）
• オーバーフローインジケーター（ShowOverflowIndicator プロパティ）
• オーバーフロー時のツールチップのカスタマイズ（OverflowIndicatorToolTipText）
• テキスト操作メソッド（AppendText、Cut、Copy、Paste、Select、SelectAll）
• キャレットの位置を設定する ScrollToCaret() メソッド

---

境界線の設定

📄 参照: references/border-settings.md

参照するタイミング: 境界線の外観のカスタマイズ、境界線の色の適用、3D 境界線の設定、境界線の辺の選択

対象トピック:

• BorderStyle プロパティ（Fixed3D、FixedSingle、None）
• Border3DStyle プロパティ（Raised、Sunken、Etched など）
• Color 値を使用した BorderColor のカスタマイズ
• BorderSides の設定（All、Top、Bottom、Left、Right、組み合わせ）
• コードを含む境界線の完全な例
• 境界線のカスタマイズパターン
• 境界線とアプリケーションのテーマの統一

---

外観とスタイル

📄 参照: references/appearance-styling.md

参照するタイミング: ビジュアルテーマの適用、色のカスタマイズ、Office スタイルの選択

対象トピック:

• 背景のカスタマイズに使用する BackColor プロパティ
• 文字色を指定する ForeColor プロパティ
• Style プロパティの概要
• 8 種類の組み込みビジュアルスタイル:
  • Office2016Colorful
  • Office2016White
  • Office2016Black
  • Office2016DarkGray
  • Office2019Colorful
  • Metro（フラットでモダンなデザイン）
  • Office2007（クラシックな Ribbon スタイル）
  • Office2010（洗練された Office の外観）
  • Default（標準の外観）
• ビジュアルスタイルの選択と設定
• スタイルの比較例
• テキストボックスのスタイルとアプリケーションのデザインの統一

---

テーマの設定

📄 参照: references/themes-configuration.md

参照するタイミング: テーマアセンブリの読み込み、アプリケーション全体のテーマ設定、実行時のテーマ切り替え、高度なテーマ設定

対象トピック:

• ThemesEnabled プロパティ（Fixed3D 境界線の XP テーマ）
• 実行時のテーマ選択に使用する ThemeName プロパティ
• テーマアセンブリの読み込み要件
  • Syncfusion.Office2016Theme.WinForms（4 種類）
  • Syncfusion.Office2019Theme.WinForms
  • Syncfusion.HighContrastTheme.WinForms
• SkinManager.LoadAssembly() メソッド
• Program.Main() でのテーマの読み込み
• Office2016 テーマのバリエーション（Colorful、White、Black、DarkGray）
• Office2019Colorful テーマ
• アクセシビリティ対応の HighContrastBlack テーマ
• アプリケーション全体のテーマ設定
• 実行時のテーマ切り替え
• コントロール間のテーマの統一

---

動作とイベント

📄 参照: references/behavior-events.md

参照するタイミング: 動作プロパティの設定、イベントの処理、入力制限の適用、プロパティ変更への応答

対象トピック:

• MaxLength プロパティ（入力文字数の制限）
• ReadOnly モード（テキスト編集の防止）
• レイアウト設定（MaximumSize、MinimumSize）
• 12 種類のプロパティ変更イベント:
  • Border3DStyleChanged
  • BorderColorChanged
  • BorderSidesChanged
  • BorderStyleChanged
  • CharacterCasingChanged
  • HideSelectionChanged
  • MaximumSizeChanged
  • MinimumSizeChanged
  • MultilineChanged
  • ReadOnlyChanged
  • TextAlignChanged
  • ThemesEnabledChanged
• イベントハンドラーの実装パターン
• イベント駆動型のカスタマイズ
• 検証と入力制御のシナリオ
• 動的なプロパティ更新

---

クイックスタートの例

カスタム境界線付きの基本的なテーマ設定済みテキストボックス

C#:

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

// Create TextBoxExt instance
TextBoxExt textBoxExt1 = new TextBoxExt();
textBoxExt1.Location = new Point(50, 50);
textBoxExt1.Size = new Size(300, 25);
textBoxExt1.Text = "Enter your text here";

// Apply Office2016 Colorful theme
textBoxExt1.Style = TextBoxExt.theme.Office2016Colorful;

// Customize border
textBoxExt1.BorderColor = Color.FromArgb(0, 120, 215); // Blue border
textBoxExt1.BorderStyle = System.Windows.Forms.BorderStyle.FixedSingle;

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

VB.NET:

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

' Create TextBoxExt instance
Dim textBoxExt1 As New TextBoxExt()
textBoxExt1.Location = New Point(50, 50)
textBoxExt1.Size = New Size(300, 25)
textBoxExt1.Text = "Enter your text here"

' Apply Office2016 Colorful theme
textBoxExt1.Style = TextBoxExt.theme.Office2016Colorful

' Customize border
textBoxExt1.BorderColor = Color.FromArgb(0, 120, 215) ' Blue border
textBoxExt1.BorderStyle = System.Windows.Forms.BorderStyle.FixedSingle

' Add to form
Me.Controls.Add(textBoxExt1)

---

よく使われるパターン

パターン 1: オーバーフローインジケーター付きの複数行テキストエディター

シナリオ: メモやコメント用に、スクロールバーとオーバーフロー時のツールチップを備えた複数行テキストボックスを作成します

C#:

using Syncfusion.Windows.Forms.Tools;

TextBoxExt notesTextBox = new TextBoxExt();
notesTextBox.Location = new System.Drawing.Point(20, 20);
notesTextBox.Size = new System.Drawing.Size(400, 200);

// Enable multiline with word wrap
notesTextBox.Multiline = true;
notesTextBox.WordWrap = true;
notesTextBox.ScrollBars = System.Windows.Forms.ScrollBars.Vertical;

// Configure overflow indicator
notesTextBox.ShowOverflowIndicator = true;
notesTextBox.ShowOverflowIndicatorToolTip = true;
notesTextBox.OverflowIndicatorToolTipText = "Text content exceeds visible area. Scroll to view more.";

// Apply Metro theme
notesTextBox.Style = TextBoxExt.theme.Metro;

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

---

パターン 2: アクティブな外観の読み取り専用表示フィールド

シナリオ: 無効になっていてもアクティブに見える、読み取り専用の情報（計算値やステータスなど）を表示します

C#:

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

TextBoxExt displayField = new TextBoxExt();
displayField.Location = new System.Drawing.Point(150, 100);
displayField.Size = new System.Drawing.Size(250, 25);
displayField.Text = "Total: $1,234.56";

// Make readonly but keep active appearance
displayField.ReadOnly = true;
displayField.DrawActiveWhenDisabled = true;

// Apply custom styling
displayField.BackColor = Color.WhiteSmoke;
displayField.ForeColor = Color.DarkGreen;
displayField.BorderColor = Color.LightGray;
displayField.BorderStyle = System.Windows.Forms.BorderStyle.FixedSingle;

// Align text to right (common for currency)
displayField.TextAlign = System.Windows.Forms.HorizontalAlignment.Right;

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

---

パターン 3: 文字数制限付きの大文字入力フィールド

シナリオ: 入力を自動的に大文字に変換する入力フィールドを作成します（製品コードやライセンスキーなど）

C#:

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

TextBoxExt productCodeBox = new TextBoxExt();
productCodeBox.Location = new System.Drawing.Point(120, 80);
productCodeBox.Size = new System.Drawing.Size(200, 25);

// Enforce uppercase and length
productCodeBox.CharacterCasing = System.Windows.Forms.CharacterCasing.Upper;
productCodeBox.MaxLength = 10;

// Apply Office2019 theme
productCodeBox.Style = TextBoxExt.theme.Office2019Colorful;

// Customize border
productCodeBox.BorderColor = Color.SteelBlue;
productCodeBox.BorderStyle = System.Windows.Forms.BorderStyle.FixedSingle;

// Center align for codes
productCodeBox.TextAlign = System.Windows.Forms.HorizontalAlignment.Center;

// Add placeholder behavior
productCodeBox.ForeColor = Color.Gray;
productCodeBox.Text = "ENTER-CODE";

productCodeBox.Enter += (s, e) => {
    if (productCodeBox.Text == "ENTER-CODE")
    {
        productCodeBox.Text = "";
        productCodeBox.ForeColor = Color.Black;
    }
};

productCodeBox.Leave += (s, e) => {
    if (string.IsNullOrWhiteSpace(productCodeBox.Text))
    {
        productCodeBox.Text = "ENTER-CODE";
        productCodeBox.ForeColor = Color.Gray;
    }
};

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

---

主なプロパティ

外観プロパティ

プロパティ	型	説明
Style	TextBoxExt.theme	ビジュアルテーマ：Office2016Colorful、Office2016White、Office2016Black、Office2016DarkGray、Office2019Colorful、Metro、Office2007、Office2010、Default
ThemeName	string	実行時のテーマ名（テーマアセンブリの読み込みが必要です）
BackColor	Color	テキストボックスの背景色
ForeColor	Color	テキストの色
BorderStyle	BorderStyle	境界線のスタイル：Fixed3D、FixedSingle、None
BorderColor	Color	カスタム境界線の色
Border3DStyle	Border3DStyle	3D 境界線の効果：Raised、Sunken、Etched など
BorderSides	Border3DSide	境界線の辺：All、Top、Bottom、Left、Right

テキストプロパティ

プロパティ	型	説明
Text	string	テキストボックスの内容
SelectedText	string	現在選択されているテキスト
CharacterCasing	CharacterCasing	大文字・小文字の変換：Normal、Upper、Lower
TextAlign	HorizontalAlignment	テキストの配置：Left、Center、Right
RightToLeft	RightToLeft	右から左へのレイアウト：Yes、No
DrawActiveWhenDisabled	bool	コントロールが無効な場合も、テキストを有効状態として描画します

複数行プロパティ

プロパティ	型	説明
Multiline	bool	複数行のテキスト表示を有効にします
WordWrap	bool	テキストを自動的に次の行へ折り返します
ScrollBars	ScrollBars	スクロールバーの表示：None、Horizontal、Vertical、Both

オーバーフローインジケーターのプロパティ

プロパティ	型	説明
ShowOverflowIndicator	bool	テキストがオーバーフローしたときにインジケーターを表示します
ShowOverflowIndicatorToolTip	bool	オーバーフローインジケーターにツールチップを表示します
OverflowIndicatorToolTipText	string	オーバーフロー時に表示するカスタムツールチップテキスト

動作プロパティ

プロパティ	型	説明
MaxLength	int	最大文字数（既定値：32767）
ReadOnly	bool	テキストの編集を禁止します
MaximumSize	Size	コントロールの最大サイズ
MinimumSize	Size	コントロールの最小サイズ

テーマプロパティ

プロパティ	型	説明
ThemesEnabled	bool	Fixed3D 境界線の XP テーマを有効にします

---

一般的な使用例

1. テーマ付き外観の商品検索ボックス

在庫管理システムで商品を検索するためのスタイル設定済みテキストボックス：

TextBoxExt searchBox = new TextBoxExt();
searchBox.Style = TextBoxExt.theme.Office2016Colorful;
searchBox.BorderColor = Color.DodgerBlue;
searchBox.Text = "Search products...";

2. 複数行の商品説明フィールド

商品説明やメモ用の大きなテキストボックス：

TextBoxExt descriptionBox = new TextBoxExt();
descriptionBox.Multiline = true;
descriptionBox.WordWrap = true;
descriptionBox.ScrollBars = ScrollBars.Vertical;
descriptionBox.Size = new Size(500, 150);

3. ライセンスキーの大文字入力

ライセンスキーを自動的に大文字へ変換します：

TextBoxExt licenseBox = new TextBoxExt();
licenseBox.CharacterCasing = CharacterCasing.Upper;
licenseBox.MaxLength = 25;
licenseBox.TextAlign = HorizontalAlignment.Center;

4. 読み取り専用のステータス表示

有効な外観を表示する表示専用フィールド：

TextBoxExt statusBox = new TextBoxExt();
statusBox.ReadOnly = true;
statusBox.DrawActiveWhenDisabled = true;
statusBox.BackColor = Color.LightYellow;
statusBox.Text = "Status: Active";

5. アラビア語の右から左へのテキスト入力

国際的なアプリケーション向けの右から左へのテキストボックス：

TextBoxExt arabicTextBox = new TextBoxExt();
arabicTextBox.RightToLeft = RightToLeft.Yes;
arabicTextBox.TextAlign = HorizontalAlignment.Right;

6. カスタム境界線の入力フィールド

ブランドに合わせたカスタム境界線色のテキストボックス：

TextBoxExt brandedBox = new TextBoxExt();
brandedBox.BorderStyle = BorderStyle.FixedSingle;
brandedBox.BorderColor = Color.FromArgb(255, 87, 34); // Orange
brandedBox.Style = TextBoxExt.theme.Metro;

7. サイズ制限付きテキストボックス

サイズが固定されたテキストボックス：

TextBoxExt constrainedBox = new TextBoxExt();
constrainedBox.MinimumSize = new Size(200, 25);
constrainedBox.MaximumSize = new Size(400, 25);

---

追加リソース

アセンブリ： Syncfusion.Shared.Base.dll
名前空間： Syncfusion.Windows.Forms.Tools
NuGet パッケージ： Syncfusion.Shared.WinForms
最小 .NET Framework： 4.5

主なクラス：

• TextBoxExt - 拡張テキストボックスコントロールのメインクラス
• SkinManager - テーマアセンブリの読み込みを管理するクラス

関連スキル：

• フォームのテーマ設定とスタイル設定
• 入力検証
• 複数行テキストエディター
• 読み取り専用フィールドの表示