syncfusion-winforms-scroll-frame

スクロールフレームを実装する（SfScrollFrame）

SfScrollFrame コントロールは、Windows Forms アプリケーション向けに、テーマ設定とカスタマイズが可能なスクロールバーを提供します。Microsoft の ScrollableControl または Container から派生した任意のコントロールに、モダンなスタイルのスクロールバーを追加できます。テーマ、コンテキストメニュー、豊富な外観オプションに対応した完全にカスタマイズ可能なスクロールバーに置き換えることで、既定のシステムスクロールバーを使用しません。

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

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

• Panel、ListView、ListBox などのスクロール可能なコントロールにカスタムスクロールバーを追加する
• スクロールバーにテーマを適用する（Office2016、Office2019、HighContrast）
• スクロールバーの外観をカスタマイズする（色、サイズ、状態）
• スクロールバーのイベントやコンテキストメニューを処理する
• スクロールバーのコンテキストメニューをローカライズする
• スクロールバーのテストにUI オートメーションを有効にする（Coded UI、QTP）
• カスタムスクロール速度でプログラムからスクロールを制御する
• 既定の Windows スクロールバーをモダンなスクロールバーに置き換える

コンポーネントの概要

主な機能

• 汎用的な追加： ScrollableControl から派生した任意のコントロール（Panel、ListView、ListBox など）で動作します
• テーマのサポート： Office2016、Office2019、HighContrast のテーマを標準で搭載しています
• 完全なカスタマイズ： すべてのスクロールバー要素の色、サイズ、状態をカスタマイズできます
• コンテキストメニュー： ローカライズに対応したカスタマイズ可能な右クリックメニューです
• プログラムによるスクロール： コードからスクロール位置と速度を制御できます
• UI オートメーション： Coded UI テストおよび QTP/UFT テストに対応しています
• オーバーレイ表示： レイアウトを変更せずに、スクロールバーを既定の位置に重ねて表示します

アーキテクチャ

SfScrollFrame
├── Control Property (attach to target)
├── HorizontalScrollBar
│   ├── Style (ScrollBarStyleInfo)
│   ├── Value, SmallChange
│   ├── EnableMaximumArrow, EnableMinimumArrow, EnableThumb
│   └── ContextMenuShowing event
└── VerticalScrollBar
    ├── Style (ScrollBarStyleInfo)
    ├── Value, SmallChange
    ├── EnableMaximumArrow, EnableMinimumArrow, EnableThumb
    └── ContextMenuShowing event

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

はじめに

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

• アセンブリの配置と必要な参照設定
• デザイナーを使用した SfScrollFrame の追加
• コードを使用した SfScrollFrame の追加
• Value プロパティによるプログラムからのスクロール
• スクロール速度を指定する SmallChange の設定
• 基本的な実装例

外観とスタイル設定

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

• ScrollBarStyleInfo によるスクロールバーの外観のカスタマイズ
• 矢印ボタンのスタイル設定（色、ホバー、押下、無効状態）
• つまみのスタイル設定（色、幅、境界線、状態）
• 矢印ボタンとつまみの無効化
• 組み込みテーマのサポート（Office2016、Office2019、HighContrast）
• テーマアセンブリの読み込みと適用
• ThemeName プロパティの使用方法

コンテキストメニューのカスタマイズ

📄 参照先： references/context-menu.md

• 既定のコンテキストメニューの機能
• ContextMenuShowing イベントの処理
• 既定のコンテキストメニューの無効化
• カスタムコンテキストメニューの表示
• 既定のコンテキストメニューへの項目の追加
• ContextMenuShowingEventArgs のプロパティ

ローカライズのサポート

📄 参照先： references/localization.md

• スクロールバーのコンテキストメニュー文字列のローカライズ
• アプリケーションへのリソースファイル（.resx）の追加
• カルチャ固有のリソースの作成
• CurrentUICulture の設定
• 既定カルチャのリソースの編集
• 別のアセンブリ／名前空間からのローカライズ

