syncfusion-winforms-xptoolbar

Syncfusion WinForms XPToolBar の実装

XPToolBar コントロールは、Microsoft Visual Studio に着想を得たスタンドアロンのツールバーで、頻繁に使用するコマンドやオプションに簡単にアクセスできます。さまざまな項目の種類、柔軟な配置、オーバーフロー処理、プロフェッショナルなテーマに対応しています。

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

次のようなニーズがある場合に、このスキルを使用します。

• アプリケーションのツールバー： ボタン、ドロップダウン、コンボボックスを備えた標準ツールバー
• Visual Studio スタイルのメニュー： 「ファイル」「編集」「表示」などのオプションを備えた、VS に着想を得たメニューバー
• クイックアクセスツールバー： 頻繁に使用するコマンドをコンパクトなツールバーに配置
• ドッキング可能なツールバー： 上、下、左、右の任意の側にドッキングできるツールバー
• 複数段のツールバー： 連続して積み重ねられた複数のツールバー
• ドロップダウンメニュー： サブメニューを備えた DropDownBarItem と ParentBarItem
• ツールバーコントロール： ツールバー内の ComboBoxBarItem、TextBoxBarItem、ListBarItem
• オーバーフロー管理： 収まりきらない項目を表示するシェブロンボタン
• テーマ付きツールバー： Office2007、Office2016、Metro のテーマ
• RTL アプリケーション： 右から左へ表示するツールバーレイアウト

コンポーネントの概要

XPToolBar（Syncfusion.Windows.Forms.Tools.XPMenus.XPToolBar）は、次の機能に対応した多用途のツールバーコントロールです。

• 8 種類の BarItem：
  • BarItem： 個別のメニュー／ツールバーボタン
  • ParentBarItem： 子項目を含むサブメニュー
  • DropDownBarItem： ドロップダウン形式のリスト選択
  • ComboBoxBarItem： 編集可能なコンボボックス
  • ListBarItem： リスト選択コントロール
  • StaticBarItem： クリックできないラベル／区切り
  • ToolbarListBarItem： ツールバーのリスト表示
  • TextBoxBarItem： テキスト入力ボックス
  • Separator： 項目間の視覚的な区切り
• 柔軟なドッキング： 上、下、左、右への配置
• 複数のツールバー： 連続したツールバー段の追加
• シェブロン／オーバーフローボタン： ツールバーの幅が狭すぎるときに、非表示の項目を表示
• 豊富なテーマ： Office2007、Office2016（Colorful／White／DarkGray／Black）、Metro
• カスタマイズ： 項目ごとのテキスト、色、フォント、画像、ツールヒント
• RTL 対応： 国際対応アプリ向けの右から左へのレイアウト
• ローカライズ： CultureInfo による多言語対応
• キーボードショートカット： BarItem へのキーボードショートカットの割り当て

主要な名前空間： Syncfusion.Windows.Forms.Tools.XPMenus

アセンブリ： Syncfusion.Tools.Windows.dll（および依存関係）

---

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

はじめに

📄 参照： references/getting-started.md

参照するタイミング： XPToolBar のインストール、構成、または最初の作成が必要な場合。

解説するトピック：

• アセンブリの配置と NuGet パッケージのインストール
• デザイナーからの XPToolBar の追加（ツールボックス、スマートタグ）
• コードからの XPToolBar の追加
• Panel／コンテナーコントロールを使用したツールバーの配置
• BarItem Collection Editor による項目の追加
• Bar.Items コレクションの管理
• 基本的なツールバーの設定と初期化

BarItem の種類とコレクション

📄 参照： references/baritem-types.md

参照するタイミング： ボタン、ドロップダウン、コンボボックスを追加したい場合や、さまざまな項目の種類を理解したい場合。

解説するトピック：

• BarItem（個別のボタン／メニュー項目）
• ParentBarItem（子項目を含むサブメニュー）
• DropDownBarItem（ドロップダウン形式の選択リスト）
• ComboBoxBarItem（編集可能なコンボボックスコントロール）
• ListBarItem（リスト選択）
• StaticBarItem（クリックできないラベル）
• ToolbarListBarItem（ツールバー項目のリスト）
• TextBoxBarItem（ツールバー内のテキスト入力）
• Separator（視覚的な区切り）
• Items コレクションを使ったコードからの項目追加
• 項目のプロパティ（Text、Image、Tooltip、Enabled）

