syncfusion-winforms-tooltip

Syncfusion Windows Forms ツールチップの実装

Syncfusion の SfToolTip コンポーネントは、Windows Forms アプリケーション向けに豊富なツールチップ機能を提供します。ユーザーがコントロールにカーソルを合わせると、ポップアップとして自動的に表示されます。複数のツールチップ項目、カスタムコントロール、画像に対応し、外観を幅広くカスタマイズできます。

このスキルを使用する場面

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

• 基本的な内容または高度な内容のツールチップを Windows Forms コントロールに追加する
• 複数行の情報やセクションを含む複数項目のツールチップを表示する
• コントロールを指すくちばし付きのバルーン型ツールチップを表示する
• 色、境界線、グラデーション、画像を使ってツールチップの外観をカスタマイズする
• リッチでインタラクティブなコンテンツを表示するため、ツールチップ内にカスタムコントロールを配置する
• ツールチップの表示タイミングと位置をプログラムで制御する
• ホバー時に情報パネルを表示するコンテキストヘルプを実装する
• 国際化対応アプリケーションでRTL レイアウトをサポートする
• 専用の描画処理を使ったカスタム描画のツールチップを作成する

コンポーネントの概要

SfToolTip コンポーネントは、次の機能を提供します。

• 複数の項目： 個別のスタイルを設定して、複数のツールチップ項目を追加できます
• カスタムコントロール： ツールチップ項目内に任意のユーザーコントロールを配置できます
• リッチコンテンツ： テキスト、画像、グラデーション、区切り線に対応します
• バルーンスタイル： 方向を示すくちばし付きのツールチップを表示できます
• 外観： 色、フォント、境界線、影などを幅広くカスタマイズできます
• イベント： 表示動作やカスタム描画を制御できます
• プログラムによる制御： 必要に応じてツールチップを表示または非表示にできます

比較： 複数項目への対応、ツールチップ項目ごとのカスタマイズ、またはカスタムコントロールの配置が必要な場合は、SuperToolTip ではなく SfToolTip を選択してください。SfToolTip は、より豊かなスタイル設定と柔軟性を備えています。

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

はじめに

📄 参照： references/getting-started.md

基本的なツールチップを実装する場合：

• アセンブリの配置と必要な依存関係
• シンプルなテキストを使ったツールチップの設定（デザイナーとコード）
• ToolTipInfo を使った構造化コンテンツの設定
• ツールチップのプログラムによる表示と非表示
• ツールチップの遅延時間の設定（InitialDelay、AutoPopDelay）
• 基本的なバルーンスタイルの設定

ツールチップの項目とコンテンツ

📄 参照： references/tooltip-items-and-content.md

ツールチップのコンテンツ構造を扱う場合：

• ToolTipItem オブジェクトの作成と設定
• 1 つのツールチップへの複数項目の追加
• 項目間の間隔とパディングの設定
• Image または ImageList プロパティを使った画像の追加
• 画像の配置（Left、Top、Right）の設定
• 画像のサイズと間隔の設定
• ツールチップ内へのカスタムユーザーコントロールの配置

バルーンスタイルとくちばし

📄 参照： references/balloon-style-and-beak.md

バルーン型ツールチップを実装する場合：

• ToolTipStyle.Balloon の有効化
• バルーンスタイルと四角形スタイルの違い
• くちばしの背景色のカスタマイズ
• コントロールを基準にしたバルーンの配置
• バルーン型ツールチップの使用例

外観のカスタマイズ

📄 参照： references/appearance-customization.md

ツールチップの見た目をカスタマイズする場合：

• 境界線の色と太さ
• ToolTipItem ごとのスタイル（色、フォント、配置）
• グラデーション背景の実装
• 項目間の区切り線のカスタマイズ
• 影の効果
• RTL（右から左）レイアウトのサポート

高度な使用方法とイベント

📄 参照： references/advanced-usage.md

高度なツールチップ機能を実装する場合：

• ツールチップのテキストや情報のプログラムによる取得と設定
• ToolTipShowing イベントを使った条件付き表示
• コントロールごとの外観の動的なカスタマイズ
• 表示前のツールチップ位置の変更
• 最小幅と最大幅の設定
• DrawToolTipItem イベントを使ったカスタム描画
• 既定の描画処理のキャンセル