UI オートメーションとテスト

📄 参照先： references/ui-automation.md

• Microsoft UI Automation の概要
• Coded UI Test（CUIT）のサポート（レベル 1 および 2）
• CodedUITestBuilder の使用方法
• 操作の記録とアサーションの追加
• 自動テストの実行
• QTP/UFT テストのサポート

制限と制約

📄 参照先： references/limitations.md

• 対象となるコントロール（ScrollableControl の派生コントロール）
• 互換性のないコントロール（カスタムスクロールバーを実装したコントロール）
• LargeChange プロパティの制約
• ベストプラクティスと回避策

クイックスタート

基本的な実装

using Syncfusion.WinForms.Controls;

// Create SfScrollFrame instance
SfScrollFrame sfScrollFrame1 = new SfScrollFrame();

// Create a ListView (or any ScrollableControl)
ListView listView1 = new ListView();
listView1.View = View.Details;
listView1.Columns.Add("Column 1", 150);
listView1.Columns.Add("Column 2", 150);

// Add items
for (int i = 0; i < 100; i++)
{
    listView1.Items.Add(new ListViewItem(new[] { $"Item {i}", $"Value {i}" }));
}

// Attach SfScrollFrame to ListView
sfScrollFrame1.Control = listView1;

// Add ListView to form
this.Controls.Add(listView1);

テーマを適用する場合

using Syncfusion.WinForms.Controls;
using Syncfusion.WinForms.Themes;

// In Program.cs
static void Main()
{
    // Load theme assembly
    SfSkinManager.LoadAssembly(typeof(Office2016Theme).Assembly);
    
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
    Application.Run(new MainForm());
}

// In form
public MainForm()
{
    InitializeComponent();
    
    // Create and attach SfScrollFrame
    SfScrollFrame sfScrollFrame1 = new SfScrollFrame();
    sfScrollFrame1.Control = listView1;
    
    // Apply theme
    sfScrollFrame1.ThemeName = "Office2016Colorful";
}

よくあるパターン

パターン 1：カスタムスタイルを設定して Panel に追加する

// Create Panel with content
Panel panel1 = new Panel();
panel1.AutoScroll = true;
panel1.Size = new Size(400, 300);

// Add controls to panel
for (int i = 0; i < 50; i++)
{
    Button btn = new Button();
    btn.Text = $"Button {i}";
    btn.Location = new Point(10, i * 30);
    panel1.Controls.Add(btn);
}

// Attach SfScrollFrame
SfScrollFrame sfScrollFrame1 = new SfScrollFrame();
sfScrollFrame1.Control = panel1;

// Customize vertical scrollbar appearance
sfScrollFrame1.VerticalScrollBar.Style.ScrollBarBackColor = Color.LightGray;
sfScrollFrame1.VerticalScrollBar.Style.ThumbColor = Color.Gray;
sfScrollFrame1.VerticalScrollBar.Style.ThumbHoverColor = Color.Black;
sfScrollFrame1.VerticalScrollBar.Style.ThumbPressedColor = Color.Blue;
sfScrollFrame1.VerticalScrollBar.Style.ThumbWidth = 10;

this.Controls.Add(panel1);

パターン 2：速度を制御してプログラムからスクロールする

// Attach SfScrollFrame
sfScrollFrame1.Control = listView1;

// Configure scroll speed
sfScrollFrame1.HorizontalScrollBar.SmallChange = 10;
sfScrollFrame1.VerticalScrollBar.SmallChange = 20;

// Scroll to specific position
Button scrollButton = new Button();
scrollButton.Text = "Scroll to Middle";
scrollButton.Click += (s, e) =>
{
    // Get maximum scroll value
    int maxValue = sfScrollFrame1.VerticalScrollBar.Maximum;
    
    // Scroll to middle
    sfScrollFrame1.VerticalScrollBar.Value = maxValue / 2;
};

パターン 3：カスタムコンテキストメニュー

