文档和代码编辑器
编辑器需要“粗体”和“斜体”切换按钮、一个对齐单选组、一个“缩放”菜单,以及显示行号、列号和保存状态的状态栏。sgcToolbar 用一个条目集合和一个面板集合就能全部实现,并与您已有的 TActionList 关联。窗口变窄时,溢出菜单让每个命令仍可访问。EditorShell 演示正是围绕 TMemo 这样构建的。
- 条目类型
- 单选组
- 溢出菜单
用两个在每种界面上外观一致的控件搭建桌面应用程序的框架。工具栏提供按钮、切换按钮、单选组和下拉菜单,真正的状态栏提供进度和指示器面板,工作线程可以直接更新。
十二项功能,覆盖每个桌面应用都需要的两种栏,从单选组到工作线程的实时进度。
命令栏所需的每一种条目,分组、菜单和溢出都由控件处理。
命令
真正的应用程序工具栏会混合使用普通按钮、保持按下的按钮、带菜单的按钮、分隔符和少量文字。在 sgcToolbar 中,它们都是同一个集合中的一个条目,由 Kind 决定其绘制方式和响应方式。条目从左到右排列,之间按 Spacing 留出间距,空白填充项会占用剩余宽度,因此无需任何布局代码,即可把“帮助”或用户名推到右边缘。需要稳定尺寸时用 Width 固定条目。每种类型都会绘制提示、禁用状态和悬停跟踪。
tikButton、tikToggle 和 tikDropdown 用于命令tikSeparator 绘制一条细竖线tikSpacer 将后面的条目推到右侧tikLabel 在栏内显示文本
命令
文本对齐、视图模式和绘图工具都是典型的多选一。给多个切换条目设置相同的 GroupIndex,它们就构成一个单选组:无论通过点击还是代码将其中一个的 Down 设为 True,其他的都会弹起,而点击已按下的条目则保持按下,因此始终有一项被选中。GroupIndex 为 0 的切换按钮是简单的开关,例如“粗体”或“自动换行”。点击会在 OnItemClick 触发之前翻转 Down,因此您的处理程序读到的是新状态。无需连接任何事件即可保持分组一致。
GroupIndex 大于 0 即构成单选组Down 可通过代码读取或设置状态Down命令
缩放级别、导出格式和最近文件应该放在按钮下的菜单里,而不是再多放十个按钮。tikDropdown 条目会在标题后绘制一个小箭头,并在按钮正下方显示您赋给 DropdownMenu 的弹出菜单:VCL 和 FireMonkey 中是 TPopupMenu,WinForms 中是 ContextMenuStrip。OnItemClick 和条目的 OnClick 在菜单打开之前触发,因此您可以先填充或勾选其条目。如果菜单被释放,导航栏会自动清除引用。一个点击目标,一个菜单,即使命令增多,工具栏也保持简短。
DropdownMenu 接受您所用框架的弹出菜单OnItemClick 中填充或勾选菜单命令 仅限注册版
用户会调整窗口大小,而直接裁掉最后几个按钮的工具栏会隐藏他们需要的命令。当条目放不下时,sgcToolbar 会把最后几个移入溢出列表,并在右端绘制一个双箭头按钮。按下它会显示 OverflowMenu,该菜单在运行时构建,每个隐藏的条目对应一项,选择某项的效果与点击完全相同:切换按钮会翻转,OnItemClick 会触发,下拉按钮会显示其菜单。模型会告诉您哪些条目被隐藏。窗口再次变大时,条目会自动回到栏中。
OverflowMenu 在运行时为您构建HasOverflow、OverflowCount 和 InOverflowItemAtPos 报告对溢出按钮的命中SGC_TOOLBAR_ADVANCED 下编译社区版:放不下的条目会被裁剪,没有溢出按钮。
阅读帮助主题命令 仅限注册版
如果您的命令已经放在 TActionList 中,工具栏就不应重复定义。通过 Action 属性将条目关联到任意 VCL 或 FireMonkey 的 TAction,它会跟随该操作的 Caption、Enabled、Visible、Hint、ImageIndex 和 Checked。除非条目有 OnClick 处理程序,否则点击会以导航栏作为 ActionComponent 执行该操作。导航栏在空闲时调用 InitiateAction,因此被禁用的操作无需额外代码就会禁用其按钮。在 .NET 中,条目提供用于 ICommand 的 Command 和 CommandParameter。一个 TActionList 可以同时驱动工具栏、主菜单和导航栏。
Action 将条目关联到任意 TBasicActionDownCommand 和 CommandParameter社区版:请改为处理条目的 OnClick 或导航栏的 OnItemClick,而不是操作。
阅读帮助主题一个能自行布局、显示进度与状态,并接受任意线程更新的状态栏。
状态栏
行列号、文件名、保存状态和主消息都在争夺窗口的底边。TsgcVCLStatusBar 分三轮从左到右布局其 Panels:固定面板取其 Width,AutoSize 面板取其文本的宽度,Spring 面板平分剩余空间。主消息使用一个 Spring 面板,无论窗口多大,状态栏都保持整洁。细线分隔各面板,OnPanelClick 告诉您点击的是哪一个。面板是一个集合,可在设计时用对象检查器添加和编辑。
Alignment 和 Hint 的 spkText 面板Spring 面板平分剩余宽度AutoSize 面板适应其文本OnPanelClick 报告对面板的点击
状态栏
耗时操作需要进度条,实时连接需要一盏说明一切是否正常的指示灯。面板可以是按 Progress 百分比以强调色填充的进度条,也可以是指示器:一个彩色圆点加上面板的文本。IndicatorState 可选择 off、ok、warning 或 error,绿色、琥珀色和红色分别针对浅色和深色主题调校。它适用于数据库连接、数据源或后台同步的状态。设置 Progress 或 IndicatorState,面板会自行重绘,无需编写绘制代码。
spkProgress 配合 0 到 100 的 ProgressspkIndicator 配合 IndicatorStatesisOff、sisOk、sisWarning、sisErrorGetIndicatorColor 返回适合当前主题的颜色状态栏
下载、数据源和长时间计算都运行在工作线程中,把每次状态更新都转回主线程既繁琐又容易出错。SetPanelText、SetProgress 和 SetIndicator 可从任意线程调用,无需 Synchronize 或 Queue。模型用锁保护这些值,只在值确实改变时才触发 OnChange,因此重复设置相同的值没有任何开销。随后 VCL 导航栏向其窗口发送一条消息,FireMonkey 导航栏则将重绘排入队列,因此界面绝不会在主线程之外被访问。比面板存活更久的线程同样安全。
SetPanelText、SetProgress、SetIndicatorSynchronize 或 Queue与 sgcUI 其余部分一致的图标、主题和键盘支持,另外还能为您的文档生成这些栏的图片。
外观、键盘与输出
每个可点击的条目都有一个 16 逻辑像素的图标位。它显示栏的 Images 列表中 ImageIndex 处的图像,条目没有图像时则显示其 Glyph:一个完全不需要图像列表的字母或短符号。关闭 ShowCaptions 即可得到紧凑的纯图标栏,标题变成提示,不会丢失任何信息。VCL 图像列表只转换一次为恢复了 Alpha 的直通 ARGB,并缓存到列表更改为止,因此带掩码的列表和 32 位列表都能正确显示。在图标仍在设计时,可以自由混用两者。
Images 和 ImageIndex 用于图像列表GlyphShowCaptions 设为 False 即仅显示图标MirrorGlyph 会翻转后退、前进、撤销和重做等带方向的图标
外观、键盘与输出
两种栏的颜色取自 sgcUICore 主题令牌,与套件中每款产品使用的完全相同,因此 sgcGrid 上方、sgcNavigation 导航栏旁边的工具栏看起来就像同一个应用程序。Theme 选择 utLight 或 utDark,AccentColor 替换焦点环、切换按钮按下色调和进度条所用的强调色。悬停、按下、按住、聚焦和禁用状态都会为您自动推导。每个栏都有自己的 Theme,因此需要分别在工具栏和状态栏上设置。运行时切换会同时重绘两个栏。
Theme:utDefault(默认,跟随应用程序主题)、utLight 或 utDarkAccentColor 为 $AARRGGBB,0 表示沿用主题强调色外观、键盘与输出
当用户需要时,工具栏可以加入 Tab 顺序:设置 TabStop 后,获得焦点的按钮会显示焦点环,左右键在已启用的按钮之间移动,Home 和 End 跳转,Enter 或空格激活。它默认关闭,因此工具栏绝不会从下方的编辑器抢走焦点。ClickItem 可通过代码激活条目,例如由窗体快捷键触发。在状态栏上,SizeGrip 绘制手柄圆点,在 VCL 中拖动它们可调整可缩放窗体的大小。在 FireMonkey 中手柄只是绘制出来,并不会调整窗体大小,因此窗体不可缩放时请在那里关闭 SizeGrip。
TabStop,FireMonkey 中为 CanFocusClickItem 通过代码运行条目SizeGrip 和 GripRect外观、键盘与输出
手册中的工具栏截图会随每个版本过时。sgcToolbar_Render 中的渲染器无需窗口,也无需 VCL 或 FireMonkey,即可绘制 TsgcToolbarModel 或 TsgcStatusBarModel,因此控制台程序、测试或 Web 服务器都能将同样的栏输出为图片。SaveToPNG 和 SaveToSVG 接受以逻辑像素表示的尺寸和缩放比例,所以 560 乘 44、缩放 2 即可得到清晰的 1120 乘 88 图片。这些单元可在所有平台上构建,包括 Linux64。通过 OnGetImage 传入您自己的图像,图片就与运行中的应用程序一致。
SaveToPNG 写入 PNG 文件或流SaveToSVG 将同一栏写为 SVGTsgcToolbarModel 和 TsgcStatusBarModelOnGetImage 为无界面输出提供图标sgcUI 套件演示中的 sgcToolbar:使用内置模拟数据、可离线运行的完整应用程序。
带 Inject event、快捷按钮和主题切换的顶部栏,下方是状态栏。
Altamira Fleet →
带搜索、New、通知和用户菜单的 ERP 顶部栏。
Altamira ERP →
带 Reset what-if 和主题切换的 PMO 顶部栏。
Altamira PMO →
带 Inject fault、Acknowledge all 和速度控制的工厂顶部栏。
Altamira Plant →
编辑器需要“粗体”和“斜体”切换按钮、一个对齐单选组、一个“缩放”菜单,以及显示行号、列号和保存状态的状态栏。sgcToolbar 用一个条目集合和一个面板集合就能全部实现,并与您已有的 TActionList 关联。窗口变窄时,溢出菜单让每个命令仍可访问。EditorShell 演示正是围绕 TMemo 这样构建的。
导入工具、同步客户端和监控应用都在后台线程中工作,并且必须报告进度。直接从工作线程调用 SetProgress、SetIndicator 和 SetPanelText,状态栏会在主线程上重绘,您的代码中无需 Synchronize。指示器会随任务状态变为绿色、琥珀色或红色。LiveStatus 演示模拟了一个正是这样工作的下载。
在 Windows、macOS 和移动平台上发布的 FireMonkey 应用程序,理应在各处都使用相同的工具栏。TsgcFMXToolbar 和 TsgcFMXStatusBar 的条目、面板和事件与 VCL 栏相同,适用于 WinForms、WPF 和 Avalonia 的 .NET 栏也沿用相同的名称。EditorShellFMX 是编辑器外壳的 FireMonkey 版本,条目、溢出菜单和状态面板都相同。
Delphi、C++ Builder 和 C# 中使用相同的 API:一个切换按钮、一个单选组、一个下拉菜单,以及由点击处理程序更新的状态栏。
procedure TMainForm.CreateBars;
var
oItem: TsgcToolbarItem;
oPanel: TsgcStatusBarPanel;
begin
// a toolbar with a toggle, a Left/Center radio group and a dropdown
FToolbar := TsgcVCLToolbar.Create(Self);
FToolbar.Parent := Self;
FToolbar.ShowCaptions := True;
FToolbar.ShowHint := True;
FToolbar.OnItemClick := ToolbarItemClick;
oItem := FToolbar.Items.Add;
oItem.Caption := 'Save';
oItem.Glyph := 'S';
oItem.Hint := 'Save the document';
FToolbar.Items.Add.Kind := tikSeparator;
oItem := FToolbar.Items.Add;
oItem.Kind := tikToggle;
oItem.Caption := 'Bold';
oItem.Glyph := 'B';
oItem := FToolbar.Items.Add;
oItem.Kind := tikToggle;
oItem.GroupIndex := 1;
oItem.Down := True;
oItem.Caption := 'Left';
oItem := FToolbar.Items.Add;
oItem.Kind := tikToggle;
oItem.GroupIndex := 1;
oItem.Caption := 'Center';
oItem := FToolbar.Items.Add;
oItem.Kind := tikDropdown;
oItem.Caption := 'Zoom';
oItem.DropdownMenu := FZoomMenu;
// a status bar: a spring text panel, a progress bar and an indicator
FStatusBar := TsgcVCLStatusBar.Create(Self);
FStatusBar.Parent := Self;
oPanel := FStatusBar.Panels.Add;
oPanel.Spring := True;
oPanel.Text := 'Ready';
FStatusBar.Panels.Add.Kind := spkProgress;
oPanel := FStatusBar.Panels.Add;
oPanel.Kind := spkIndicator;
oPanel.AutoSize := True;
oPanel.Text := 'Saved';
oPanel.IndicatorState := sisOk;
end;
procedure TMainForm.ToolbarItemClick(Sender: TObject; aItem: TsgcToolbarItem);
begin
// the setters are thread safe, a worker thread can call them directly
FStatusBar.SetPanelText(0, aItem.Caption + ' clicked');
FStatusBar.SetProgress(1, 60);
FStatusBar.SetIndicator(2, sisWarning);
end;#include <vcl.h>
#include <Vcl.Menus.hpp>
#include "sgcUICore_Theme.hpp"
#include "sgcToolbar_Model.hpp"
#include "sgcToolbar_VCL.hpp"
class TBarHandler : public TObject
{
public:
TsgcVCLStatusBar *StatusBar;
void __fastcall ItemClick(TObject *Sender, TsgcToolbarItem *aItem);
};
void __fastcall TBarHandler::ItemClick(TObject *Sender, TsgcToolbarItem *aItem)
{
// the setters are thread safe, a worker thread can call them directly
StatusBar->SetPanelText(0, aItem->Caption + " clicked");
StatusBar->SetProgress(1, 60);
StatusBar->SetIndicator(2, sisWarning);
}
void __fastcall CreateBars(TForm *Form, TBarHandler *Handler, TPopupMenu *ZoomMenu)
{
// a toolbar with a toggle, a Left/Center radio group and a dropdown
TsgcVCLToolbar *Toolbar = new TsgcVCLToolbar(Form);
Toolbar->Parent = Form;
Toolbar->ShowCaptions = true;
Toolbar->OnItemClick = Handler->ItemClick;
TsgcToolbarItem *Item = Toolbar->Items->Add();
Item->Caption = "Save";
Item->Glyph = "S";
Item->Hint = "Save the document";
Toolbar->Items->Add()->Kind = tikSeparator;
Item = Toolbar->Items->Add();
Item->Kind = tikToggle;
Item->Caption = "Bold";
Item = Toolbar->Items->Add();
Item->Kind = tikToggle;
Item->GroupIndex = 1;
Item->Down = true;
Item->Caption = "Left";
Item = Toolbar->Items->Add();
Item->Kind = tikToggle;
Item->GroupIndex = 1;
Item->Caption = "Center";
Item = Toolbar->Items->Add();
Item->Kind = tikDropdown;
Item->Caption = "Zoom";
Item->DropdownMenu = ZoomMenu;
// a status bar: a spring text panel, a progress bar and an indicator
TsgcVCLStatusBar *StatusBar = new TsgcVCLStatusBar(Form);
StatusBar->Parent = Form;
TsgcStatusBarPanel *Panel = StatusBar->Panels->Add();
Panel->Spring = true;
Panel->Text = "Ready";
StatusBar->Panels->Add()->Kind = spkProgress;
Panel = StatusBar->Panels->Add();
Panel->Kind = spkIndicator;
Panel->AutoSize = true;
Panel->Text = "Saved";
Panel->IndicatorState = sisOk;
Handler->StatusBar = StatusBar;
}using System;
using System.Windows.Forms;
using esegece.sgcToolbar;
internal class MainForm : Form
{
private readonly TsgcWinFormsToolbar Toolbar = new TsgcWinFormsToolbar();
private readonly TsgcWinFormsStatusBar StatusBar = new TsgcWinFormsStatusBar();
public MainForm()
{
// a toolbar with a toggle, a Left/Center radio group and a dropdown
Toolbar.ShowCaptions = true;
Toolbar.OnItemClick = ToolbarItemClick;
TsgcToolbarItem oItem = Toolbar.Items.Add();
oItem.Caption = "Save";
oItem.Glyph = "S";
oItem.Hint = "Save the document";
Toolbar.Items.Add().Kind = TsgcToolbarItemKind.tikSeparator;
oItem = Toolbar.Items.Add();
oItem.Kind = TsgcToolbarItemKind.tikToggle;
oItem.Caption = "Bold";
oItem = Toolbar.Items.Add();
oItem.Kind = TsgcToolbarItemKind.tikToggle;
oItem.GroupIndex = 1;
oItem.Down = true;
oItem.Caption = "Left";
oItem = Toolbar.Items.Add();
oItem.Kind = TsgcToolbarItemKind.tikToggle;
oItem.GroupIndex = 1;
oItem.Caption = "Center";
ContextMenuStrip oZoom = new ContextMenuStrip();
oZoom.Items.Add("100%");
oZoom.Items.Add("200%");
oItem = Toolbar.Items.Add();
oItem.Kind = TsgcToolbarItemKind.tikDropdown;
oItem.Caption = "Zoom";
oItem.DropdownMenu = oZoom;
// a status bar: a spring text panel, a progress bar and an indicator
TsgcStatusBarPanel oPanel = StatusBar.Panels.Add();
oPanel.Spring = true;
oPanel.Text = "Ready";
StatusBar.Panels.Add().Kind = TsgcStatusPanelKind.spkProgress;
oPanel = StatusBar.Panels.Add();
oPanel.Kind = TsgcStatusPanelKind.spkIndicator;
oPanel.AutoSize = true;
oPanel.Text = "Saved";
oPanel.IndicatorState = TsgcStatusIndicatorState.sisOk;
Controls.Add(Toolbar);
Controls.Add(StatusBar);
}
private void ToolbarItemClick(object sender, TsgcToolbarItem aItem)
{
// the setters are thread safe, a worker thread can call them directly
StatusBar.SetPanelText(0, aItem.Caption + " clicked");
StatusBar.SetProgress(1, 60);
StatusBar.SetIndicator(2, TsgcStatusIndicatorState.sisWarning);
}
}dotnet add package esegece.sgcToolbar.WinFormsEditorShell 和 LiveStatus 演示提供 VCL 和 C++ Builder 版本,以及适用于 Delphi 的 FireMonkey 版本;.NET 版本则提供 WinForms、WPF 和 Avalonia 项目。
一个 TMemo 编辑器外壳,包含切换按钮、Left、Center 和 Right 单选组、Zoom 下拉菜单、TActionList 关联、溢出菜单、行列面板和 Dark 切换按钮。它使用了溢出和操作,因此需要注册版或试用版。
一个工作线程模拟下载,并驱动文本面板、进度面板以及会变为绿色、琥珀色或红色的指示器,带有 Start 和 Stop 按钮。可用社区版构建。
EditorShell 演示,在 FireMonkey TMemo 周围使用 TsgcFMXToolbar 和 TsgcFMXStatusBar,仅适用于 Delphi:条目、操作关联、溢出菜单和状态面板都相同。
sgcToolbar 包含在每个 sgcUI 版本中(从 Standard 起),也可单独购买。sgcToolbar 同时包含在 All-Access 捆绑包中。
免费的社区版(NuGet 上的 esegece.sgcToolbar.Community)不包含溢出菜单和 Action 关联。
| 功能 | 社区版(免费) | 注册版 |
|---|---|---|
| Every item kind, toggles, radio groups and dropdown menus | ✓ | ✓ |
| Text, progress and indicator panels | ✓ | ✓ |
| Thread safe status updates | ✓ | ✓ |
| Icons, glyphs, themes, keyboard and size grip | ✓ | ✓ |
| Headless PNG and SVG output | ✓ | ✓ |
| Overflow menu | − | ✓ |
| Action links (Delphi) and Command (.NET) | − | ✓ |
| 组件 | 目标 |
|---|---|
| TsgcVCLToolbar, TsgcVCLStatusBar | Delphi 和 C++ Builder,VCL (sgcToolbar_VCL) |
| TsgcFMXToolbar, TsgcFMXStatusBar | Delphi 和 C++ Builder,FireMonkey (sgcToolbar_FMX) |
| TsgcToolbarItem, TsgcStatusBarPanel, TsgcToolbarModel, TsgcStatusBarModel | 框架无关的模型 (sgcToolbar_Model) |
| TsgcWinFormsToolbar, TsgcWinFormsStatusBar | .NET,WinForms |
| TsgcWpfToolbar, TsgcWpfStatusBar | .NET,WPF |
| TsgcAvaloniaToolbar, TsgcAvaloniaStatusBar | .NET,Avalonia |
| 目标 | 组件 | 平台 |
|---|---|---|
| Delphi 7 至 13,VCL | TsgcVCLToolbar, TsgcVCLStatusBar | Win32 和 Win64 |
| Delphi XE6 至 13,FireMonkey | TsgcFMXToolbar, TsgcFMXStatusBar | Windows、macOS、iOS、Android 和 Linux (FMXLinux) |
| C++ Builder 2007 至 13 | VCL 和 FireMonkey 栏 | 生成的 .hpp 头文件和静态库 |
| Delphi 10.2 至 13,框架无关 | 模型和无界面 PNG 与 SVG 渲染器 | Linux64,例如在服务器上渲染工具栏 |
| .NET Framework 4.7.2、.NET 8、9 和 10 | TsgcWinFormsToolbar、WPF 和 Avalonia 栏 | WinForms、WPF 和 Avalonia |
可以。SetPanelText、SetProgress 和 SetIndicator 可从任意线程调用,无需 Synchronize 或 Queue。模型用锁保护这些值,状态栏在主线程上重绘。其他所有属性都在主线程中设置。请参阅线程安全更新。
它承担相同的工作:上方是按钮、切换按钮、下拉按钮、分隔符和标签,下方是文本面板。它还增加了空白填充项、进度和指示器面板、线程安全的设置方法、主题和无界面输出。您现有的 TActionList 和 TPopupMenu 组件可通过 Action 和 DropdownMenu 接入。
缺少溢出菜单和条目的 Action 关联,在 .NET 中即 Command 和 CommandParameter。在社区版中,放不下的条目会被裁剪。其他所有功能,包括线程安全的状态更新、进度和指示器面板以及无界面输出,社区版都有。
可以。C++ Builder 2007 至 13 通过生成的头文件和库使用相同的 VCL 和 FireMonkey 栏,EditorShell 和 LiveStatus 演示也提供 C++ Builder 工程。本页的代码标签页展示了 Delphi、C++ Builder 和 C# 中的同一个工具栏。
清晰。所有尺寸都是逻辑像素乘以显示器的缩放比例,图标位为 16 逻辑像素,因此按钮、字形、进度条和指示器圆点在任何 DPI 下都保持清晰。FireMonkey 会按窗体的设备尺寸从图像列表中获取图像。
可以。TsgcToolbarModel 和 TsgcStatusBarModel 的 SaveToSVG 和 SaveToPNG 无需窗口即可绘制这些栏,自 Delphi 10.2 起在 Linux64 上同样可用,因此构建步骤可以为每个版本重新生成手册中的图片。缩放参数可为高 DPI 屏幕和打印生成清晰的图像。
简介, VCL 快速入门, FireMonkey 快速入门, TsgcVCLToolbar, TsgcVCLStatusBar, 条目类型, 状态面板, 线程安全更新, 版本, 平台.
Delphi、C++ Builder 和 .NET,涵盖每款 sgcUI 产品。