ドッキングとレイアウト

📄 参照： references/docking-and-layout.md

参照するタイミング： ツールバーを配置したい場合や、複数段のツールバーを追加したい場合。

説明するトピック：

• ドッキング位置（Top、Bottom、Left、Right）
• Dock プロパティの設定
• 複数のツールバーを連続して配置する方法
• ツールバーの段を追加する方法
• コンテナーの要件（Panel、GroupBox など）
• ツールバーの配置戦略
• さまざまなシナリオに応じたレイアウトのベストプラクティス

シェブロンとオーバーフロー

📄 参照： references/chevron-and-overflow.md

参照するタイミング： オーバーフローの問題が発生した場合や、非表示のツールバー項目を管理したい場合。

説明するトピック：

• シェブロン／オーバーフローボタンの機能
• ツールバーの幅に収まらない項目の表示
• オーバーフローの動作と発生条件
• シェブロンの外観設定
• オーバーフローメニューでのユーザー操作
• ウィンドウサイズに応じたツールバー項目の管理

外観のカスタマイズ

📄 参照： references/appearance-customization.md

参照するタイミング： 色、フォント、画像、ツールチップをカスタマイズしたい場合。

説明するトピック：

• テキストのカスタマイズ（Text プロパティ）
• 背景色（BackColor プロパティ）
• 前景色（ForeColor プロパティ）
• 項目またはツールバーごとのフォント設定
• BarItems への画像の割り当て
• ツールチップの設定（項目ごとの ToolTip プロパティ）
• サイズと間隔の調整
• 項目ごとの外観のカスタマイズ

テーマとスタイル

📄 参照： references/themes-and-styling.md

参照するタイミング： Office テーマ、RTL サポート、またはローカライズが必要な場合。

説明するトピック：

• ビジュアルスタイル：Office2007（Blue、Silver、Black）
• Office2016 テーマ（Colorful、White、DarkGray、Black）
• Metro テーマ
• Style プロパティの設定
• アラビア語／ヘブライ語向けの RTL（右から左）サポート
• CultureInfo によるローカライズ
• キーボードショートカット（Ctrl+X、Alt+F など）
• カスタムアクション用の BarItems のトリガー

---

クイックスタートの例

メニュー項目付きの基本的なツールバー

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

// Create panel to host toolbar
Panel panel1 = new Panel();
panel1.Dock = DockStyle.Top;
panel1.Height = 50;

// Create XPToolBar
XPToolBar xpToolBar1 = new XPToolBar();

// Create menu items
BarItem fileItem = new BarItem();
fileItem.Text = "File";

ParentBarItem editItem = new ParentBarItem();
editItem.Text = "Edit";

// Add submenu items to Edit
BarItem cutItem = new BarItem { Text = "Cut" };
BarItem copyItem = new BarItem { Text = "Copy" };
BarItem pasteItem = new BarItem { Text = "Paste" };
editItem.Items.AddRange(new BarItem[] { cutItem, copyItem, pasteItem });

DropDownBarItem viewItem = new DropDownBarItem();
viewItem.Text = "View";

// Add items to toolbar
xpToolBar1.Bar.Items.AddRange(new BarItem[] { 
    fileItem, 
    editItem, 
    viewItem 
});

// Add toolbar to panel
panel1.Controls.Add(xpToolBar1);

// Add panel to form
this.Controls.Add(panel1);

Office2016 テーマを使ったツールバー

// Apply Office2016 Colorful theme
xpToolBar1.Style = VisualStyle.Office2016Colorful;

---

よく使われるパターン

サブメニュー項目付きのファイルメニュー

// Create File menu with submenu
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "File";

// Add submenu items
BarItem newItem = new BarItem { Text = "New", Image = Properties.Resources.New };
BarItem openItem = new BarItem { Text = "Open", Image = Properties.Resources.Open };
BarItem saveItem = new BarItem { Text = "Save", Image = Properties.Resources.Save };
BarItem separator = new BarItem { BarItemType = BarItemType.Separator };
BarItem exitItem = new BarItem { Text = "Exit" };

fileMenu.Items.AddRange(new BarItem[] { 
    newItem, 
    openItem, 
    saveItem, 
    separator, 
    exitItem 
});