クイックスタート

テキストを使った基本的なツールチップ

using Syncfusion.Windows.Forms;

// Add SfToolTip component to form
SfToolTip sfToolTip1 = new SfToolTip();

// Set simple text tooltip
sfToolTip1.SetToolTip(this.button1, "Click to submit the form");

複数項目を含むツールチップ

using Syncfusion.Windows.Forms;
using Syncfusion.WinForms.Controls;

SfToolTip sfToolTip1 = new SfToolTip();

// Create ToolTipInfo with multiple items
ToolTipInfo toolTipInfo = new ToolTipInfo();

ToolTipItem item1 = new ToolTipItem();
item1.Text = "User Information";
item1.Style.Font = new Font("Arial", 10f, FontStyle.Bold);

ToolTipItem item2 = new ToolTipItem();
item2.Text = "Name: John Doe\nEmail: [email protected]";

toolTipInfo.Items.AddRange(new ToolTipItem[] { item1, item2 });
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

画像付きバルーンスタイルのツールチップ

SfToolTip sfToolTip1 = new SfToolTip();

ToolTipInfo toolTipInfo = new ToolTipInfo();
toolTipInfo.ToolTipStyle = ToolTipStyle.Balloon;
toolTipInfo.BeakBackColor = Color.LightSkyBlue;

ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Text = "David Carter\nPhone: +1 919.494.1974\nEmail: [email protected]";
toolTipItem.Image = Properties.Resources.UserImage;
toolTipItem.Style.ImageSize = new Size(80, 80);
toolTipItem.Style.ImageAlignment = ToolTipImageAlignment.Left;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

一般的なパターン

パターン 1：グラデーション付きのリッチな書式設定のツールチップ

ToolTipInfo toolTipInfo = new ToolTipInfo();
toolTipInfo.BorderColor = Color.DarkGray;
toolTipInfo.BorderThickness = 2;

ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Text = "Important Information";
toolTipItem.EnableGradientBackground = true;
toolTipItem.Style.GradientBrush = new BrushInfo(
    GradientStyle.Horizontal, 
    new Color[] { Color.LightBlue, Color.LightGreen }
);
toolTipItem.Style.Font = new Font("Arial", 10f, FontStyle.Bold);
toolTipItem.Style.ForeColor = Color.DarkBlue;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.control, toolTipInfo);

パターン 2：条件に応じたツールチップの表示

sfToolTip1.ToolTipShowing += (sender, e) =>
{
    // Customize tooltip based on control state
    if (e.Control is Button button && !button.Enabled)
    {
        e.Cancel = true; // Don't show tooltip for disabled controls
    }
    
    // Or modify appearance dynamically
    if (e.Control.Tag?.ToString() == "Warning")
    {
        e.ToolTipInfo.Items[0].Style.BackColor = Color.LightCoral;
        e.ToolTipInfo.BorderColor = Color.Red;
    }
};

パターン 3：プログラムによるツールチップの表示

// Show tooltip at specific location
Point location = new Point(300, 200);
sfToolTip1.Show("Processing complete!", location);

// Show tooltip at cursor position with duration
ToolTipInfo info = new ToolTipInfo();
ToolTipItem item = new ToolTipItem { Text = "Operation successful!" };
info.Items.Add(item);
sfToolTip1.Show(info);

// Hide after delay
Thread.Sleep(3000);
sfToolTip1.Hide();

パターン 4：ツールチップ内のカスタムコントロール

// Create custom control (e.g., PictureBox with animated GIF)
PictureBox pictureBox = new PictureBox();
pictureBox.Image = Image.FromFile("loading.gif");
pictureBox.SizeMode = PictureBoxSizeMode.CenterImage;
pictureBox.Size = new Size(200, 100);

ToolTipInfo toolTipInfo = new ToolTipInfo();
ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Control = pictureBox;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

主なプロパティ

SfToolTip のプロパティ

Property	Type	Description
InitialDelay	int	ツールチップが表示されるまでの遅延（ミリ秒、既定値：0）
AutoPopDelay	int	ツールチップが表示される時間（ミリ秒、既定値：5000）
ShadowVisible	bool	ツールチップの影の効果を有効にします

