syncfusion-winforms-xptaskbar

Windows Forms での XPTaskBar の実装

目次

• このスキルを使用する場面
• コンポーネントの概要
• クイックスタートの例
• ドキュメントのナビゲーションガイド
• 一般的なパターン
• 主な構成プロパティ

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

次のような場合に XPTaskBar を使用します。

• 展開可能なタスクパネルを作成する - コマンド項目や機能を、折りたたみ可能なグループボックス内に表示します
• Windows XP 風のメニューを構築する - 従来のタスクサイドバーの UI パターンを再現します
• 階層的にナビゲーションを整理する - 関連するコマンドをカテゴリ別のボックスにまとめます
• インタラクティブなタスクリストを実装する - ユーザーがアニメーション付きでタスクカテゴリを展開／折りたたみできるようにします
• カスタムアニメーションとイベントを追加する - 展開／折りたたみの動作を制御し、ユーザー操作に応答します

コンポーネントの概要

XPTaskBar は、折りたたみ可能なボックス内にまとめられたコマンド項目を表示する Windows Forms コントロールで、Windows XP のタスクサイドバーを模しています。コンポーネントの階層は次のとおりです。

• XPTaskBar - 複数のボックスを格納できるメインコンテナーコントロール
• XPTaskBarBox - ヘッダーと項目領域を備えた折りたたみ可能なセクション
• XPTaskBarItem - ボックス内に表示される個々のコマンド項目

主な機能

• 階層レイアウト - 項目をカテゴリ別のボックスに整理します
• 折りたたみ／展開アニメーション - 設定可能なアニメーション速度で滑らかに遷移します
• 複数のレイアウトモード - 縦向き（既定）または横向き
• 状態の永続化 - セッションをまたいで展開／折りたたみ状態を保持します
• 豊富なカスタマイズ - 色、フォント、画像、間隔を制御します
• イベント駆動 - クリック、アニメーション、状態変更を処理します
• 子コントロールのサポート - ボックス内にパネルやその他のコントロールを配置できます

クイックスタートの例

using Syncfusion.Windows.Forms.Tools;

// Create XPTaskBar control
XPTaskBar xpTaskBar1 = new XPTaskBar();
xpTaskBar1.Dock = DockStyle.Fill;
this.Controls.Add(xpTaskBar1);

// Create first task box
XPTaskBarBox box1 = new XPTaskBarBox();
box1.Text = "File Operations";
xpTaskBar1.Controls.Add(box1);

// Add items to the box
box1.Items.AddRange(new XPTaskBarItem[] {
    new XPTaskBarItem("New Document", System.Drawing.Color.Empty, -1, "NewDoc"),
    new XPTaskBarItem("Open File", System.Drawing.Color.Empty, -1, "OpenFile"),
    new XPTaskBarItem("Save", System.Drawing.Color.Empty, -1, "Save")
});

// Handle item clicks
box1.ItemClick += (sender, e) => {
    switch (e.XPTaskBarItem.Tag as string) {
        case "NewDoc":
            // Handle new document
            break;
        case "OpenFile":
            // Handle file open
            break;
    }
};

// Create second task box
XPTaskBarBox box2 = new XPTaskBarBox();
box2.Text = "Editing Tools";
xpTaskBar1.Controls.Add(box2);

box2.Items.AddRange(new XPTaskBarItem[] {
    new XPTaskBarItem("Cut", System.Drawing.Color.Empty, -1, "Cut"),
    new XPTaskBarItem("Copy", System.Drawing.Color.Empty, -1, "Copy"),
    new XPTaskBarItem("Paste", System.Drawing.Color.Empty, -1, "Paste")
});

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

実装のニーズに合った順序でリファレンスドキュメントを参照してください。

はじめに

📄 参照: references/getting-started.md

• アセンブリとパッケージの依存関係
• デザイナーまたはコードからコントロールを追加する方法
• XPTaskBar、ボックス、項目の基本的な設定
• 必要なアセンブリ参照

構造の構築

📄 参照: references/box-structure.md

• XPTaskBar のボックス階層と構造
• ヘッダーのカスタマイズ（テキスト、フォント、配置、方向）
• 折りたたみ／展開ボタンの設定
• 子パネルとコントロールの統合

📄 参照: references/items-and-content.md

• XPTaskBarItems の作成と管理
• Items コレクションの操作
• 項目のプロパティと設定
• PreferredChildPanelHeight を使った入れ子のコントロールの配置

レイアウトと方向

