syncfusion-winforms-ribbon

Syncfusion WinForms RibbonControlAdv の実装

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

Microsoft Office 風のリボンインターフェイスを作成するために、Syncfusion の WinForms RibbonControlAdv を実装する際にこのスキルを使用します。このコンポーネントは、タブ、グループ、さまざまなコントロールタイプ、Backstage ビュー、クイックアクセスツールバー、最新の簡易レイアウトオプションを備えた包括的なリボンメニューシステムを提供します。

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

• Office 風のリボンインターフェイスを作成する（Office 2007／2010／2013／2016／Touch スタイル）
• コマンドを整理するためにタブとグループ（ToolStripEx）を追加する
• Backstage ビューまたはアプリケーションメニューを実装する
• クイックアクセスツールバー（QAT）の機能を追加する
• コンパクトな表示向けに簡易レイアウトモードをサポートする
• リボンの状態（最大化、最小化、自動非表示）を処理する
• 各種リボンコントロール（ボタン、ドロップダウン、ギャラリー、コンボボックス）を追加する
• デザイン時または実行時にリボンの外観と動作をカスタマイズする
• キーボードナビゲーションとタッチインターフェイスをサポートする

コンポーネントの概要

RibbonControlAdv は、Microsoft Office に似た、ナビゲーションしやすい単一のユーザーインターフェイスに、アプリケーションに必要なすべてのツールを収める高度なナビゲーションコントロールです。次の機能を提供します。

• 複数のビジュアルスタイル： Office2007、Office2010、Office2013、Office2016、TouchStyle
• 柔軟なレイアウト： 標準レイアウトモードと簡易レイアウトモード
• 豊富なコントロールのサポート： ボタン、ドロップダウン、分割ボタン、コンボボックス、ギャラリー、チェックボックス、ラジオボタン、テキストボックスなど
• クイックアクセスツールバー（QAT）： よく使うコマンドにワンクリックでアクセス
• BackStage ビュー： Office 2016 スタイルのアプリケーションメニュー
• アプリケーションメニュー： Office 2007 スタイルのメニューボタン
• 動的なサイズ変更： ウィンドウサイズに応じたインテリジェントな折りたたみ動作
• カスタマイズ： ダイアログによる実行時のカスタマイズ
• キーボードとタッチのサポート： 完全なキーボードナビゲーションとタッチに最適化されたインターフェイス

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

はじめに

📄 参照： references/getting-started.md

• RibbonControlAdv のインストールと追加（デザイナーおよびコード）
• 適切なビジュアルスタイルを適用するための RibbonForm の設定
• ビジュアルスタイルの適用（Office2007、Office2010、Office2013、Office2016、TouchStyle）
• 機能を整理するためのタブ（ToolStripTabItem）の追加
• タブ内でのグループ（ToolStripEx）の作成
• 基本的なボタンコントロールの追加
• 最小構成で動作する完全なサンプル

参照するタイミング： 新しいリボンの実装を開始するとき、基本構造を設定するとき、ビジュアルスタイルを選択するとき。

---

リボンコントロール

📄 参照： references/ribbon-controls.md

• ToolStripButton - 標準的なクリック可能ボタン
• ToolStripRadioButton - ラジオボタンによる選択
• ToolStripDropDownButton - ドロップダウンメニュー
• ToolStripSplitButton/Ex - ドロップダウン付き分割ボタン
• ToolStripComboBoxEx - ドロップダウン選択リスト
• ToolStripGallery - スクロール機能付きのビジュアルアイテムギャラリー
• ToolStripCheckBox - チェックボックスオプション
• ToolStripTextBox - テキスト入力フィールド
• ToolStripProgressBar - 進行状況インジケーター
• ToolStripLabel - テキストラベル
• ToolStripSeparator - 視覚的な区切り線
• ToolStripPanelItem - 複数行レイアウト用コンテナー
• 各コントロールタイプのコード例

参照するタイミング： リボンに特定のコントロールタイプを追加するとき、コントロールのプロパティやイベントについて理解するとき、複雑なコントロールレイアウトを実装するとき。

---

リボンの状態と表示モード

📄 参照： references/ribbon-states.md

• 最大化、最小化、自動非表示の状態
• DisplayOption プロパティ（ShowTabsAndCommands、ShowTabs、AutoHide）
• 状態変更の方法（表示オプションボタン、ダブルクリック、最小化ボタン、コンテキストメニュー）
• DisplayOptionChanged イベント
• キーボードショートカット（Ctrl+F1）
• 最小化／最大化ボタンのツールチップ
• ShowRibbonDisplayOptionButton プロパティと ShowMinimizeButton プロパティ

参照するタイミング： リボンの表示／非表示を制御するとき、最小化／最大化機能を実装するとき、リボンの状態変更を処理するとき、最小化／最大化に関する問題をトラブルシューティングするとき。

