syncfusion-wpf-toolbar

Syncfusion WPF ToolBarAdv の実装

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

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

• ToolBarAdv コントロールを実装する：Syncfusion.Shared.WPF アセンブリを使用する WPF アプリケーションで
• コマンドツールバーを作成する：ボタン、区切り線、カスタムコントロールを含むツールバーを作成する
• オーバーフロー項目を処理する：ツールバーのコンテンツが利用可能なスペースを超える場合に
• フローティングツールバーを実装する：切り離して、異なる位置にドッキングできるツールバーを実装する
• ToolBarManager を使用する：上、下、左、右の位置にツールバーを配置する
• バンドの配置を設定する：ToolBarTrayAdv 内のツールバーレイアウトを制御する
• ボタン機能を追加／削除する：ユーザーがツールバー項目の表示／非表示を切り替えられるようにする
• ツールバーの外観をカスタマイズする：テーマ、アイコンテンプレート、スタイルを使用する
• ツールバーの状態を動的に管理する（ドッキング、フローティング、非表示）
• グリッパーコントロールを実装する：ツールバーをドラッグ＆ドロップで移動できるようにする

コンポーネントの概要

ToolBarAdv は、関連するコマンドやコントロールをまとめるコンテナーコントロールで、通常はアクションを実行するボタンで構成されます。次の機能を備えています。

• 柔軟な配置：Band プロパティと BandIndex プロパティを使用
• オーバーフローパネル：表示可能なスペースに収まらない項目を表示
• 複数の状態：ドッキング、フローティング、非表示
• ToolBarManager との連携：複数の位置へのドッキングに対応
• グリッパーコントロール：ユーザー操作による位置変更に対応
• アイコンテンプレート：パスデータとフォントアイコンに対応
• 追加／削除ボタン：ユーザーが項目の表示／非表示をカスタマイズ可能
• テーマのサポート：SfSkinManager を使用

主要なコントロール：

• ToolBarAdv - メインのツールバーコンテナー
• ToolBarTrayAdv - 複数のツールバーをバンド単位で整理するコンテナー
• ToolBarManager - 上／下／左／右にツールバーを配置するレイアウトマネージャー
• ToolBarItemSeparator - ツールバー項目間の視覚的な区切り線

アセンブリ： Syncfusion.Shared.WPF
名前空間： Syncfusion.Windows.Tools.Controls

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

はじめに

📄 参照： references/getting-started.md

• アセンブリと NuGet パッケージのインストール
• XAML と C# による ToolBarAdv の作成
• 基本構造（グリッパー、オーバーフローボタン）
• ツールバーへのボタンとコントロールの追加
• パスデータを使用したアイコンテンプレートの設定
• 初期の外観とスタイル設定
• ライセンスキーの登録（v16.2.0.x+）

配置とレイアウト

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

• ツールバーの配置に使用する Band プロパティと BandIndex プロパティ
• オーバーフローの処理（OverflowMode.Always、Never、AsNeeded）
• グリッパーの表示制御
• ToolBarTrayAdv の向き（水平／垂直）
• 複数のツールバーをバンド内に配置
• オーバーフローパネルの動作

追加／削除ボタンの機能

📄 参照： references/add-remove-buttons.md

• EnableAddRemoveButton 機能
• Icon プロパティと Label プロパティを使用した項目の追加
• IsAvailable 添付プロパティを使用したツールバー項目の非表示
• ToolBarItemInfoCollection の管理
• ユーザー操作による項目の表示設定のカスタマイズ

ツールバーの状態と動作

📄 参照： references/toolbar-states.md

• ToolBarState プロパティ（ドッキング、フローティング、非表示）
• FloatingBarLocation の設定
• ドッキング制限（CanDockAtTop/Bottom/Left/Right）
• ToolBarStateChanged イベントの処理
• フローティングツールバーのライフサイクル
• 状態の遷移と管理

ToolBarManager との連携

📄 参照： references/toolbar-manager.md

• TopToolBarTray、BottomToolBarTray、LeftToolBarTray、RightToolBarTray
• 複数の位置へのツールバーレイアウト
• 残りのスペースへのコンテンツ配置
• IsLocked プロパティによる位置変更の防止
• フローティングツールバーの要件

カスタマイズとテーマ設定

📄 参照： references/customization-theming.md

• FloatingToolBarStyle プロパティ
• 前景色のカスタマイズ
• FrameworkElement のスタイルに対する ControlsResourceDictionary
• SfSkinManager によるテーマの適用
• カスタムテーマ用の ThemeStudio
• 組み込みテーマのオプション

クイックスタートの例

ボタンを使用した基本的な ToolBarAdv

