syncfusion-winforms-xptoolbar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion WinForms XPToolBar

实现Syncfusion WinForms XPToolBar

The XPToolBar control is a Microsoft Visual Studio-inspired standalone toolbar that provides convenient access to frequently used commands and options. It supports various item types, flexible positioning, overflow handling, and professional themes.
XPToolBar控件是受Microsoft Visual Studio启发的独立工具栏,可便捷访问常用命令和选项。它支持多种条目类型、灵活定位、溢出处理和专业主题。

When to Use This Skill

何时使用本技能

Use this skill when the user needs to:
  • Application Toolbars: Standard toolbar with buttons, dropdowns, and combo boxes
  • Visual Studio-Style Menus: VS-inspired menu bars with File, Edit, View options
  • Quick Access Toolbars: Frequently used commands in a compact toolbar
  • Dockable Toolbars: Toolbars that can dock to any side (Top, Bottom, Left, Right)
  • Multiple Toolbar Levels: Several toolbars stacked consecutively
  • Dropdown Menus: DropDownBarItem and ParentBarItem with submenus
  • Toolbar Controls: ComboBoxBarItem, TextBoxBarItem, ListBarItem in toolbars
  • Overflow Management: Chevron button for items that don't fit
  • Themed Toolbars: Office2007, Office2016, Metro themes
  • RTL Applications: Right-to-Left toolbar layouts
当用户需要实现以下需求时可使用本技能:
  • 应用工具栏: 带按钮、下拉菜单和组合框的标准工具栏
  • Visual Studio风格菜单: 受VS启发的菜单栏,包含文件、编辑、视图选项
  • 快速访问工具栏: 紧凑布局的工具栏,存放常用命令
  • 可停靠工具栏: 可停靠到任意侧边(顶部、底部、左侧、右侧)的工具栏
  • 多层工具栏: 多个连续堆叠的工具栏
  • 下拉菜单: 带子菜单的DropDownBarItem和ParentBarItem
  • 工具栏控件: 工具栏内的ComboBoxBarItem、TextBoxBarItem、ListBarItem
  • 溢出管理: 适配空间不足场景的V形按钮
  • 主题化工具栏: Office2007、Office2016、Metro主题
  • RTL应用: 从右到左的工具栏布局

Component Overview

组件概览

XPToolBar (
Syncfusion.Windows.Forms.Tools.XPMenus.XPToolBar
) is a versatile toolbar control supporting:
  • 8 BarItem Types:
    • BarItem: Individual menu/toolbar button
    • ParentBarItem: Submenu with child items
    • DropDownBarItem: Dropdown list selection
    • ComboBoxBarItem: Editable combo box
    • ListBarItem: List selection control
    • StaticBarItem: Non-clickable label/separator
    • ToolbarListBarItem: Toolbar list display
    • TextBoxBarItem: Text input box
    • Separator: Visual divider between items
  • Flexible Docking: Top, Bottom, Left, Right positioning
  • Multiple Toolbars: Add consecutive toolbar levels
  • Chevron/Overflow Button: Shows hidden items when toolbar is too narrow
  • Rich Themes: Office2007, Office2016 (Colorful/White/DarkGray/Black), Metro
  • Customization: Text, colors, fonts, images, tooltips per item
  • RTL Support: Right-to-Left layout for international apps
  • Localization: Multi-language support with CultureInfo
  • Keyboard Shortcuts: Assign keyboard shortcuts to BarItems
Key Namespace:
Syncfusion.Windows.Forms.Tools.XPMenus
Assembly:
Syncfusion.Tools.Windows.dll
(and dependencies)

XPToolBar
Syncfusion.Windows.Forms.Tools.XPMenus.XPToolBar
)是一款多功能工具栏控件,支持:
  • 8种BarItem类型:
    • BarItem: 独立的菜单/工具栏按钮
    • ParentBarItem: 带子条目的子菜单
    • DropDownBarItem: 下拉列表选择器
    • ComboBoxBarItem: 可编辑组合框
    • ListBarItem: 列表选择控件
    • StaticBarItem: 不可点击的标签/分隔符
    • ToolbarListBarItem: 工具栏列表展示
    • TextBoxBarItem: 文本输入框
    • Separator: 条目之间的视觉分隔线
  • 灵活停靠: 支持顶部、底部、左侧、右侧定位
  • 多工具栏: 可添加连续的工具栏层级
  • V形/溢出按钮: 当工具栏过窄时展示被隐藏的条目
  • 丰富主题: Office2007、Office2016(多彩/白色/深灰/黑色)、Metro
  • 定制能力: 每个条目的文本、颜色、字体、图片、提示信息均可配置
  • RTL支持: 面向国际化应用的从右到左布局
  • 本地化: 支持基于CultureInfo的多语言适配
  • 键盘快捷键: 可为BarItem分配键盘快捷键