// Handle click events
newItem.Click += (s, e) => CreateNewDocument();
openItem.Click += (s, e) => OpenDocument();
saveItem.Click += (s, e) => SaveDocument();
exitItem.Click += (s, e) => Application.Exit();

xpToolBar1.Bar.Items.Add(fileMenu);

使用する場面： ファイル操作を含む標準的なアプリケーションメニュー。

ComboBox と TextBox を備えたツールバー

// Font selector combo box
ComboBoxBarItem fontCombo = new ComboBoxBarItem();
fontCombo.Text = "Font:";
fontCombo.ChoiceList.AddRange(new string[] { "Arial", "Calibri", "Times New Roman" });
fontCombo.SelectedIndex = 0;

// Font size text box
TextBoxBarItem fontSizeTextBox = new TextBoxBarItem();
fontSizeTextBox.Text = "Size:";
fontSizeTextBox.TextBoxValue = "12";
fontSizeTextBox.MinimumSize = new Size(50, 20);

// Add to toolbar
xpToolBar1.Bar.Items.AddRange(new BarItem[] { 
    fontCombo, 
    fontSizeTextBox 
});

// Handle changes
fontCombo.SelectedIndexChanged += (s, e) => {
    string selectedFont = fontCombo.ChoiceList[fontCombo.SelectedIndex];
    ApplyFont(selectedFont);
};

使用する場面： テキストエディターや書式設定用のツールバー。

ドッキングされたツールバー（上部）

// Create toolbar with top docking
XPToolBar toolbar = new XPToolBar();
toolbar.Dock = DockStyle.Top;

// Add items
toolbar.Bar.Items.AddRange(new BarItem[] { 
    new BarItem { Text = "Home" },
    new BarItem { Text = "Insert" },
    new BarItem { Text = "View" }
});

// Add directly to form (no panel needed for simple top dock)
this.Controls.Add(toolbar);

使用する場面： 複雑なレイアウトを必要としない、上部にドッキングされたシンプルなツールバー。

複数段のツールバー

// First toolbar level (Menu bar)
Panel menuPanel = new Panel { Dock = DockStyle.Top, Height = 30 };
XPToolBar menuToolbar = new XPToolBar();
menuToolbar.Bar.Items.AddRange(new BarItem[] { 
    new ParentBarItem { Text = "File" },
    new ParentBarItem { Text = "Edit" },
    new ParentBarItem { Text = "View" }
});
menuPanel.Controls.Add(menuToolbar);

// Second toolbar level (Quick access)
Panel quickPanel = new Panel { Dock = DockStyle.Top, Height = 40 };
XPToolBar quickToolbar = new XPToolBar();
quickToolbar.Bar.Items.AddRange(new BarItem[] { 
    new BarItem { Text = "New", Image = Properties.Resources.New },
    new BarItem { Text = "Save", Image = Properties.Resources.Save },
    new BarItem { Text = "Undo", Image = Properties.Resources.Undo }
});
quickPanel.Controls.Add(quickToolbar);

// Add to form (order matters - add quick toolbar first for correct stacking)
this.Controls.Add(quickPanel);
this.Controls.Add(menuPanel);

使用する場面： メニューバーとクイックアクセスツールバーを備えた複雑なアプリケーション。

---

主なプロパティ

基本プロパティ

プロパティ	型	説明	使用する場面
Bar.Items	BarItemCollection	ツールバー項目のコレクション	ツールバーボタンやコントロールの追加／管理
Dock	DockStyle	ドッキング位置	ツールバーの配置（Top／Bottom／Left／Right）
Style	VisualStyle	ビジュアルテーマのスタイル	Office2007／2016／Metro テーマの適用

BarItem のプロパティ

プロパティ	型	説明	使用する場面
Text	string	項目のテキスト／キャプション	ボタンやメニューのラベルの設定
Image	Image	項目のアイコン	項目への視覚的なアイコンの追加
ToolTip	string	ツールチップのテキスト	ホバー時に表示する情報の提供
Enabled	bool	項目の有効／無効	項目の操作可否の制御
Visible	bool	項目の表示／非表示	項目の表示状態の切り替え

BarItem の種類の概要