📄 参照: references/layout-orientation.md

• 縦向きレイアウトモード（既定）
• 横向きレイアウトモードと列幅
• 方向の動的な切り替え
• レスポンシブなレイアウト動作

動作とインタラクティブ性

📄 参照: references/behavior-and-events.md

• アニメーションの設定とタイミング
• 折りたたみ／展開イベントの処理
• Tag に基づく振り分けを行う ItemClick イベント
• 状態の保持（AutoPersistStates）
• ドラッグ＆ドロップのサポート
• イベントの例とパターン

外観とカスタマイズ

📄 参照: references/appearance-customization.md

• ヘッダーの色と前景色のカスタマイズ
• ヘッダーのフォントスタイル
• ProvideHeaderBackgroundBrush イベントと ProvideItemsBackgroundBrush イベントによるブラシのカスタマイズ
• ヘッダーと項目への画像の追加
• ツールチップの設定と表示
• カスタム背景の描画方法

余白とスクロール

📄 参照： references/padding-spacing-scrolling.md

• XPTaskBar 内部の余白（DockPadding、HorizontalPadding、VerticalPadding）
• ボックスヘッダーの余白（PADX、PADY）
• 自動スクロールの動作
• スクロールマージンと最小サイズの設定

一般的なパターン

パターン 1：複数ボックスのタスクメニュー

折りたたみ可能な複数のタスクカテゴリを含むサイドバーを作成します。

var taskBar = new XPTaskBar { VerticalLayout = true };

// Create boxes for different task categories
foreach (var category in new[] { "File", "Edit", "View", "Help" }) {
    var box = new XPTaskBarBox { Text = category };
    taskBar.Controls.Add(box);
    // Add items to box
}

パターン 2：項目のクリックイベントの振り分け

Tag プロパティを使って、イベントの振り分けを実装します。

box.ItemClick += (sender, e) => {
    var command = e.XPTaskBarItem.Tag as string;
    ExecuteCommand(command);
};

パターン 3：状態の永続化

セッションをまたいでユーザー設定を保持します。

xpTaskBar1.AutoPersistStates = true;

パターン 4：状態変化のアニメーション

展開／折りたたみ時のアニメーションの動作を制御します。

box.AnimationDelay = 50;           // Milliseconds between frames
box.AnimationPositionsCount = 15;  // Number of animation steps
box.UseAdditionalAnimation = true; // Animate when adding/removing items

主な設定プロパティ

XPTaskBar レベル

プロパティ	型	目的
VerticalLayout	bool	垂直モード（既定）では true、水平モードでは false に設定します
ColWidthOnHorizontalAlignment	int	水平レイアウトモードでの列幅
HorizontalPadding	int	内部の水平方向の間隔
VerticalPadding	int	内部の垂直方向の間隔
AutoScroll	bool	必要に応じてスクロールバーを自動的に有効にします
AutoPersistStates	bool	展開／折りたたみの状態をセッション間で保持します
AllowDrop	bool	ドラッグ＆ドロップのサポートを有効にします
MinimumSize	Size	コントロールの最小サイズ

XPTaskBarBox レベル

プロパティ	型	目的
Text	string	ボックスヘッダーに表示するテキスト
Collapsed	bool	true に設定すると折りたたみ、false に設定すると展開します
ShowCollapseButton	bool	折りたたみボタンを表示／非表示にします
ToggleByButton	bool	ボタンで状態を切り替えられるようにします
HeaderBackColor	Color	ヘッダーの背景色
HeaderForeColor	Color	ヘッダーのテキスト色
HeaderFont	Font	ヘッダーのテキストフォント
HeaderTextAlign	StringAlignment	ヘッダーのテキスト配置
AnimationDelay	int	アニメーションフレーム間の遅延（ミリ秒）
AnimationPositionsCount	int	アニメーションのステップ数
PreferredChildPanelHeight	int	子コントロール用に確保する高さ
ShowToolTip	bool	項目のツールチップを有効にします
PADX	int	ヘッダーの水平方向の余白
PADY	int	ヘッダーの垂直方向の余白

XPTaskBarItem レベル

プロパティ	型	目的
Text	string	項目に表示するテキスト
ImageIndex	int	親ボックスの ImageList 内のインデックス
ToolTipText	string	項目にポインターを合わせたときのツールチップテキスト
Tag	object	イベントの振り分けに使うカスタムデータ

---

次のステップ： references/getting-started.md から始めて、最初の XPTaskBar コントロールをセットアップします。