核心命名空间:
Syncfusion.Windows.Forms.Tools.XPMenus
程序集:
Syncfusion.Tools.Windows.dll
(及其依赖项)

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When to read: User needs to install, configure, or create their first XPToolBar.
Topics covered:
  • Assembly deployment and NuGet package installation
  • Adding XPToolBar via designer (toolbox, smart tags)
  • Adding XPToolBar via code
  • Positioning toolbar with Panel/container controls
  • BarItem Collection Editor for adding items
  • Bar.Items collection management
  • Basic toolbar setup and initialization
📄 阅读: references/getting-started.md
适用场景: 用户需要安装、配置或创建第一个XPToolBar时。
覆盖内容:
  • 程序集部署和NuGet包安装
  • 通过设计器添加XPToolBar(工具箱、智能标签)
  • 通过代码添加XPToolBar
  • 使用Panel/容器控件定位工具栏
  • 用于添加条目的BarItem集合编辑器
  • Bar.Items集合管理
  • 基础工具栏设置和初始化

BarItem Types and Collections

BarItem类型与集合

📄 Read: references/baritem-types.md
When to read: User wants to add buttons, dropdowns, combo boxes, or understand different item types.
Topics covered:
  • BarItem (individual button/menu item)
  • ParentBarItem (submenu with child items)
  • DropDownBarItem (dropdown selection list)
  • ComboBoxBarItem (editable combo box control)
  • ListBarItem (list selection)
  • StaticBarItem (non-clickable labels)
  • ToolbarListBarItem (toolbar item lists)
  • TextBoxBarItem (text input in toolbar)
  • Separator (visual divider)
  • Adding items programmatically via Items collection
  • Item properties (Text, Image, Tooltip, Enabled)
📄 阅读: references/baritem-types.md
适用场景: 用户想要添加按钮、下拉菜单、组合框,或了解不同条目类型时。
覆盖内容:
  • BarItem(独立按钮/菜单项)
  • ParentBarItem(带子条目的子菜单)
  • DropDownBarItem(下拉选择列表)
  • ComboBoxBarItem(可编辑组合框控件)
  • ListBarItem(列表选择器)
  • StaticBarItem(不可点击的标签)
  • ToolbarListBarItem(工具栏条目列表)
  • TextBoxBarItem(工具栏内的文本输入框)
  • Separator(视觉分隔线)
  • 通过Items集合编程添加条目
  • 条目属性(Text、Image、Tooltip、Enabled)

Docking and Layout

停靠与布局

📄 Read: references/docking-and-layout.md
When to read: User needs to position toolbar or add multiple toolbar levels.
Topics covered:
  • Docking positions (Top, Bottom, Left, Right)
  • Dock property configuration
  • Multiple consecutive toolbars
  • Adding toolbar levels
  • Container requirements (Panel, GroupBox, etc.)
  • Toolbar positioning strategies
  • Layout best practices for different scenarios
📄 阅读: references/docking-and-layout.md
适用场景: 用户需要定位工具栏或添加多层工具栏时。
覆盖内容:
  • 停靠位置(顶部、底部、左侧、右侧)
  • Dock属性配置
  • 多个连续工具栏
  • 添加工具栏层级
  • 容器要求(Panel、GroupBox等)
  • 工具栏定位策略
  • 不同场景下的布局最佳实践

Chevron and Overflow

V形按钮与溢出处理

📄 Read: references/chevron-and-overflow.md
When to read: User encounters overflow issues or wants to manage hidden toolbar items.
Topics covered:
  • Chevron/Overflow button functionality
  • Viewing items that don't fit in toolbar width
  • Overflow behavior and triggers
  • Configuring chevron appearance
  • User interaction with overflow menu
  • Managing toolbar items for different window sizes
