syncfusion-winforms-checkbox

Windows Forms で CheckBoxAdv を実装する

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

次のようなことが必要な場合に、このスキルを使用してください。

• Windows Forms アプリケーションに高度なチェックボックスコントロールを実装する
• チェック済み、未チェック、未確定の状態を持つチェックボックスを作成する
• チェックボックスにグラデーション背景、カスタムボーダー、テキストの影を適用する
• チェックボックスとテキストの配置を個別に設定する
• チェックボックスの状態に整数値または文字列値を関連付ける
• チェックボックスの状態変更イベントを処理する
• CheckBoxAdv コントロールを SQL データベースのフィールドにバインドする
• 標準の Windows Forms コントロールを超えてチェックボックスの外観をカスタマイズする
• 3 状態をサポートするチェックボックスを実装する
• 読み取り専用または自動サイズ調整のチェックボックスコントロールを作成する

コンポーネントの概要

CheckBoxAdv は、標準の CheckBox を拡張し、外観と機能を強化した Windows Forms 用の高度なチェックボックスコントロールです。グラデーション背景、カスタムボーダー（2D および 3D）、テキストの影、テキストとチェックボックスの個別配置、画像チェックボックス、包括的なデータバインディングオプションをサポートしています。

主な機能

• 3 つの状態：チェック済み、未チェック、未確定の状態をサポート
• 値の関連付け：各状態に整数値と文字列値をバインド
• 外観のカスタマイズ：グラデーション背景、カスタムボーダー、テキストの影
• 柔軟な配置：テキストとチェックボックスを個別に配置
• データバインディング：BoolValue プロパティと IntValue プロパティを使用して SQL データベースに接続
• イベント処理：CheckStateChanged イベントと CheckedChanged イベントに応答
• 動作の制御：AutoHeight、ReadOnlyMode、フォーカス矩形のオプション

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

はじめに

📄 参照： references/getting-started.md

• アセンブリの配置と NuGet パッケージ
• デザイナーから CheckBoxAdv を追加する方法
• プログラムから CheckBoxAdv を追加する方法
• 必要な名前空間（Syncfusion.Windows.Forms.Tools）
• 基本的な初期化と設定
• チェックボックスの初期状態の設定

状態と設定

📄 参照： references/states-and-values.md

• CheckState プロパティ（Checked、Unchecked、Indeterminate）
• ブール状態を指定する Checked プロパティ
• 3 状態モードを指定する Tristate プロパティ
• 状態への整数値の関連付け（CheckedInt、UncheckedInt、IndeterminateInt）
• 状態への文字列値の関連付け（CheckedString、UncheckedString、IndeterminateString）
• BoolValue、IntValue、StringValue プロパティの使用
• 各値の型を使用するタイミング

テキストと配置

📄 参照： references/text-and-alignment.md

• テキストの影効果（TextShadow、ShadowColor、ShadowOffset）
• WrapText プロパティによるテキストの折り返し
• テキストの配置オプション（TextContentAlignment）
• チェックボックスの配置オプション（CheckAlign）
• 配置オプション（TopLeft、MiddleCenter、BottomRight など）
• テキストとチェックボックスの配置の組み合わせ

外観と動作

📄 参照： references/appearance-and-behavior.md

• フォーカス矩形の表示（DrawFocusRectangle）
• 高さの自動計算（AutoHeight）
• 読み取り専用モード（ReadOnlyMode）
• グラデーション背景（BackgroundStyle、GradientStart、GradientEnd）
• ボーダースタイル（Border3DStyle、BorderStyle、BorderSingle）
• ボーダーの色（BorderColor、HotBorderColor）
• マウスオーバー時の効果

イベントと操作

📄 参照： references/events.md

• CheckStateChanged イベント
• CheckedChanged イベント
• イベントハンドラーのパターン
• 状態変更への応答
• イベントの発生タイミングと順序
• イベント処理のベストプラクティス

データバインディング

📄 参照： references/data-binding.md

• SQL データベースへのバインド
• bit 型／ブール型フィールド用の BoolValue プロパティ
• 整数型フィールド用の IntValue プロパティ
• SqlDataAdapter と DataTable の使用
• 接続文字列の設定
• 一般的なデータバインディングのパターン
• バインディングに関する問題のトラブルシューティング

クイックスタートの例

using Syncfusion.Windows.Forms.Tools;

// Create CheckBoxAdv instance
CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Enable Feature";
checkBoxAdv1.Size = new Size(150, 25);
checkBoxAdv1.Location = new Point(20, 20);

// Set initial state
checkBoxAdv1.Checked = true;

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

// Handle state changes
checkBoxAdv1.CheckedChanged += (sender, e) => {
    MessageBox.Show($"Checkbox is now: {checkBoxAdv1.Checked}");
};

一般的なパターン

パターン 1：3 状態チェックボックス

ユーザーが必要としているもの：チェック済み、未チェック、未確定の状態を持つチェックボックス：

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Select All";
checkBoxAdv1.Tristate = true;
checkBoxAdv1.CheckState = CheckState.Indeterminate;