• BarItem - 標準のボタン／メニュー項目
• ParentBarItem - サブメニュー項目を含むメニュー（.Items コレクションを使用）
• DropDownBarItem - ドロップダウンリスト（.ChoiceList を使用）
• ComboBoxBarItem - 編集可能なコンボボックス（.Items と .SelectedIndex を使用）
• ListBarItem - リスト選択コントロール
• StaticBarItem - クリックできないラベル
• TextBoxBarItem - テキスト入力（.TextBoxValue を使用）
• ToolbarListBarItem - ツールバー項目のリスト
• Separator - 視覚的な区切り（BarItemType = BarItemType.Separator を設定）

---

一般的なユースケース

1. アプリケーションのメニューバー

シナリオ： ファイル、編集、表示、ヘルプを含む標準的なメニューバーです。

• 最上位の各メニューに ParentBarItem を使用します
• 各 ParentBarItem にサブメニューの BarItem を追加します
• 項目グループの間に区切りを追加します
• アクションの Click イベントを処理します
• 参照：baritem-types.md

2. テキストエディターのツールバー

シナリオ： フォント、サイズ、太字、斜体を設定する書式設定ツールバーです。

• フォントの選択には ComboBoxBarItem を使用します
• フォントサイズには TextBoxBarItem を使用します
• 太字／斜体／下線には画像付きの BarItem を使用します
• 視覚的にわかりやすくするため、画像を使用します
• 参照：baritem-types.md、appearance-customization.md

3. リボン風のクイックアクセス

シナリオ： メインコンテンツの上に配置するクイックアクセスツールバーです。

• よく使うコマンドを含むツールバーを上部にドッキングします
• テキストなしの画像（アイコンのみのボタン）を使用します
• 各項目のツールチップを有効にします
• モダンな外観にするため、Office2016 テーマを適用します
• 参照：docking-and-layout.md、themes-and-styling.md

4. マルチレベルのツールバーシステム

シナリオ： メニューバー、クイックアクセスツールバー、書式設定ツールバーを組み合わせます。

• 複数の Panel コンテナーを作成します
• 各パネルに XPToolBar を 1 つ追加します
• 適切なドッキング順序でパネルを積み重ねます
• すべてのツールバーに一貫したテーマを適用します
• 参照：docking-and-layout.md

5. ローカライズされたツールバー

シナリオ： 国際対応アプリケーション（アラビア語／ヘブライ語）向けのツールバーです。

• RTL サポートを有効にします
• ローカライズには CultureInfo を使用します
• ローカライズされた文字列をリソースから読み込みます
• さまざまな言語でテストします
• 参照：themes-and-styling.md

6. 動的なツールバー

シナリオ： コンテキストに応じて、実行時にツールバー項目を追加／削除します。

• Bar.Items.Add/Remove メソッドを使用します
• Visible プロパティで項目の表示／非表示を切り替えます
• Enabled プロパティで有効／無効を切り替えます
• 変更後にツールバーレイアウトを更新します
• 参照：baritem-types.md

---

イベント

一般的な BarItem イベント：

• Click - 項目がクリックされたときに発生します
• SelectedIndexChanged - ComboBoxBarItem／DropDownBarItem の選択が変更されたときに発生します

barItem1.Click += (sender, e) => {
    // Handle button click
    MessageBox.Show("Item clicked!");
};

comboBoxBarItem1.SelectedIndexChanged += (sender, e) => {
    string selected = comboBoxBarItem1.ChoiceList[comboBoxBarItem1.SelectedIndex];
    // Handle selection change
};

---

ベストプラクティス

1. コンテナーの使用： 適切に配置するため、XPToolBar は必ず Panel またはコンテナー内に配置します
2. テーマの一貫性： ツールバーの Style をアプリケーションのテーマに合わせます
3. 画像の品質： BarItem の画像には高品質なアイコン（16x16 または 24x24）を使用します
4. ツールチップ： アイコンのみのボタンには必ずツールチップを設定します
5. オーバーフローの管理： オーバーフローを最小限に抑えるため、ツールバー項目の数を適切に保ちます
6. イベント処理： すべての操作可能な BarItem の Click イベントをサブスクライブします
7. 区切り： 関連する項目を視覚的にグループ化するため、区切りを使用します
8. キーボードショートカット： よく使うコマンドにショートカットを割り当てます
9. 動的な更新： 項目を削除するのではなく、Enabled／Visible プロパティを使用します
10. ドッキング順序： 複数のツールバーを積み重ねる場合は、パネルを逆順に追加します

---

関連項目

• Syncfusion XPToolBar ドキュメント
• XPToolBar API リファレンス
• BarItem API リファレンス