📄 阅读: references/chevron-and-overflow.md
适用场景: 用户遇到溢出问题,或想要管理被隐藏的工具栏条目时。
覆盖内容:
  • V形/溢出按钮功能
  • 查看工具栏宽度不足时被隐藏的条目
  • 溢出行为与触发条件
  • 配置V形按钮外观
  • 用户与溢出菜单的交互
  • 适配不同窗口尺寸的工具栏条目管理

Appearance Customization

外观定制

📄 Read: references/appearance-customization.md
When to read: User wants to customize colors, fonts, images, or tooltips.
Topics covered:
  • Text customization (Text property)
  • Background color (BackColor property)
  • Foreground color (ForeColor property)
  • Font configuration per item or toolbar
  • Image assignment to BarItems
  • Tooltip configuration (ToolTip property per item)
  • Size and spacing adjustments
  • Per-item appearance customization
📄 阅读: references/appearance-customization.md
适用场景: 用户想要定制颜色、字体、图片或提示信息时。
覆盖内容:
  • 文本定制(Text属性)
  • 背景色(BackColor属性)
  • 前景色(ForeColor属性)
  • 单条目或整个工具栏的字体配置
  • 为BarItem分配图片
  • 提示信息配置(每个条目的ToolTip属性)
  • 尺寸与间距调整
  • 单条目外观定制

Themes and Styling

主题与样式

📄 Read: references/themes-and-styling.md
When to read: User wants Office themes, RTL support, or localization.
Topics covered:
  • Visual styles: Office2007 (Blue, Silver, Black)
  • Office2016 themes (Colorful, White, DarkGray, Black)
  • Metro theme
  • Style property configuration
  • RTL (Right-to-Left) support for Arabic/Hebrew
  • Localization with CultureInfo
  • Keyboard shortcuts (Ctrl+X, Alt+F, etc.)
  • Trigger BarItems for custom actions

📄 阅读: references/themes-and-styling.md
适用场景: 用户想要使用Office主题、RTL支持或本地化能力时。
覆盖内容:
  • 视觉样式:Office2007(蓝色、银色、黑色)
  • Office2016主题(多彩、白色、深灰、黑色)
  • Metro主题
  • Style属性配置
  • 面向阿拉伯语/希伯来语的RTL(从右到左)支持
  • 基于CultureInfo的本地化
  • 键盘快捷键(Ctrl+X、Alt+F等)
  • 触发自定义动作的BarItem

Quick Start Example

快速入门示例

Basic Toolbar with Menu Items

带菜单项的基础工具栏

csharp
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);
csharp
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);

Toolbar with Office2016 Theme

带Office2016主题的工具栏

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

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

Common Patterns

常用模式

File Menu with Submenu Items

带子菜单条目的文件菜单

csharp
// 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);
When to use: Standard application menu with File operations.
csharp
// 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);
适用场景: 带文件操作的标准应用菜单。

Toolbar with ComboBox and TextBox

带组合框和文本框的工具栏

csharp
// Font selector combo box
ComboBoxBarItem fontCombo = new ComboBoxBarItem();
fontCombo.Text = "Font:";
fontCombo.Items.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);
};
When to use: Text editor or formatting toolbars.
csharp
// Font selector combo box
ComboBoxBarItem fontCombo = new ComboBoxBarItem();
fontCombo.Text = "Font:";
fontCombo.Items.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);
};
适用场景: 文本编辑器或格式工具栏。

Docked Toolbar (Top)

停靠在顶部的工具栏

csharp
// 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);
When to use: Simple top-docked toolbar without complex layout.
csharp
// 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);
适用场景: 无需复杂布局的简单顶部停靠工具栏。

Multiple Toolbar Levels

多层工具栏

csharp
// 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);
When to use: Complex applications with menu bar and quick access toolbar.

csharp
// 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);
适用场景: 同时带有菜单栏和快速访问工具栏的复杂应用。

Key Properties

核心属性

Core Properties

基础属性

PropertyTypeDescriptionWhen to Use
Bar.Items
BarItemCollection
Collection of toolbar itemsAdd/manage toolbar buttons and controls
Dock
DockStyle
Docking positionPosition toolbar (Top/Bottom/Left/Right)
Style
VisualStyle
Visual theme styleApply Office2007/2016/Metro themes
属性类型描述适用场景
Bar.Items
BarItemCollection
工具栏条目集合添加/管理工具栏按钮和控件
Dock
DockStyle
停靠位置定位工具栏(顶部/底部/左侧/右侧)
Style
VisualStyle
视觉主题样式应用Office2007/2016/Metro主题

