README

TyControls

Lazarus 自绘控件库。195 个控件全部由 BGRABitmap 绘制,外观由 .tycss 文本主题统一控制,在 Windows、Linux、macOS 上显示效果完全一致。

English: README.en.md · 更新日志: CHANGELOG.md

同一个程序,只换一个主题名:

classic	win11	material3

三张图是同一个窗口、同一份代码,只改了主题名。主题不只换配色:classic 下按钮是立体边框、方角、渐变标题带。全部内置主题的对照见图库。

亮 / 暗 / 图片主题

亮色	暗色	green(图片主题)

亮暗是同一个主题文件里的两套 @mode 取值,可跟随操作系统。green 是照片背景加半透明控件的图片主题。

几个控件的样子

TTyStringGrid 按列指定编辑器:复选、星级、取色、按钮
	TTyTreeView 虚拟树、多列、三态复选
富输入控件 数值 / 货币 / 掩码 / 滑块 / 计算器
	TTyChart 折线、柱状、饼图、环形图
TTyRibbon 功能区、快速访问栏、Alt 键提示
	TTyCalendar 周数、今日高亮、可选日期范围
TTyAdvanceChart 直接读 ECharts 的配置,示例里是官方图库的例子
	TTyDBGrid 绑数据集的表格:勾选、查找下拉、格式化金额、多选
TTyPropertyGrid 属性表格:点哪个控件就检查哪个,改了直接写回
	多滑块 TrackBar 区间、多值、渐变色标

每个示例每个标签页的亮色、暗色截图都在图库里。

特性

• 195 个控件:按钮、输入、列表、数据网格、虚拟树、Ribbon、日历、Shell 文件浏览、20 个自绘对话框、22 个数据感知控件,一套配齐
• ECharts 式图表:TTyAdvanceChart 的配置就是 Apache ECharts 的 option,ECharts 的文档可以直接参考,示例里的配置原样贴进来;能画折线、柱状、饼图、散点、雷达、热力图、树图、旭日图、桑基图等,坐标轴和文字跟着主题换肤
• 数据感知控件:单独的 tycontrols_db 包,22 个控件绑上 TDataSource 的字段就能用,其中数据表格 TTyDBGrid 的行为照 LCL TDBGrid
• 属性表格:TTyPropertyGrid 在程序运行时列出任意对象的 published 属性,改了直接写回,可多选、按名字过滤、分类显示
• 终端:TTyTerminalView 照 xterm.js 解析输出、编码按键;示例里接上 ConPTY / PTY 就是一个能用的 shell 窗口
• 能派生:大多数控件分成 TTyCustomXxx(实现,不发布属性)和 TTyXxx(面板上那个)两层,包装自己的控件时只露想露的属性;派生类自动沿用父类的主题样式,也能登记自己的主题键单独换肤,见 subclassing.md
• 三平台一致:完全自绘,不包装原生控件,同一份代码在三个平台上渲染出同样的界面
• 主题换肤:17 个内置主题一个属性切换,支持运行时热切换、跟随系统明暗和强调色;主题是文本文件,改外观不用重编译
• 经典与现代两种风格:从 Win95 / XP 的立体风到 Win11 / Material 的扁平风都能做,控件密度也可整体切换
• HiDPI:矢量绘制,任意缩放比例下清晰;跨屏拖动自动适配新 DPI
• 设计器支持完整:组件面板拖放、容器控件直接拖入、主题效果设计期可见、File → New 工程模板
• 内置 2022 个矢量图标(Lucide),按名字取用,不用则不占体积
• 中英文界面,gettext .po 翻译
• 一万多个单元测试,全套无内存泄漏

支持平台

依赖:Lazarus 3.0+、FPC 3.2.2+、BGRABitmap(OPM 包名 BGRABitmapPack)。

快速开始

1. 安装包

Lazarus 里打开 tycontrols_dt.lpk,点 Use → Install,IDE 重新编译并重启。运行期包 tycontrols.lpk 和数据感知控件包 tycontrols_db.lpk 作为依赖自动安装。

2. 新建工程

File → New… → Project → TyControls 应用程序

模板生成的主窗体已带自绘标题栏、内容容器 Surface 和样式控制器。控件放在 Surface 里(TTyForm 的可视控件都放它上面,图形控件必须放进去,详见 TTyForm 文档)。给已有工程加窗体用 File → New… → Form → TyControls 窗体。

3. 换主题