---

クイックアクセスツールバー（QAT）

📄 参照： references/quick-access-toolbar.md

• QAT の概要と表示制御
• 項目の追加（コンテキストメニュー、カスタマイズウィンドウ、AddQuickItem メソッド）
• 項目の削除と QAT への項目追加の制限
• クイックアクセスメニューの設定
• QATImageProvider を使用した QAT 項目のカスタム画像
• バックステージ項目の QAT への追加
• プログラムによる新しい QAT 項目の作成
• QAT イベント（BeforeAddItem、BeforeRemoveItem、QuickItemAdded）

参照するタイミング： クイックアクセスツールバーの実装、よく使うコマンドの追加、QAT の外観のカスタマイズ、QAT イベントの処理。

---

バックステージビュー

📄 参照： references/backstage.md

• BackStage の概要（Office 2016 形式のアプリケーションメニュー）
• BackStageView コンポーネントの作成と設定
• コンテンツページ用の BackStage タブの追加
• 操作用の BackStage ボタンの追加
• 視覚的なグループ化のための BackStageSeparator
• MenuButtonText による RibbonControlAdv との連携
• 完全なコード例

参照するタイミング： Office 2016 形式のバックステージの実装、ファイル／アプリケーションメニューの作成、バックステージのタブやボタンの追加。

---

アプリケーションメニュー

📄 参照： references/application-menu.md

• ApplicationMenu の概要（Office 2007 形式のメニュー）
• メニューパネルへのコントロールの追加
• ミニツールバーとの連携
• ApplicationMenu と BackStage の違い
• ApplicationMenu と BackStage の使い分け

参照するタイミング： Office 2007 形式のアプリケーションメニューの実装、Office2007 リボンスタイルにおけるメニューボタンの機能の理解。

---

簡易レイアウト

📄 参照： references/simplified-layout.md

• LayoutMode プロパティ（Normal と Simplified）
• 実行時の切り替えに使用する EnableSimplifiedLayoutMode
• RibbonItemDisplayMode 列挙型（Normal、Simplified、OverflowMenu）
• 項目の表示制御に使用する SetDisplayMode 関数
• 中サイズ画像のサポート（SetMediumItemImage による 20x20 アイコン）
• サイズ変更時のオーバーフローメニューの動作
• QAT ウィンドウからの実行時カスタマイズ
• 簡易レイアウトのベストプラクティス

参照するタイミング： コンパクトなリボンインターフェースの実装、レイアウト切り替えへの対応、オーバーフローメニューの設定、画面スペースの最適化。

---

カスタマイズと実行時の設定

📄 参照： references/customization.md

• コンテキストメニューのオプションとカスタマイズ
• クイックアクセスツールバーのカスタマイズダイアログ
• 実行時カスタマイズ用のリボンのカスタマイズダイアログ
• カスタムコンテキストメニュー項目の追加（BeforeContextMenuOpen イベント）
• 状態の保存／読み込みに対応するシリアル化
• デザイナーのサポートとスマートタグ
• 項目を制限する SetUseInCustomQuickAccessDialog

参照するタイミング： 実行時カスタマイズの有効化、カスタムコンテキストメニュー項目の追加、リボンの状態の保存／読み込みの実装、カスタマイズオプションの制限。

---

サイズ変更時の動作と折りたたみオプション

📄 参照： references/resize-behavior.md

• 既定の折りたたみ動作（即時にドロップダウンへ変換）
• CollapseBehavior プロパティ（Default と Office2010）
• Office2010 の折りたたみ動作（Large → Small → ExtraSmall → Dropdown）
• 複数サイズの画像に対応する ToolStripExImageProvider
• SetLargeItemImage および SetSmallItemImage メソッド
• ウィンドウ幅に応じた動的なサイズ変更
• 起動ボタンの設定（ShowLauncher プロパティ）

参照するタイミング： サイズ変更時の動作の設定、複数サイズのアイコンの実装、折りたたみパターンのカスタマイズ、グループへの起動ボタンの追加。

高度な機能

📄 参照： references/advanced-features.md

• タブの操作（ToolStripTabItem の管理）
• コンテキストに応じたタブのためのコンテキストタブグループ
• フォーム下部での StatusStripEx の統合
• MDI アプリケーション向けのリボンのマージ対応
• キーボード対応とキー ヒント
• タッチ対応とタッチ操作に最適化された UI
• ローカライズ対応
• 外観のカスタマイズ（色、フォント、テーマ）
• ビジュアルデザイン用のリボンデザイナー
• ツールチップとスーパーツールチップの設定
• 従来の Windows スタイル向け EnableAeroTheme

