syncfusion-winforms-trackbar

Windows Forms での TrackBarEx の実装

TrackBarEx は、値を選択するためのインタラクティブなスライダーを提供する、高度な Windows Forms コントロールです。ユーザーはスライダーをドラッグしたり、ボタンをクリックしたりして、指定した範囲内の値を設定できます。直感的な値入力が必要な場面に最適です。

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

次のような場合にこのスキルを使用します。

• 値を選択するためのインタラクティブなスライダーコントロールを作成する
• スライダーのドラッグや増減ボタンのクリックによる値の入力を可能にする
• 外観（ボタン、色、グラデーション）をカスタマイズする
• 水平または垂直の向きを設定する
• 最小値と最大値で値の範囲を設定する
• ユーザーが値を変更したときのスクロールイベントを処理する
• 小さい増減幅と大きい増減幅を管理する
• デザイナーとプログラムの両方でコントロールを作成できるようにする

コンポーネントの概要

TrackBarEx は、スライダー、トラックチャンネル、オプションの増減ボタンを組み合わせ、直感的に値を選択できるようにします。ユーザーは、マウスでのドラッグ、ボタンのクリック、またはキーボード操作でコントロールを操作できます。

主な機能：

• スライダーとボタンのカスタマイズ（サイズ、色、外観）
• 設定可能な範囲による値の管理
• 水平および垂直の向き
• 外観オプション（グラデーション、透明度、フォーカス矩形）
• 値の変更に対応するスクロールイベント処理
• 増減ボタンの制御
• チャンネルとトラックのカスタマイズ

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

はじめに

📄 参照： references/getting-started.md

• アセンブリの依存関係とプロジェクトのセットアップ
• デザイナーからコントロールを追加する方法
• プログラムからコントロールを追加する方法
• 基本的な最小値と最大値の設定
• 既定の構成について

外観とカスタマイズ

📄 参照： references/appearance-customization.md

• ボタンの外観プロパティ（ShowButton、ButtonColor、HighlightedButtonColor、PushedButtonEndColor）
• スライダーとチャンネルの設定（サイズ、寸法）
• グラデーションの色（TrackBarGradientStart、TrackBarGradientEnd）
• フォーカス矩形と透明度のオプション
• 外観を完全にカスタマイズするパターン

値の管理と構成

📄 参照： references/value-management.md

• Minimum、Maximum、Value プロパティ
• SmallChange と LargeChange の増減幅
• SmallIncrease、SmallDecrease、LargeIncrease、LargeDecrease メソッド
• ボタンを押し続けたときの動作に関するタイマー間隔
• 値の範囲と制約の管理

向きとイベント

📄 参照： references/orientation-events.md

• 水平および垂直の向きのモード
• スクロールイベントの処理
• ユーザー操作への対応
• 一般的なイベントのシナリオとパターン
• イベント処理のベストプラクティス

クイックスタートの例

外観と値の処理をカスタマイズした、基本的な TrackBarEx コントロールを作成します。

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

public class Form1 : Form
{
    private TrackBarEx trackBarEx1;

    public Form1()
    {
        // Create and configure control
        trackBarEx1 = new TrackBarEx();
        trackBarEx1.Minimum = 0;
        trackBarEx1.Maximum = 100;
        trackBarEx1.Value = 50;
        trackBarEx1.ShowButtons = true;
        trackBarEx1.ButtonColor = System.Drawing.Color.DodgerBlue;
        trackBarEx1.Orientation = Orientation.Horizontal;
        
        // Add scroll event handler
        trackBarEx1.Scroll += TrackBarEx1_Scroll;
        
        // Add to form
        this.Controls.Add(trackBarEx1);
    }

    private void TrackBarEx1_Scroll(object sender, EventArgs e)
    {
        // Update UI or application state when value changes
        System.Diagnostics.Debug.WriteLine($"Value: {trackBarEx1.Value}");
    }
}

一般的なパターン

値の範囲の設定

用途に適した最小値と最大値を定義します。

trackBarEx1.Minimum = 10;
trackBarEx1.Maximum = 100;
trackBarEx1.Value = 50;

ボタンの外観のカスタマイズ

ボタンの色をカスタマイズして、視覚的なフィードバックを強化します。

trackBarEx1.ShowButtons = true;
trackBarEx1.ButtonColor = System.Drawing.Color.LightBlue;
trackBarEx1.HighlightedButtonColor = System.Drawing.Color.Blue;
trackBarEx1.PushedButtonEndColor = System.Drawing.Color.DarkBlue;

値の変更の処理

Scroll イベントを使用して、ユーザー操作に対応します。

trackBarEx1.Scroll += (s, e) => {
    // Handle value change
};

向きの変更

水平レイアウトと垂直レイアウトを切り替えます。

// For vertical layout
trackBarEx1.Orientation = Orientation.Vertical;

// For horizontal layout
trackBarEx1.Orientation = Orientation.Horizontal;

主なプロパティ

プロパティ	目的
Value	現在のスライダー位置を取得または設定します
Minimum	最小値を取得または設定します（デフォルト：10）
Maximum	最大値を取得または設定します（デフォルト：20）
Orientation	水平または垂直のレイアウトを設定します
ShowButtons	増減ボタンの表示を切り替えます
SmallChange	矢印キーまたは小刻みな増分による値の変化量（デフォルト：1）
LargeChange	大刻みな増分による値の変化量（デフォルト：5）
ButtonColor	増減ボタンの色
HighlightedButtonColor	強調表示時のボタンの色
PushedButtonEndColor	押下時のボタンの色
Transparent	背景を透明にします

一般的な使用例

• 音量調整： TrackBarEx を使用して、視覚的なフィードバックを伴う音量調整を行います
• スライダー入力： 数値を選択するための直感的なスライダーでテキスト入力を置き換えます
• 進捗表示： 調整可能な進捗状況または完了率を表示します
• 範囲選択： 最小値と最大値のしきい値をユーザーが設定できるようにします
• パラメーター調整： アプリケーションの設定やしきい値を簡単に調整できるようにします