XAML：

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <syncfusion:ToolBarTrayAdv>
        <syncfusion:ToolBarAdv ToolBarName="Standard" Height="40">
            
            <Button Width="22" Height="22" ToolTip="New">
                <Image Source="Images/NewDocumentHS.png" Width="16" Height="16"/>
            </Button>
            
            
            <Button Width="22" Height="22" ToolTip="Open">
                <Image Source="Images/openHS.png" Width="16" Height="16"/>
            </Button>
            
            
            <syncfusion:ToolBarItemSeparator />
            
            
            <Button Width="22" Height="22" ToolTip="Save">
                <Image Source="Images/saveHS.png" Width="16" Height="16"/>
            </Button>
        </syncfusion:ToolBarAdv>
    </syncfusion:ToolBarTrayAdv>
</Window>

C#：

using Syncfusion.Windows.Tools.Controls;

// Create toolbar
ToolBarAdv toolBar = new ToolBarAdv();
toolBar.ToolBarName = "Standard";
toolBar.Height = 40;

// Add New button
Button newButton = new Button
{
    Width = 22,
    Height = 22,
    ToolTip = "New",
    Content = new Image 
    { 
        Source = new BitmapImage(new Uri("Images/NewDocumentHS.png", UriKind.Relative)),
        Width = 16,
        Height = 16
    }
};
toolBar.Items.Add(newButton);

// Add to ToolBarTray
ToolBarTrayAdv tray = new ToolBarTrayAdv();
tray.ToolBars.Add(toolBar);

// Add to window
this.Content = tray;

複数の位置に配置する ToolBarManager

XAML：

<syncfusion:ToolBarManager x:Name="toolBarManager">
    
    <syncfusion:ToolBarManager.TopToolBarTray>
        <syncfusion:ToolBarTrayAdv>
            <syncfusion:ToolBarAdv ToolBarName="File">
                <Button Width="22" Height="22" ToolTip="New">
                    <Image Source="Images/NewDocumentHS.png" Width="16" Height="16"/>
                </Button>
            </syncfusion:ToolBarAdv>
        </syncfusion:ToolBarTrayAdv>
    </syncfusion:ToolBarManager.TopToolBarTray>
    
    
    <syncfusion:ToolBarManager.LeftToolBarTray>
        <syncfusion:ToolBarTrayAdv Orientation="Vertical">
            <syncfusion:ToolBarAdv ToolBarName="Tools">
                <Button Width="22" Height="22" ToolTip="Cut">
                    <Image Source="Images/CutHS.png" Width="16" Height="16"/>
                </Button>
            </syncfusion:ToolBarAdv>
        </syncfusion:ToolBarTrayAdv>
    </syncfusion:ToolBarManager.LeftToolBarTray>
    
    
    <syncfusion:ToolBarManager.Content>
        <TextBox Text="Your application content here"/>
    </syncfusion:ToolBarManager.Content>
</syncfusion:ToolBarManager>

よく使われるパターン

パターン 1：複数のツールバーのバンド位置設定

<syncfusion:ToolBarTrayAdv>
    
    <syncfusion:ToolBarAdv Band="0" BandIndex="0" ToolBarName="Standard">
        <Button Content="New"/>
        <Button Content="Open"/>
    </syncfusion:ToolBarAdv>
    
    
    <syncfusion:ToolBarAdv Band="0" BandIndex="1" ToolBarName="Extras">
        <Button Content="Cut"/>
        <Button Content="Copy"/>
    </syncfusion:ToolBarAdv>
    
    
    <syncfusion:ToolBarAdv Band="1" BandIndex="0" ToolBarName="Format">
        <Button Content="Bold"/>
        <Button Content="Italic"/>
    </syncfusion:ToolBarAdv>
</syncfusion:ToolBarTrayAdv>

パターン 2：オーバーフローモードの制御

<syncfusion:ToolBarAdv>
    
    <Button syncfusion:ToolBarAdv.OverflowMode="Never"
            Content="Important"/>
    
    
    <Button syncfusion:ToolBarAdv.OverflowMode="AsNeeded"
            Content="Normal"/>
    
    
    <Button syncfusion:ToolBarAdv.OverflowMode="Always"
            Content="Advanced"/>
</syncfusion:ToolBarAdv>

パターン 3：ラベル付きボタンの追加／削除

<syncfusion:ToolBarAdv EnableAddRemoveButton="True">
    <Button syncfusion:ToolBarAdv.Label="New Document"
            syncfusion:ToolBarAdv.Icon="Images/NewDocumentHS.png">
        <Image Source="Images/NewDocumentHS.png" Width="16" Height="16"/>
    </Button>
    
    <Button syncfusion:ToolBarAdv.Label="Open Document"
            syncfusion:ToolBarAdv.Icon="Images/openHS.png">
        <Image Source="Images/openHS.png" Width="16" Height="16"/>
    </Button>