sfScrollFrame1.Control = listView1;

// Handle ContextMenuShowing event for vertical scrollbar
sfScrollFrame1.VerticalScrollBar.ContextMenuShowing += (sender, e) =>
{
    // Add custom menu item to default menu
    ToolStripMenuItem customItem = new ToolStripMenuItem("Show Current Position");

    customItem.Click += (s, ev) =>
    {
        int position = sfScrollFrame1.VerticalScrollBar.Value;
        MessageBox.Show($"Current scroll position: {position}");
    });

    e.ContextMenu.Items.Add(customItem);
};

パターン 4：カスタムカラーの無効化された矢印ボタン

sfScrollFrame1.Control = panel1;

// Disable minimum arrows (top/left)
sfScrollFrame1.VerticalScrollBar.EnableMinimumArrow = false;
sfScrollFrame1.HorizontalScrollBar.EnableMinimumArrow = false;

// Set disabled button colors
sfScrollFrame1.VerticalScrollBar.Style.ArrowButtonDisabledBackColor = Color.Silver;
sfScrollFrame1.VerticalScrollBar.Style.ArrowButtonDisabledForeColor = Color.Gray;

sfScrollFrame1.HorizontalScrollBar.Style.ArrowButtonDisabledBackColor = Color.Silver;
sfScrollFrame1.HorizontalScrollBar.Style.ArrowButtonDisabledForeColor = Color.Gray;

主なプロパティ

SfScrollFrame のプロパティ

プロパティ	型	説明
Control	Control	スクロールバーを取り付けるコントロール（ScrollableControl である必要があります）
HorizontalScrollBar	ScrollBarBase	水平スクロールバーの設定にアクセスします
VerticalScrollBar	ScrollBarBase	垂直スクロールバーの設定にアクセスします
ThemeName	string	適用するテーマ（Office2016Colorful、Office2016White など）

ScrollBar のプロパティ

プロパティ	型	説明
Value	int	現在のスクロール位置
SmallChange	int	矢印ボタンをクリックしたときのスクロール量
EnableMaximumArrow	bool	下／右の矢印ボタンを有効／無効にします
EnableMinimumArrow	bool	上／左の矢印ボタンを有効／無効にします
EnableThumb	bool	スクロールバーのつまみを有効／無効にします
Style	ScrollBarStyleInfo	外観のカスタマイズ設定

ScrollBarStyleInfo のプロパティ

プロパティ	型	説明
ScrollBarBackColor	Color	スクロールバーのトラックの背景色
ThumbColor	Color	通常時のつまみの色
ThumbHoverColor	Color	マウスオーバー時のつまみの色
ThumbPressedColor	Color	クリック時のつまみの色
ThumbWidth	int	つまみの幅／高さ（最大値：スクロールバーのサイズ）
ThumbBorderColor	Color	つまみの境界線の色
ArrowButtonBackColor	Color	通常時の矢印ボタンの背景色
ArrowButtonForeColor	Color	通常時の矢印アイコンの色
ArrowButtonHoverBackColor	Color	ホバー時の矢印ボタンの背景色
ArrowButtonPressedBackColor	Color	クリック時の矢印ボタンの背景色
ArrowButtonDisabledBackColor	Color	無効時の矢印ボタンの背景色
ArrowButtonBorderColor	Color	矢印ボタンの境界線の色

一般的な使用例

使用例 1：カスタムスクロールバーを備えた ListView

シナリオ： デフォルトの ListView スクロールバーを、テーマに合わせてカスタマイズしたスクロールバーに置き換えます。

実装：

// Setup ListView
ListView listView = new ListView { View = View.Details, Size = new Size(400, 300) };
listView.Columns.Add("Name", 150);
listView.Columns.Add("Value", 150);

// Attach themed scrollbar
SfScrollFrame scrollFrame = new SfScrollFrame();
scrollFrame.Control = listView;
scrollFrame.ThemeName = "Office2019Colorful";