ToolTipInfo のプロパティ

Property	Type	Description
Items	ToolTipItemCollection	表示するツールチップ項目のコレクション
ToolTipStyle	ToolTipStyle	Rectangle（既定）または Balloon スタイル
BeakBackColor	Color	バルーンのくちばし部分の背景色
BorderColor	Color	ツールチップの境界線の色
BorderThickness	int	境界線の太さ（ピクセル単位）
MinWidth	int	ツールチップの最小幅
MaxWidth	int	ツールチップの最大幅
RightToLeft	RightToLeft	RTL レイアウトのサポート

ToolTipItem のプロパティ

Property	Type	Description
Text	string	ツールチップ項目のテキスト内容
Image	Image	項目に表示する画像
ImageList	ImageList	複数の画像に使用する ImageList
ImageIndex	int	ImageList を使用する場合のインデックス
Control	Control	項目内に配置するカスタムコントロール
EnableSeparator	bool	項目の後に区切り線を表示します
EnableGradientBackground	bool	グラデーション背景を有効にします
Padding	Padding	項目の内容の周囲の余白
Style	ToolTipStyleInfo	包括的なスタイル設定

ToolTipStyleInfo（Style）のプロパティ

Property	Type	Description
BackColor	Color	背景色
ForeColor	Color	テキストの色
Font	Font	テキストのフォント
TextAlignment	ContentAlignment	テキストの配置（MiddleLeft など）
ImageAlignment	ToolTipImageAlignment	画像の位置（Left、Top、Right）
ImageSize	Size	画像の固定サイズ
ImageToTextOffset	int	画像とテキストの間隔
GradientBrush	BrushInfo	グラデーションの設定
SeparatorColor	Color	区切り線の色
SeparatorStyle	DashStyle	区切り線のスタイル

一般的な用途

1. フォームフィールドのヘルプ： フォームコントロールに説明的なツールチップを追加し、想定される入力を説明します
2. ボタンの操作： ツールバーのボタンやアイコンに操作の説明を表示します
3. ステータス情報： ステータスバーの項目やインジケーターに詳細なステータスを表示します
4. ユーザープロファイル： ホバー時に画像付きのリッチなプロフィールカードを表示します
5. データ検証： 検証コントロールに検証ルールやエラーの詳細を表示します
6. ダッシュボードウィジェット： チャートやウィジェットのツールチップに詳細な指標を表示します
7. 無効なコントロール： コントロールが無効になっている理由と、使用可能になるタイミングを説明します
8. 進行状況インジケーター： ホバー時に進行状況の詳細を表示します
9. アイコントレイアプリケーション： システムトレイのツールチップにアプリケーションのステータスを表示します
10. 多言語サポート： RTL サポートを利用して翻訳や追加のコンテキストを表示します

イベント

Event	Description	Use Case
ToolTipShowing	ツールチップが表示される前に発生します	コントロールごとに外観をカスタマイズする、条件に応じて表示をキャンセルする、位置を調整する
DrawToolTipItem	ツールチップの描画中に発生します	カスタム描画を実装する、既定の外観を上書きする

アセンブリの依存関係

必須のアセンブリ：

• Syncfusion.Core.WinForms.dll および Syncfusion.Shared.Base

NuGet パッケージ：

• Syncfusion.Core.WinForms

ベストプラクティス

1. ツールチップは簡潔に保ちます： ユーザーはツールチップを素早く読みます。必要な情報だけを記載します
2. バルーン形式は控えめに使用します： バルーン形式のツールチップは目立ちやすいため、重要なヒントに使用します
3. 冗長な表現を避けます： コントロールのラベルをそのままツールチップで繰り返さないでください
4. 表示タイミングを考慮します： 内容の複雑さに応じて InitialDelay と AutoPopDelay を調整します
5. アクセシビリティ： 十分な色のコントラストを確保し、ツールチップのテキストを読みやすくします
6. パフォーマンス： 頻繁にホバーされるコントロールのツールチップでは、複雑なカスタムコントロールを避けます
7. RTL レイアウトをテストします： 右から左に記述する言語の設定で、ツールチップの表示を確認します