BarItem Properties

BarItem属性

PropertyTypeDescriptionWhen to Use
Text
string
Item text/captionSet button or menu label
Image
Image
Item iconAdd visual icon to item
ToolTip
string
Tooltip textProvide hover information
Enabled
bool
Enable/disable itemControl item interactivity
Visible
bool
Show/hide itemToggle item visibility
属性类型描述适用场景
Text
string
条目文本/标题设置按钮或菜单标签
Image
Image
条目图标为条目添加视觉图标
ToolTip
string
提示文本提供悬浮提示信息
Enabled
bool
启用/禁用条目控制条目交互性
Visible
bool
显示/隐藏条目切换条目可见性

BarItem Types Summary

BarItem类型汇总

  • BarItem - Standard button/menu item
  • ParentBarItem - Menu with submenu items (use
    .Items
    collection)
  • DropDownBarItem - Dropdown list (use
    .ChoiceList
    )
  • ComboBoxBarItem - Editable combo box (use
    .Items
    and
    .SelectedIndex
    )
  • ListBarItem - List selection control
  • StaticBarItem - Non-clickable label
  • TextBoxBarItem - Text input (use
    .TextBoxValue
    )
  • ToolbarListBarItem - Toolbar item list
  • Separator - Visual divider (set
    BarItemType = BarItemType.Separator
    )

  • BarItem - 标准按钮/菜单项
  • ParentBarItem - 带子菜单条目的菜单(使用
    .Items
    集合)
  • DropDownBarItem - 下拉列表(使用
    .ChoiceList
  • ComboBoxBarItem - 可编辑组合框(使用
    .Items
    .SelectedIndex
  • ListBarItem - 列表选择控件
  • StaticBarItem - 不可点击的标签
  • TextBoxBarItem - 文本输入框(使用
    .TextBoxValue
  • ToolbarListBarItem - 工具栏条目列表
  • Separator - 视觉分隔线(设置
    BarItemType = BarItemType.Separator

Common Use Cases

常见使用场景

1. Application Menu Bar

1. 应用菜单栏

Scenario: Standard menu bar with File, Edit, View, Help.
  • Use ParentBarItem for each top-level menu
  • Add submenu BarItems to each ParentBarItem
  • Add separators between item groups
  • Handle Click events for actions
  • Read: baritem-types.md
场景: 带文件、编辑、视图、帮助的标准菜单栏。
  • 每个顶层菜单使用ParentBarItem
  • 为每个ParentBarItem添加子菜单BarItem
  • 在条目组之间添加分隔线
  • 为动作绑定Click事件
  • 阅读:baritem-types.md

2. Text Editor Toolbar

2. 文本编辑器工具栏

Scenario: Formatting toolbar with font, size, bold, italic.
  • ComboBoxBarItem for font selection
  • TextBoxBarItem for font size
  • BarItems with images for bold/italic/underline
  • Use images for visual clarity
  • Read: baritem-types.md, appearance-customization.md
场景: 带字体、字号、加粗、斜体的格式工具栏。
  • 使用ComboBoxBarItem实现字体选择
  • 使用TextBoxBarItem实现字号设置
  • 带图片的BarItem实现加粗/斜体/下划线功能
  • 使用图片提升视觉清晰度
  • 阅读:baritem-types.mdappearance-customization.md

3. Ribbon-Like Quick Access

3. 类Ribbon快速访问栏

Scenario: Quick access toolbar above main content.
  • Top-docked toolbar with frequently used commands
  • Use images without text (icon-only buttons)
  • Enable tooltips for each item
  • Apply Office2016 theme for modern look
  • Read: docking-and-layout.md, themes-and-styling.md
场景: 主内容上方的快速访问工具栏。
  • 停靠在顶部的工具栏,存放常用命令
  • 使用无文本的图标按钮
  • 为每个条目启用提示信息
  • 应用Office2016主题实现现代外观
  • 阅读:docking-and-layout.mdthemes-and-styling.md

4. Multi-Level Toolbar System

4. 多层工具栏系统

Scenario: Menu bar + Quick access toolbar + Formatting toolbar.
  • Create multiple Panel containers
  • Add one XPToolBar per panel
  • Stack panels with proper docking order
  • Apply consistent theme across all toolbars
  • Read: docking-and-layout.md
场景: 菜单栏 + 快速访问工具栏 + 格式工具栏。
  • 创建多个Panel容器
  • 每个Panel内添加一个XPToolBar
  • 按正确的停靠顺序堆叠Panel
  • 所有工具栏应用统一主题
  • 阅读:docking-and-layout.md

5. Localized Toolbar

5. 本地化工具栏

Scenario: Toolbar for international application (Arabic/Hebrew).
  • Enable RTL support
  • Use CultureInfo for localization
  • Load localized strings from resources
  • Test with different languages
  • Read: themes-and-styling.md
场景: 面向国际化应用(阿拉伯语/希伯来语)的工具栏。
  • 启用RTL支持
  • 使用CultureInfo实现本地化
  • 从资源文件加载本地化字符串
  • 使用不同语言测试
  • 阅读:themes-and-styling.md

6. Dynamic Toolbar

6. 动态工具栏

Scenario: Add/remove toolbar items at runtime based on context.
  • Use Bar.Items.Add/Remove methods
  • Show/hide items with Visible property
  • Enable/disable with Enabled property
  • Refresh toolbar layout after changes
  • Read: baritem-types.md

场景: 运行时根据上下文添加/移除工具栏条目。
  • 使用Bar.Items.Add/Remove方法
  • 通过Visible属性显示/隐藏条目
  • 通过Enabled属性启用/禁用条目
  • 更改后刷新工具栏布局
  • 阅读:baritem-types.md

Events

事件

Common BarItem events:
  • Click - Raised when item is clicked
  • SelectedIndexChanged - For ComboBoxBarItem/DropDownBarItem selection changes
csharp
barItem1.Click += (sender, e) => {
    // Handle button click
    MessageBox.Show("Item clicked!");
};

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

常用BarItem事件:
  • Click - 条目被点击时触发
  • SelectedIndexChanged - ComboBoxBarItem/DropDownBarItem选中项变化时触发
csharp
barItem1.Click += (sender, e) => {
    // Handle button click
    MessageBox.Show("Item clicked!");
};

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

Best Practices

最佳实践

  1. Container Usage: Always place XPToolBar in a Panel or container for proper positioning
  2. Theme Consistency: Match toolbar Style to application theme
  3. Image Quality: Use high-quality icons (16x16 or 24x24) for BarItem images
  4. Tooltips: Always provide tooltips for icon-only buttons
  5. Overflow Management: Keep toolbar item count reasonable to minimize overflow
  6. Event Handling: Subscribe to Click events for all interactive BarItems
  7. Separators: Use separators to visually group related items
  8. Keyboard Shortcuts: Assign shortcuts for frequently used commands
  9. Dynamic Updates: Use Enabled/Visible properties rather than removing items
  10. Docking Order: Add panels in reverse order when stacking multiple toolbars

  1. 容器使用: 始终将XPToolBar放在Panel或其他容器中,确保定位正常
  2. 主题一致性: 工具栏Style与应用主题保持一致
  3. 图片质量: 为BarItem使用高质量图标(16x16或24x24)
  4. 提示信息: 始终为仅图标按钮添加提示信息
  5. 溢出管理: 合理控制工具栏条目数量,减少溢出情况
  6. 事件处理: 为所有可交互BarItem绑定Click事件
  7. 分隔线: 使用分隔线对相关条目进行视觉分组
  8. 键盘快捷键: 为常用命令分配快捷键
  9. 动态更新: 优先使用Enabled/Visible属性,而非直接移除条目
  10. 停靠顺序: 堆叠多个工具栏时,按相反顺序添加Panel

Related Skills

相关技能

  • MainFrameBarManager: Advanced menu and toolbar management
  • RibbonControlAdv: Office-style Ribbon interface
  • StatusStripEx: Status bar for bottom of form

  • MainFrameBarManager: 高级菜单与工具栏管理
  • RibbonControlAdv: Office风格Ribbon界面
  • StatusStripEx: 窗体底部的状态栏

See Also

参考链接