// Customize thumb width
scrollFrame.VerticalScrollBar.Style.ThumbWidth = 8;
scrollFrame.HorizontalScrollBar.Style.ThumbWidth = 8;

使用例 2：高速スクロールに対応したパネル

シナリオ： 多数のコントロールを含むパネルで、スクロール速度を上げます。

実装：

// Setup Panel
Panel panel = new Panel { AutoScroll = true, Size = new Size(500, 400) };

// Attach scrollbar with fast scrolling
SfScrollFrame scrollFrame = new SfScrollFrame();
scrollFrame.Control = panel;
scrollFrame.VerticalScrollBar.SmallChange = 30;   // Faster vertical scroll
scrollFrame.HorizontalScrollBar.SmallChange = 30; // Faster horizontal scroll

使用例 3：ローカライズされたアプリケーション

シナリオ： スクロールバーメニューがローカライズされた多言語アプリケーションです。

実装：

// Set culture before InitializeComponent
System.Threading.Thread.CurrentThread.CurrentUICulture = 
    new System.Globalization.CultureInfo("de-DE");

InitializeComponent();

// SfScrollFrame automatically uses localized context menu strings
// if corresponding .resx files exist

使用例 4：スクロールバーの操作を無効化

シナリオ： 表示専用のスクロール可能なコンテンツ（つまみのドラッグなし）です。

実装：

SfScrollFrame scrollFrame = new SfScrollFrame();
scrollFrame.Control = listView;

// Disable thumb dragging (scrolling only via arrows/wheel)
scrollFrame.VerticalScrollBar.EnableThumb = false;
scrollFrame.HorizontalScrollBar.EnableThumb = false;

// Set disabled thumb color
scrollFrame.VerticalScrollBar.Style.ThumbDisabledColor = Color.LightGray;
scrollFrame.HorizontalScrollBar.Style.ThumbDisabledColor = Color.LightGray;

トラブルシューティング

問題：スクロールバーが表示されない

解決策：

• 対象のコントロールが ScrollableControl を継承していることを確認します
• コンテンツがコントロールのサイズを超えていることを確認します（スクロールバーは必要な場合にのみ表示されます）
• Panel コントロールの AutoScroll プロパティが true であることを確認します

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

解決策：

• アプリケーションの実行前に Program.cs でテーマアセンブリを読み込みます
• ThemeName のスペルと大文字・小文字を確認します
• テーマアセンブリがプロジェクトで参照されていることを確認します

問題：コンテキストメニューが表示されない

解決策：

• スクロールバーのトラックまたはつまみを直接右クリックします
• ContextMenuShowing イベントによってメニューがキャンセルされていないことを確認します
• コントロールにフォーカスがあることを確認します

問題：SmallChange が期待どおりに機能しない

解決策：

• SmallChange は矢印ボタンのクリックに影響し、マウスホイールによるスクロールには影響しません
• マウスホイールによるスクロールは、取り付けられたコントロールによって制御されます
• 速度の変化をはっきりさせるには、より大きな値（10～30）を使用します

ベストプラクティス

1. 早めに設定する： InitializeComponent() の後、フォームのコンストラクターで Control プロパティを設定します。
2. テーマの読み込みは一度だけ： テーマアセンブリはフォームごとではなく、Program.cs で読み込みます。
3. スタイルを統一する： アプリケーション内のすべての SfScrollFrame インスタンスに同じテーマを適用します。
4. SmallChange を調整する： 最適なスクロール速度を見つけるため、さまざまな値（10-50）を試します。
5. イベントを処理する： カスタムメニューの動作を設定するには、ContextMenuShowing をサブスクライブします。
6. 互換性をテストする： デプロイ前に、SfScrollFrame が対象のコントロールで動作することを確認します。
7. ローカライズを設定する： 多言語アプリでは、開発の早い段階でリソースファイルを追加します。
8. パフォーマンス： 実行時にスタイルプロパティを頻繁に変更しないようにします。