checkBoxAdv1.CheckStateChanged += (sender, e) => {
    switch(checkBoxAdv1.CheckState) {
        case CheckState.Checked:
            // Select all items
            break;
        case CheckState.Unchecked:
            // Deselect all items
            break;
        case CheckState.Indeterminate:
            // Partial selection
            break;
    }
};

パターン 2：カスタムスタイルのチェックボックス

ユーザーが必要としているもの：グラデーション背景と境界線で見た目を強化したチェックボックス：

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Styled Checkbox";

// Gradient background
checkBoxAdv1.BackgroundStyle = CheckBoxAdvBackStyle.HorizontalGradient;
checkBoxAdv1.GradientStart = Color.LightBlue;
checkBoxAdv1.GradientEnd = Color.DarkBlue;

// Custom border
checkBoxAdv1.BorderStyle = BorderStyle.FixedSingle;
checkBoxAdv1.BorderColor = Color.Navy;
checkBoxAdv1.HotBorderColor = Color.Red; // On mouse hover

// Shadow text
checkBoxAdv1.TextShadow = true;
checkBoxAdv1.ShadowColor = Color.Gray;
checkBoxAdv1.ShadowOffset = new Point(2, 2);

パターン 3：データバインドされたチェックボックス

ユーザーが必要としているもの：チェックボックスをデータベースのフィールドにバインドすること：

// For boolean/bit fields
using (SqlConnection conn = new SqlConnection(connectionString)) {
    conn.Open();
    SqlDataAdapter adapter = new SqlDataAdapter("SELECT * FROM Settings", conn);
    DataTable dataTable = new DataTable();
    adapter.Fill(dataTable);
    
    checkBoxAdv1.DataBindings.Add("BoolValue", dataTable, "IsEnabled");
}

// For integer fields (values: -1, 0, 1)
checkBoxAdv1.DataBindings.Add("IntValue", dataTable, "StatusCode");

パターン 4：読み取り専用チェックボックスの表示

ユーザーが必要としているもの：ユーザーによる変更を許可せずにチェックボックスの状態を表示すること：

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Read-Only Status";
checkBoxAdv1.Checked = true;
checkBoxAdv1.ReadOnlyMode = true;
checkBoxAdv1.DrawFocusRectangle = false;

主なプロパティ

状態プロパティ

• Checked（bool）：チェック状態（true/false）を取得または設定します
• CheckState（CheckState）：状態（Checked、Unchecked、Indeterminate）を取得または設定します
• Tristate（bool）：ユーザーが未確定状態を選択できる3状態モードを有効にします

値プロパティ

• BoolValue（bool）：状態のブール値表現（データバインディング用）
• IntValue（int）：状態の整数値表現
• StringValue（string）：現在の状態の文字列表現
• CheckedInt/UncheckedInt/IndeterminateInt（int）：各状態の整数値
• CheckedString/UncheckedString/IndeterminateString（string）：各状態の文字列値

外観プロパティ

• BackgroundStyle（CheckBoxAdvBackStyle）：背景スタイル（Default、HorizontalGradient、VerticalGradient）
• GradientStart/GradientEnd（Color）：グラデーションの色
• BorderStyle（BorderStyle）：境界線のスタイル（FixedSingle、Fixed3D、None）
• BorderColor/HotBorderColor（Color）：境界線の色
• TextShadow（bool）：テキストの影を有効にします
• DrawFocusRectangle（bool）：フォーカス枠を表示します

配置プロパティ

• TextContentAlignment（ContentAlignment）：テキストの位置
• CheckAlign（ContentAlignment）：チェックボックスの位置

動作プロパティ

• AutoHeight（bool）：高さを自動的に計算します
• ReadOnlyMode（bool）：ユーザー操作を無効にします
• WrapText（bool）：テキストの折り返しを有効にします

一般的な使用例

使用例 1：設定ダイアログ

状態を保持するアプリケーション設定用のチェックボックスを作成します：

• シンプルなオン／オフ設定には BoolValue を使用します
• 設定データベースに直接バインドします
• CheckedChanged を処理して設定をすぐに保存します

使用例 2：リスト項目の選択

未確定状態を使った「すべて選択」を実装します：

• 3 状態の動作には Tristate プロパティを使用します
• 一部の項目のみ選択されている場合は CheckState.Indeterminate を使用します
• 子項目の選択状態に基づいて状態を更新します

使用例 3：フォームの検証

検証状態を表示する読み取り専用チェックボックスを作成します：

• ReadOnlyMode = true を設定します
• Checked 状態をプログラムから更新します
• 状態を示すカスタムカラーを使用します

使用例 4：強化された UI デザイン

アプリケーションのテーマに合わせた、視覚的に豊かなチェックボックスを作成します：

• グラデーション背景を適用します
• カスタム境界線とホバー効果を設定します
• テキストに影を付けて奥行きを演出します
• テキストとチェックボックスを個別に配置します

使用例 5：データ入力フォーム

チェックボックスをデータベースのレコードにバインドします：

• ステータスコード（0、1、または -1）には IntValue を使用します
• はい／いいえのフィールドには BoolValue を使用します
• 状態にカスタムの整数値または文字列値を関連付けます