</syncfusion:ToolBarAdv>

パターン 4：フローティングツールバーの設定

<syncfusion:ToolBarManager>
    <syncfusion:ToolBarManager.TopToolBarTray>
        <syncfusion:ToolBarTrayAdv>
            <syncfusion:ToolBarAdv 
                ToolBarName="FloatingTools"
                syncfusion:ToolBarManager.ToolBarState="Floating"
                FloatingBarLocation="500,300">
                <Button Content="Tool 1"/>
                <Button Content="Tool 2"/>
            </syncfusion:ToolBarAdv>
        </syncfusion:ToolBarTrayAdv>
    </syncfusion:ToolBarManager.TopToolBarTray>
</syncfusion:ToolBarManager>

主なプロパティ

ToolBarAdv のプロパティ

プロパティ	説明	型	使用するタイミング
Band	ツールバーを配置するバンドのインデックス	int	ツールバーを特定の行／列に配置する
BandIndex	バンド内での位置	int	同じバンド内の複数のツールバーの順序を指定する
ToolBarName	ツールバーの表示名	string	ユーザーがツールバーを識別できるようにする
GripperVisibility	グリッパーハンドルの表示／非表示	Visibility	ユーザーによる位置変更の可否を制御する
FloatingBarLocation	フローティング状態での位置	Point	カスタムのフローティング位置を設定する
IsOverflowOpen	オーバーフローポップアップの開閉状態	bool	オーバーフローをプログラムから開閉する
EnableAddRemoveButton	追加／削除メニューの表示	bool	ユーザーが表示項目をカスタマイズできるようにする

ToolBarManager のプロパティ

プロパティ	説明	型	使用するタイミング
TopToolBarTray	上部のツールバートレイ	ToolBarTrayAdv	ツールバーを上部に配置する
BottomToolBarTray	下部のツールバートレイ	ToolBarTrayAdv	ツールバーを下部に配置する
LeftToolBarTray	左側のツールバートレイ	ToolBarTrayAdv	ツールバーを左側に配置する
RightToolBarTray	右側のツールバートレイ	ToolBarTrayAdv	ツールバーを右側に配置する
CanDockAtTop/Bottom/Left/Right	指定した位置へのドッキングを許可する	bool	ドッキング可能な位置を制限する
Content	アプリケーションのメインコンテンツ	UIElement	残りの領域に表示するコンテンツ

よくあるユースケース

ユースケース 1：アプリケーションのメニューバー

ファイル、編集、書式設定のコマンドを上部に配置した標準的なアプリケーションツールバーを作成します。

対象： ドキュメントエディター、IDE、生産性向上アプリケーションの構築
参照： references/getting-started.md、references/toolbar-manager.md

ユースケース 2：コンテキストに応じたツールバー

複数のツールバーをバンドごとに整理し、現在のコンテキストや選択内容に応じて表示／非表示を切り替えます。

対象： モード固有のコマンドを備えた複雑なアプリケーション
参照： references/positioning-and-layout.md、references/add-remove-buttons.md

ユースケース 3：フローティングツールパレット

ユーザーが画面上の任意の場所に配置できる、取り外し可能なツールバーです。

対象： グラフィックエディター、デザインツール、取り外し可能なパネルを備えたアプリケーション
参照： references/toolbar-states.md、references/toolbar-manager.md

ユースケース 4：ユーザーがカスタマイズできるツールバー

ユーザーが自分の好みに応じてツールバー項目を表示／非表示にできるようにします。

対象： ワークスペースをカスタマイズしたい上級ユーザー向けのアプリケーション
参照： references/add-remove-buttons.md

ベストプラクティス

1. ツールバーを複数の位置（上部／下部／左側／右側）に配置する場合は、ToolBarManager を使用します
2. ユーザーが識別しやすいように、すべてのツールバーに ToolBarName を設定します
3. OverflowMode は戦略的に設定し、重要なボタンは Never を指定して常に表示します
4. オプションのコマンドが多数あるパワーユーザー向けのシナリオでは、Add/Remove ボタンを有効にします
5. EnableAddRemoveButton が true の場合は、Icon と Label の添付プロパティを使用します
6. フローティングツールバーが使いやすい位置に表示されるよう、適切な FloatingBarLocation を設定します
7. プロフェッショナルな外観にするため、SfSkinManager を使用してテーマを統一して適用します
8. ラスター画像の代わりに、拡大縮小可能なベクターアイコンとして IconTemplate を使用します
9. 関連するコマンドを区切り線で区分し、同じツールバーにまとめます
10. オーバーフローが正しく機能することを確認するため、さまざまなウィンドウサイズでツールバーの動作をテストします