选中窗体上的 TTyStyleController,把 ThemeName 改成任意内置主题名。设计器里立即生效,运行时改同一个属性即热切换。模板生成的 .lpr 已在启动时调用 TyRegisterBuiltinThemes;用别的方式建的工程也要加上这一行,否则按名字选的内置主题只在设计器里生效。

完整步骤见 docs/getting-started.md。

控件清单

195 个控件,分 17 个组件面板分页。每个控件的属性、事件、主题键说明见 docs/controls/。

核心 · TyControls(2)

按钮 · TyControls Buttons(8)

标签与标记 · TyControls Labels(7)

文本与数值输入 · TyControls Edits(15)

勾选与开关 · TyControls Choices(6)

列表与下拉 · TyControls Lists(15)

颜色 / 字体 / 文件选择器 · TyControls Pickers(11)

仪表与指示器 · TyControls Gauges(12)

条状控件 · TyControls Bars(18)

容器与布局 · TyControls Containers(22)

数据视图 · TyControls Data Views(10)

数据感知 · TyControls Data Controls(22)

单独的包 tycontrols_db,绑 TDataSource 的字段即用,外观跟随主题。说明见 docs/controls/dbcontrols.md,数据表格见 docs/controls/dbgrid.md。

菜单 · TyControls Menus(4)

Ribbon · TyControls Ribbon(7)

图像与提示 · TyControls Images(11)

内置图标(Lucide):加一行 uses tyControls.Icons.Lucide 就有 2022 个矢量图标,按名字取用:

CharImage1.IconFont  := TyLucideFont;
CharImage1.GlyphName := 'house';

字体内嵌在单元里,不用随程序分发文件;不 uses 就不进最终程序。组件面板上的 TTyLucideImageList 可以直接当图像列表拖放使用。许可为 ISC / MIT,商用无需署名,随发布带上 THIRD-PARTY-NOTICES.md 即可。

图形与图表 · TyControls Shapes & Charts(5)

对话框 · TyControls Dialogs(20)

几个大控件的完整能力见各自文档:grid.md(TTyStringGrid)· treeview.md(TTyTreeView)· ttyform.md(TTyForm)· dbgrid.md(TTyDBGrid)· propertygrid.md(TTyPropertyGrid)· terminal.md(TTyTerminalView)· multitrackbar.md(多滑块)· advancechart.md(TTyAdvanceChart)。

主题

内置主题编译进二进制,程序不用带 themes/ 文件夹就能按名切换:

另有图片主题 green(以文件提供)和 themes/palettes/ 调色板。所有主题共用同一套语义变量,--accent 可在运行时覆盖成任意品牌色。

写自己的主题见 docs/themes.md,.tycss 语言参考见 docs/tycss-reference.md。

写主题可以用仓库里的主题编辑器 tools/themebuilder:边写边看预览,也可以接大模型用一句话起草或修改。用法见 docs/themebuilder.md。

示例

52 个示例,每个都可独立构建:lazbuild examples/<名称>/<工程>.lpi。界面跟随系统语言显示中文或英文,每个示例的标题栏上都能换主题、切亮暗。

综合示例

单控件示例

文档

界面语言

库自带中英文界面。LCL 的 SetDefaultLang 只加载应用自己的 .po,库的翻译要多加一行:

uses ..., LCLTranslator;

SetDefaultLang('', LangDir);                                                        // 应用
TranslateUnitResourceStringsEx('', LangDir, 'tycontrols', 'tyControls.StrConsts');  // 控件库

部署时把 languages/tycontrols.<语言>.po 与应用自己的 .po 放在同一个 languages/ 目录。注意几点:

• 部署文件名是 tycontrols.<语言>.po,由源码里的 tycontrols.strconsts.<语言>.po 改名而来。第三个参数必须传 'tycontrols'(不能带点,LCL 会把点号后面当扩展名剥掉),第四个参数传真实单元名 tyControls.StrConsts。
• 英文部署也要带 tycontrols.en.po,它是日历和日期框的月份、星期名跟随应用语言的开关。
• 用了数据感知控件(tycontrols_db)的,再加一行 TranslateUnitResourceStringsEx('', LangDir, 'tycontrols_db', 'tyControls.DB.StrConsts'),部署 tycontrols.db.strconsts.<语言>.po 改名后的 tycontrols_db.<语言>.po。

完整示例见 examples/demo。

许可

修改版 LGPL,与 FPC RTL / LCL / BGRABitmap 相同:可以静态链接进闭源商业软件分发;修改库本身的源码时,修改部分需以同样许可开放。

完整条款见 COPYING.modifiedLGPL.txt 与 COPYING.LGPL.txt。