参照するタイミング： 高度なシナリオ、コンテキストタブ、MDI 統合、キーボードショートカット、タッチ対応、ローカライズ、テーマのカスタマイズを実装する場合。

---

クイックスタートの例

タブと基本的なコントロールを備えたリボンを作成する最小限の例を示します。

using Syncfusion.Windows.Forms.Tools;

// 1. Make your form inherit from RibbonForm instead of Form
public partial class Form1 : RibbonForm
{
    private RibbonControlAdv ribbonControlAdv1;
    private ToolStripTabItem homeTab;
    private ToolStripEx clipboardToolStrip;
    private ToolStripButton pasteButton;
    private ToolStripButton cutButton;
    private ToolStripButton copyButton;
    
    public Form1()
    {
        InitializeComponent();
        InitializeRibbon();
    }
    
    private void InitializeRibbon()
    {
        // Create ribbon control
        ribbonControlAdv1 = new RibbonControlAdv();
        ribbonControlAdv1.RibbonStyle = RibbonStyle.Office2016;
        ribbonControlAdv1.MenuButtonText = "File";
        
        // Create Home tab
        homeTab = new ToolStripTabItem();
        homeTab.Text = "Home";
        
        // Create Clipboard group (ToolStripEx)
        clipboardToolStrip = new ToolStripEx();
        clipboardToolStrip.Text = "Clipboard";
        
        // Add buttons to group
        pasteButton = new ToolStripButton();
        pasteButton.Text = "Paste";
        pasteButton.Image = Image.FromFile("paste.png");
        
        cutButton = new ToolStripButton();
        cutButton.Text = "Cut";
        cutButton.Image = Image.FromFile("cut.png");
        
        copyButton = new ToolStripButton();
        copyButton.Text = "Copy";
        copyButton.Image = Image.FromFile("copy.png");
        
        // Build hierarchy
        clipboardToolStrip.Items.AddRange(new ToolStripItem[] { 
            pasteButton, cutButton, copyButton 
        });
        homeTab.Panel.Controls.Add(clipboardToolStrip);
        ribbonControlAdv1.Header.AddMainItem(homeTab);
        
        // Add ribbon to form
        this.Controls.Add(ribbonControlAdv1);
    }
}

よく使われるパターン

複数のタブを追加する

ToolStripTabItem homeTab = new ToolStripTabItem { Text = "Home" };
ToolStripEx clipboardGroup = new ToolStripEx { Text = "Clipboard" };
homeTab.Panel.Controls.Add(clipboardGroup);
ribbonControlAdv1.Header.AddMainItem(homeTab);

クイックアクセスツールバー

ribbonControlAdv1.Header.AddQuickItem(new QuickButtonReflectable(saveButton));

シンプルなレイアウト

ribbonControlAdv1.LayoutMode = RibbonLayoutMode.Simplified;
ribbonControlAdv1.EnableSimplifiedLayoutMode = true;
ribbonControlAdv1.SetDisplayMode(pasteButton, RibbonItemDisplayMode.Simplified);

状態の変更

ribbonControlAdv1.DisplayOptionChanged += (sender, e) => {
    Console.WriteLine($"Ribbon changed to {e.NewValue}");
};

BackStage の設定

BackStage backStage1 = new BackStage();
backStage1.Controls.Add(new BackStageTab { Text = "Info" });
ribbonControlAdv1.BackStage = backStage1;

複数サイズの画像

ribbonControlAdv1.CollapseBehavior = CollapseBehavior.Office2010;
ToolStripExImageProvider imageProvider = new ToolStripExImageProvider(clipboardToolStrip);
imageProvider.SetLargeItemImage(pasteButton, 0);
imageProvider.SetSmallItemImage(pasteButton, 0);

主要なプロパティとメソッド

必須プロパティ

• RibbonStyle - Office2007/2010/2013/2016/TouchStyle
• LayoutMode - 標準レイアウトまたはシンプルなレイアウト
• DisplayOption - ShowTabsAndCommands、ShowTabs、AutoHide
• CollapseBehavior - 既定または Office2010 の折りたたみパターン
• MenuButtonText - ファイル／アプリケーションメニューボタンのテキスト
• BackStage - 関連付けられた BackStage ビュー
• EnableSimplifiedLayoutMode - レイアウトの切り替えを許可

主要なメソッド

• Header.AddMainItem(tab) - リボンにタブを追加
• Header.AddQuickItem(item) - QAT に項目を追加
• SetDisplayMode(item, mode) - 項目の表示状態を制御

重要なイベント

• DisplayOptionChanged - リボンの状態変更
• BeforeContextMenuOpen - コンテキストメニューをカスタマイズ
• Header.QuickItems.BeforeAddItem/BeforeRemoveItem - QAT の変更

よくあるユースケース

ユースケース 1：Office スタイルのドキュメントエディター

