工具条控件 (SToolBar)¶

SToolBar 是 SOUI 中提供的类似 MFC CToolBar 功能的工具条控件，支持按钮、分隔符、下拉菜单等功能。

基本信息¶

类名：SToolBar
控件标签：toolbar
基类：SWindow

功能特点¶

支持按钮、分隔符、下拉菜单等工具条元素
支持图标和文本显示
支持按钮状态管理（启用、禁用、选中、按下）
支持动画效果
支持垂直排列
支持子控件嵌入

属性说明¶

属性名	类型	默认值	说明
iconSkin	皮肤	-	图标皮肤
sepSkin	皮肤	-	分隔符皮肤
skin	皮肤	-	按钮状态皮肤
dropArrowSkin	皮肤	-	下拉箭头皮肤
vertical	布尔值	false	是否垂直排列
textIconVertical	布尔值	true	文本和图标是否垂直排列
animate	布尔值	true	是否启用动画效果
maxItemWidth	整数	-	最大项目宽度
textIconInterval	整数	-	文本和图标之间的间距

使用示例¶

基本工具条¶

<toolbar name="tb_main" 
         size="-1,32" 
         iconSkin="skin:tb_main" 
         skin="skin:toolbar_state" 
         sepSkin="skin:tb_sep">
    <data>
        <item id="1" text="打开" tip="打开项目"/>
        <item id="2" text="保存" tip="保存文件"/>
        <sep/>
        <item id="3" text="新建" tip="新建文件"/>
        <item id="4" text="删除" tip="删除文件"/>
    </data>
</toolbar>

垂直工具条¶

<toolbar name="tb_vertical" 
         size="40,-1" 
         vertical="true" 
         iconSkin="skin:tb_icons" 
         skin="skin:toolbar_state">
    <data>
        <item id="1" text="工具1" tip="工具1提示"/>
        <item id="2" text="工具2" tip="工具2提示"/>
        <sep/>
        <item id="3" text="工具3" tip="工具3提示"/>
    </data>
</toolbar>

代码创建工具条¶

// 初始化工具条
SToolBar *pToolBar = FindChildByName2<SToolBar>(L"tb_main");
if(pToolBar)
{
    // 设置图标皮肤
    ISkinObj *pIconSkin = SApplication::getSingleton().CreateSkinByName(L"tb_main");
    if(pIconSkin)
    {
        pToolBar->SetIconsSkin(pIconSkin);
        pIconSkin->Release();
    }

    // 添加按钮
    pToolBar->AddButton(1, 0, L"打开");
    pToolBar->AddButton(2, 1, L"保存");
    pToolBar->AddButton(3, 2, L"新建");
}

事件处理¶

工具条命令事件¶

事件名	EventID	说明
EventToolBarCmd	EventToolBarCmd::EventID	工具条按钮点击事件

// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_ID_HANDLER(R.id.tb_main, EventToolBarCmd::EventID, OnTbMainClick)
EVENT_MAP_END()

void OnTbMainClick(IEvtArgs *e)
{
    EventToolBarCmd *e2 = sobj_cast<EventToolBarCmd>(e);
    if(e2->nCmdId == R.id.tb_main_open)
    {
        // 处理打开操作
    }else if(e2->nCmdId == R.id.tb_main_save){
        // 处理保存操作
    }
}

命令更新事件 (EventUpdateCmdUI)¶

用于更新工具条按钮的状态（启用/禁用、选中状态等）。

// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_ID_HANDLER(R.id.tb_main, EventUpdateCmdUI::EventID, OnUpdateCmdUI)
EVENT_MAP_END()

void OnUpdateCmdUI(IEvtArgs *e)
{
    EventUpdateCmdUI *e2 = sobj_cast<EventUpdateCmdUI>(e);
    if(e2->nCmdId == R.id.tb_main_save)
    {
        // 根据文档是否修改决定保存按钮是否可用
        e2->bEnable = m_bIsDirty;
    }
    else if(e2->nCmdId == R.id.tb_main_cut)
    {
        // 根据是否有选中内容决定剪切按钮是否可用
        e2->bEnable = m_bHasSelection;
        // 设置是否选中状态
        e2->bChecked = m_bIsCutMode;
    }
}

命令提示事件 (EventUpdateCmdTip)¶

用于更新命令提示信息，通常显示在状态栏。

// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_ID_HANDLER(R.id.tb_main, EventUpdateCmdTip::EventID, OnUpdateCmdTip)
EVENT_MAP_END()

void OnUpdateCmdTip(IEvtArgs *e)
{
    EventUpdateCmdTip *e2 = sobj_cast<EventUpdateCmdTip>(e);
    SWindow *pStatusBar = FindChildByID(R.id.txt_status);
    if(pStatusBar)
    {
        if(e2->strTip)
        {
            // 显示工具条按钮的提示信息
            pStatusBar->SetWindowText(SStringT(e2->strTip));
        }
        else if(e2->nCmdId >= 0)
        {
            // 根据命令ID显示对应的提示信息
            switch(e2->nCmdId)
            {
            case R.id.tb_main_open:
                pStatusBar->SetWindowText(L"打开项目文件");
                break;
            case R.id.tb_main_save:
                pStatusBar->SetWindowText(L"保存当前文件");
                break;
            }
        }
        else
        {
            // 显示默认提示信息
            pStatusBar->SetWindowText(L"就绪");
        }
    }
}

方法说明¶

按钮管理¶

InsertItem：插入工具条项目
AddButton：添加按钮
DeleteButton：删除按钮
GetItemCount：获取项目数量
GetItemID：获取项目ID
CommandToIndex：根据命令ID获取项目索引

按钮状态¶

EnableButton：启用/禁用按钮
CheckButton：选中/取消选中按钮
PressButton：按下/释放按钮
IsButtonEnabled：检查按钮是否启用
IsButtonChecked：检查按钮是否选中
IsButtonPressed：检查按钮是否按下

按钮样式¶

GetButtonStyle：获取按钮样式
SetButtonStyle：设置按钮样式

子控件管理¶

SetItemChild：为工具条项目设置子控件
GetItemChild：获取工具条项目的子控件

最佳实践¶

图标皮肤设计：为工具条创建合适的图标皮肤，确保图标清晰易辨识。
提示信息：为每个工具条按钮设置有意义的提示信息，提升用户体验。
状态管理：使用 EventUpdateCmdUI 事件动态更新按钮状态，确保界面状态与应用逻辑保持一致。
命令提示：使用 EventUpdateCmdTip 事件在状态栏显示命令提示，帮助用户了解当前操作。
布局考虑：根据工具条内容多少，合理设置工具条的大小和布局方式。
响应式设计：当工具条空间不足时，SToolBar 会自动添加"更多"按钮，确保所有功能都可访问。

常见问题¶

Q: 工具条按钮不显示图标怎么办？¶

A: 确保正确设置了 iconSkin 属性，并在添加按钮时指定了正确的图标索引。

Q: 如何为工具条按钮添加下拉菜单？¶

A: 使用 TBSTYLE_DROPDOWN 样式创建下拉按钮，然后在点击事件中处理下拉菜单的显示。

Q: 工具条按钮的提示信息如何显示在状态栏？¶

A: 通过处理 EventUpdateCmdTip 事件，将提示信息显示到状态栏控件。