クリップボード操作、書式設定ツール、表示オプションを含む、ホーム、挿入、表示タブを備えた完全なリボンインターフェイスを実装します。

移動先： getting-started.md → ribbon-controls.md → quick-access-toolbar.md

---

ユースケース 2：BackStage 設定を備えたアプリケーション

ファイル操作、オプション、アプリケーション設定向けのモダンな BackStage ビューを備えたアプリケーションを作成します。

移動先： backstage.md → customization.md

---

ユースケース 3：コンパクトなモバイルスタイルのインターフェイス

1. Office スタイルのドキュメントエディター - ホーム、挿入、表示タブを備えた完全なリボン → getting-started.md、ribbon-controls.md
2. BackStage 設定 - ファイル操作向けのモダンな BackStage ビュー → backstage.md
3. コンパクトなインターフェイス - オーバーフローメニューを備えたシンプルなレイアウト → simplified-layout.md
4. カスタマイズ可能なアプリケーション - 実行時のリボンのカスタマイズ → customization.md
5. コンテキストタブを備えた MDI - 子ウィンドウに応じて変化するリボン → advanced-feature 解決策： QATImageProvider を使用して、QAT 用に個別の画像を設定します。標準のボタン画像は適切に拡大縮小されない場合があります。QATImageProvider の使用方法については、quick-access-toolbar.md を参照してください。

---

問題：ウィンドウのサイズ変更中にコントロールが消える

問題： ウィンドウを小さくすると、リボンのコントロールが表示されなくなります。

解決策： これは想定された折りたたみ動作です。段階的にサイズを変更するには CollapseBehavior を Office2010 に設定するか、ToolStripExImageProvider を使用して複数サイズの画像を実装してください。resize-behavior.md を参照してください。

---

問題：シンプルなレイアウトの項目が表示されない

問題： シンプルなレイアウトに切り替えると、項目が表示されません。

解決策： SetDisplayMode を使用して項目の表示状態を設定します。レイアウトをまたいで表示するには、RibbonItemDisplayMode.Simplified または Normal | Simplified を設定してください。SetMediumItemImage を使って中サイズの画像（20x20）を追加します。simplified-layout.md を参照してください。

---

問題：BackStage が表示されない

問題： メニューボタンに BackStage ビューが表示されません。

解決策： ribbonControlAdv1.BackStage が設定されていること、および MenuButtonText が構成されていることを確認してください。BackStage は Office 2016 スタイルでのみ動作します。Office 2007 の場合は、代わりに ApplicationMenu を使用してください。backstage.md と application-menu.md を参照してください。

---

ベストプラクティス

1. RibbonForm を使用する： 適切なビジュアルスタイルとテーマのサポートを実現するため、常に Form ではなく RibbonForm を継承してください。

2. 論理的に整理する： 関連するコマンドを ToolStripEx グループにまとめ、ワークフローに沿ってタブ内のグループを整理してください。

• 最小化が機能しない - DisplayOption を確認してください。AutoHide は一時的に表示します。継続して表示するには ShowTabsAndCommands を使用してください → ribbon-states.md
• QAT のカスタムアイコンが表示されない - QAT 専用の画像には QATImageProvider を使用してください → quick-access-toolbar.md
• サイズ変更時にコントロールが消える - これは想定された折りたたみ動作です。複数サイズの画像とともに CollapseBehavior.Office2010 を使用してください → resize-behavior.md
• 簡易レイアウトの項目が非表示になる - SetDisplayMode(item, RibbonItemDisplayMode.Simplified) を使用し、20x20 の中サイズ画像を追加してください → simplified-layout.md
• BackStage が表示されない - BackStage プロパティが設定されていること、および MenuButtonText が構成されていることを確認してください。Office2016 スタイルが必要です（Office2007 では ApplicationMenu を使用してください） → backstage.md- RibbonForm を使用する - 適切なスタイルとテーマのサポートのために RibbonForm を継承してください
• 論理的に整理する - 関連するコマンドを ToolStripEx にまとめ、ワークフローに沿って整理してください
• QAT を実装する - 頻繁に使用するコマンドのためにクイックアクセスツールバーを有効にしてください
• 複数サイズの画像 - すべての状態に対応する 32x32、16x16、20x20 の画像を用意してください
• 状態変更を処理する - DisplayOptionChanged イベントを使用してユーザー設定を保存してください
• 実行時のカスタマイズ - ユーザーが個人設定できるよう、カスタマイズダイアログを有効にしてください
• キーボードとタッチ - 組み込みの KeyTips とタッチサポートを活用してください
• コンテキストタブ - コンテキストに応じたタブを表示してください（例：画像の選択時に「画像ツール」を表示）
• サイズ変更をテストする - ウィンドウサイズが異なる場合でも、コントロールが適切に折りたたまれることを確認してください