English: subclassing.en.md
从 4.0 起,大多数控件都分成两层,跟 LCL 的 TCustomEdit / TEdit 一个路数(没拆的几个见第 5 节末尾):
TTyCustomXxx:全部实现都在这里。属性按 LCL 的规矩放在 public 或 protected,一个都不发布。TTyXxx:组件面板上的那个类,只有一段published,把该露的属性列出来。
想包一个自己的控件、只给用户看一部分属性,就从 TTyCustomXxx 派生;想要全部属性再加几个,就从 TTyXxx 派生。后一种跟 3.0 一样,什么都不用改。
本页先讲怎么派生,后面是限制,最后一节是从 3.0 升级要注意的地方。
一个只露文字、只读开关和 OnChange 的标签输入框:
unit MyTagEdit;
{$mode objfpc}{$H+}
interface
uses
Classes, tyControls.Edit;
type
TMyTagEdit = class(TTyCustomEdit)
published
property Text;
property ReadOnly;
property OnChange;
end;
procedure Register;
implementation
procedure Register;
begin
RegisterComponents('My Controls', [TMyTagEdit]);
end;
end.放进自己的设计期包,装上就能在面板上看到。对象查看器里只有这三个,加上 LCL 根类本来就发布、藏不掉的那几个(Name、Tag、Left、Top、Width、Height、Hint、Cursor、Anchor*、Help*,共 15 个)。
property Text; 这样不带类型的一行,会把 TTyCustomEdit 里那条声明的 default、stored、读写方法原样带过来,.lfm 里写不写、写什么,跟 TTyEdit 完全一样。不要写成 property Text: string;,那是另起一个新属性,default 和 stored 全丢。
IDE 存窗体时按 published 段的顺序写属性,读回来时按文件里的顺序一个个调 setter。有些 setter 会当场拿另一个属性钳值,所以那个属性得先发布。多数是「范围在前、值在后」,先写值就会被默认的范围钳住:
| Custom 类 | 要先发布 | 再发布 |
|---|---|---|
TTyCustomSpinEdit |
MinValue、MaxValue |
Value,然后 ValueEmpty |
TTyCustomProgressBar |
Min、Max |
Position |
TTyCustomCircularProgress |
Min、Max |
Position |
TTyCustomGauge |
Min、Max |
Value |
TTyCustomMeter |
Min、Max |
Value |
TTyCustomLevelMeter |
Min、Max |
Value |
TTyCustomDial |
Min、Max |
Value |
TTyCustomGearDial |
Min、Max |
Value |
TTyCustomTrackBar |
Min、Max |
Position |
TTyCustomScrollBar |
Min、Max |
Position |
TTyCustomUpDown |
Min、Max |
Position |
TTyCustomRating |
Count |
Value |
TTyCustomFilterComboBox |
Filter |
FilterIndex |
TTyCustomMaskEdit |
Mask |
SpaceChar |
后三行不是范围:Rating 的值按星数钳;FilterIndex 按 Filter 里有几组钳;掩码里自带空白符时,设 Mask 会顺手改掉 SpaceChar。SpinEdit 的 ValueEmpty 要放在 Value 后面,因为写进一个数就会清掉「空」的状态。
拿不准就照对应 TTyXxx 的发布顺序抄。
下面这些不讲究顺序,读窗体期间值会先存着,等 Loaded 时再落:
- 数值编辑框一族(
TTyCustomNumericEdit及货币、滑块、计算器、小数微调框)的Value,按最终的Decimals/MinValue/MaxValue设进去; - 组合框、列表框一族、
TTyCustomButtonGroup、TTyCustomRadioGroup的ItemIndex(列表框还有TopIndex),TTyCustomStringGrid的Col/Row,读到时条目还没有就先存着; TTyCustomColorBox/TTyCustomColorListBox的Selected;TTyCustomPagination的PageIndex、TTyCustomToolWindowBar的ActiveIndex、TTyCustomRibbon的ActivePageIndex和Minimized、TTyCustomRibbonGallery/TTyCustomRibbonBackstage的ItemIndex;TTyCustomSteps的StepIndex本来就不按条目钳。
控件靠 GetStyleTypeKey 报出的主题键找样式(TTyEdit 报 'TyEdit'),这个覆写在 Custom 类里。所以 TMyTagEdit 什么都不写,就吃 TyEdit 的全部 tycss 规则,换主题跟着变。.tycss 里不会出现 TyCustomEdit 这种键,永远写 TyEdit。
想让主题能单独给你的控件换肤,就覆写 GetStyleTypeKey 报一个自己的键,再在单元的 initialization 里登记它从哪个键来:
unit MyTagButton;
{$mode objfpc}{$H+}
interface
uses
Classes, tyControls.Button;
type
TMyTagButton = class(TTyCustomButton)
protected
function GetStyleTypeKey: string; override;
published
property Caption;
property StyleClass;
property OnClick;
end;
implementation
uses
tyControls.StyleModel;
function TMyTagButton.GetStyleTypeKey: string;
begin
Result := 'MyTagButton';
end;
initialization
TyRegisterTypeKeyParent('MyTagButton', 'TyButton');
finalization
TyUnregisterTypeKeyParent('MyTagButton');
end.主题里没写 MyTagButton 时,它和 TTyButton 画得一模一样,StyleClass 下拉里也有 primary、danger 这些按钮的变体;主题想让它不一样,只写不同的地方:
MyTagButton { border-radius: var(--radius-pill); }MyTagButton 先拿到 TyButton 的全部样式,再用自己的规则逐个属性盖上去,按阶段交错:普通规则盖普通规则、变体盖变体、:hover 盖 :hover,但父键更晚阶段的规则仍然有效。所以只给 MyTagButton 写一条普通背景,悬停、禁用时照样是按钮的悬停色、禁用效果;想要自己的悬停色就写 MyTagButton:hover。细节见 tycss-reference.md 第 4.5 节。
几点要注意:
- 链可以有好几级(
MyFancyTag→MyTagButton→TyButton),最多 8 个键。登记成环、超过 8 级、或者同一个键登记两个不同的父键,TyRegisterTypeKeyParent会抛ETyCssError。 - 用
GetStyleTypeKey + 'Fill'这种办法拼子部件键的控件(仪表一族),子部件键要各登记一条,比如TyRegisterTypeKeyParent('MyMeterFill', 'TyMeterFill')。 - 在控件创建之前登记。运行到一半才登记,已经画好的控件不会自己重画。
- 不登记也可以,那这个键就只吃主题里为它写的规则;主题一条都没写,控件就什么样式都没有。
自己的控件包想让控件装上就有样子,不必等每个主题都写到它,就在包里带一份 tycss,用 TyRegisterAddOnCss 交给 TyControls:
uses
tyControls.Css.AddOns;
initialization
TyRegisterAddOnCss('mytags', MyTagsCss);MyTagsCss 返回这份 tycss 的文本,通常是编进程序的字符串。TyAdvanceChart 的图表样式就是这样登记的。
- 登记进去的是两样东西:一份默认 tycss,和从这份文本里取出的词表。
- 默认 tycss 进每个样式模型的底层,排在
light.tycss后面,所以每个主题,内置的、用户自己的,都会用到它。 - 词表是文本里定义的 token(
--名字:)和主题键。设计期 StyleOverride 编辑器的补全里会有它们。 - 词表只收
Ty开头的主题键(和生成内置词表的scripts/gen-tycss-catalog.ps1同一条规则)。别的名字的键照样生效,只是补全里没有。 - 在单元的
initialization里调用,赶在第一个控件创建之前。 - 同一个名字再登记一次,就替换原来的文本。
- 文本载入不了(语法错,或者用了谁都没定义的变量),会被拒绝,异常信息里带着登记时用的名字。
- 已经有样式模型时,
TyRegisterAddOnCss当场抛这个异常,什么都不留下。 - 还没有样式模型时(
initialization里通常如此),下一个建出来的样式模型会去掉它,再抛这个异常。 - 用户主题照样能盖过它:它在底层,用户主题给同一个键或同一个 token 写了值,就以用户主题为准。
- 不要了可以调
TyUnregisterAddOnCss去掉。已经建好的样式模型会跟着去掉它的规则和 token。
主题编辑器不链接你的包,要它认得这些键和 token,见 themebuilder.md 的「附加包的样式」。
跟 LCL 对应的 Custom 类一致:同名属性照抄 LCL 的可见性,没有 LCL 对应物的控件放 public。大致是:
- 编辑框、组合框、列表框、按钮、滑块、滚动条、图像:多数 public;
- 标签、树、列表视图、上下按钮、网格基类(
TTyCustomGrid):多数 protected; TTyCustomCheckBox/TTyCustomRadioButton/TTyCustomToggleSwitch的Checked是 protected(LCL 的TButtonControl.Checked就是)。
protected 的属性照样能在自己的 published 段里发布。只是想让代码从外面访问、又不想进对象查看器,就提到 public:
TMyCheck = class(TTyCustomCheckBox)
public
property Checked;
published
property Caption;
end;属性编辑器会跟过来。 库里的属性编辑器注册在 Custom 类上,或者注册在更上面的基类、中间类上(StyleClass、StyleOverride、Version 在 TTyCustomControl / TTyGraphicControl / TTyComponent,图标按钮的 GlyphName 在 TTyGlyphButtonBase),IDE 按继承关系匹配,你发布了对应属性,对象查看器里就是同一个编辑器。唯一按属性类型注册的是 TTyColor:所有这个类型的属性都显示十六进制值,点「...」取色。
藏起来的属性分两种。Custom 类里声明了 stored False 的(Lucide 图像列表的 IconFont、工具窗口和操作区的 Controller),隐藏编辑器也注册在 Custom 类上,你发布了也看不见——反正改了也存不下来。其余的隐藏编辑器留在最终类上,只管库里那个控件的对象查看器,你发布了就能看见、能改。
组件编辑器不会跟过来。 双击、右键菜单里的那些动作(组件编辑器)留在最终类上,因为它们会改属性,而你的子类未必发布了那些属性。下面这些在你的子类上没有:
| 组件编辑器 | 注册在 | 动作 |
|---|---|---|
| 页控件编辑器 | TTyPageControl |
添加页、删除页、下一页、上一页、显示页 |
| 工具窗口栏编辑器 | TTyToolWindowBar |
新建工具窗口、显示窗口 |
| 工具窗口编辑器 | TTyToolWindow |
添加操作区、移到另一侧、移回栏里 |
| 树节点编辑器 | TTyTreeView |
双击编辑节点 |
| 级联选择 / 树形选择的节点编辑器 | TTyCascader、TTyTreeSelect |
双击编辑选项树 |
| 列表分组编辑器 | TTyListGroupPanel |
编辑分组 |
| 终端编辑器 | TTyTerminalView |
导入 / 导出配色方案 |
| 图像集合编辑器 | TTyImageCollection |
管理图片 |
| 对话框预览 | 各对话框 | 预览 |
| 图标浏览器 | TTyIconFont、TTyLucideIconFont、TTyVirtualImageList、TTyLucideImageList |
浏览图标 |
高级图表在独立项目 TyAdvanceChart 里,它的图表编辑器也在那边。
TTyFormSurface 的 Purpose 说明和 Version 编辑器也留在最终类上;你的表面子类发布 Purpose 时,它只是一个普通的只读字符串。
这些编辑器的实现里写的是 Component as TTyPageControl 这样的最终类,所以不能直接把它们注册给你的类——一点菜单就抛 EInvalidCast。对话框预览(TTyDialogComponentEditor)判的也是最终类,只是用 is:注册给你的对话框类不会抛异常,点「预览」什么都不发生。
唯一能直接借用的是图标浏览器(TTyIconBrowserComponentEditor),它认任何 TTyCustomIconFont / TTyCustomVirtualImageList。它在设计期包 tycontrols_dt 的 tyControls.Design.CompEditors 单元里,所以你的设计期包要依赖 tycontrols_dt,uses 这个单元,再在 Register 里写 RegisterComponentEditor(TMyIconFont, TTyIconBrowserComponentEditor)。
其余的要自己写一个,不长。以页控件的「添加页」为例:
uses
Classes, ComponentEditors, PropEdits, tyControls.PageControl, tyControls.TabSheet;
type
TMyPageControlEditor = class(TDefaultComponentEditor)
public
function GetVerbCount: Integer; override;
function GetVerb(Index: Integer): string; override;
procedure ExecuteVerb(Index: Integer); override;
end;
function TMyPageControlEditor.GetVerbCount: Integer;
begin
Result := 1;
end;
function TMyPageControlEditor.GetVerb(Index: Integer): string;
begin
Result := 'Add page';
end;
procedure TMyPageControlEditor.ExecuteVerb(Index: Integer);
var
PC: TTyCustomPageControl;
Hook: TPropertyEditorHook;
NewPage: TTyTabSheet;
NewName: string;
begin
PC := Component as TTyCustomPageControl;
Hook := nil;
if not GetHook(Hook) then Exit;
NewPage := TTyTabSheet.Create(PC.Owner);
NewPage.Parent := PC; // 先挂到页控件上,页才算进去
NewName := GetDesigner.CreateUniqueComponentName(NewPage.ClassName);
NewPage.Caption := NewName;
NewPage.Name := NewName;
PC.ActivePage := NewPage;
Hook.PersistentAdded(NewPage, True);
Modified;
end;
// 在设计期包的 Register 里:
// RegisterComponentEditor(TMyPageControl, TMyPageControlEditor);删页、翻页要用的 Pages[]、PageCount、ActivePage、ActivePageIndex 在 TTyCustomPageControl 上都是 public。别的家族同理:组件编辑器里把对象当成 Custom 类来用。
DefineProperties 也在 Custom 类里。 库里只有 TTyCustomVirtualImageList(Lucide 图像列表也从它来)覆写了它:照常写非可视组件在窗体上的设计位置(Left / Top),故意不写 TCustomImageList 那块 Bitmap 像素数据——图在 Loaded 里按名字重新生成,旧窗体里存着的那块读到就丢掉。你的子类不管发布了什么,都是这样。
- LCL 根类发布的 15 个属性藏不掉。
TComponent的Name、Tag,TControl的Left、Top、Width、Height、Hint、Cursor、四个AnchorSide*、三个Help*。Pascal 没法取消发布,LCL 自己的 Custom 类也一样。 - 宿主交出的子项有时仍是最终类型。 多数宿主属性已经写成 Custom 类(见第 7 节),但只交出自己建的那个类的保持不变:
TTyRadioGroup的按钮是TTyRadioButton,TTyCheckGroup的是TTyCheckBox,TTyPageControl.AddPage返回TTyTabSheet,TTyFilterComboBox.ShellListView是TTyShellListView(照 LCL 的TFilterComboBox)。 GlyphName编辑器按名字找宿主的IconFont。 你的子类要在对象查看器里用图标下拉,就得发布IconFont。TTyGridCell由TTyGridPanel自己建。 你的格子子类只能在代码里手动放进去。- 你的
TTyCustomScrollBar子类永远是独立滚动条。 宿主只内嵌自己建的TTyScrollBar,不会把你的条当成内嵌条。 - 行是代码生成的列表框、组合框,别让
Items进.lfm。TTyCustomListBox、TTyCustomComboBox默认把Items写进窗体文件,因为作者在对象查看器里填的行就该存下来。如果你的子类的行是按别的属性算出来的(比如按Style填一张色板),在构造函数里inherited Create(AOwner);之后加一句FItemsStreamed := False;。否则 IDE 存窗体时会把算出来的行也写进去:TStrings只存文字、不存Objects,读回来这份残缺的行还会盖掉你刚算好的。读旧窗体不受影响,文件里有Items块照样读得进来。库里的颜色框、颜色列表框和TTyComboBoxEx都是这样做的。 - Lucide 图像列表的
IconFont固定是内置的 Lucide 字体。TTyCustomLucideImageList在构造函数里设好它,声明为stored False,隐藏编辑器也注册在 Custom 类上。你的子类发布了IconFont,对象查看器里也看不到;代码里改了能用,但不会存进.lfm。想自己选字体,从TTyCustomVirtualImageList派生。 - 可以放心不发布的: 编辑框、多行编辑框、组合框的
Text。这三个家族的Caption就是Text,TTyUpDown之类按Caption驱动的东西照样能用。
下面这些没有 TTyCustomXxx,要派生就直接从组件面板上的那个类派生,它发布的属性你都会继承下来、藏不掉:
| 类 | 为什么不拆 | 怎么派生 | 以后拆不拆 |
|---|---|---|---|
菜单:TTyPopupMenu、TTyImagesMenu、TTyMenuEx |
LCL 的 TPopupMenu 也不拆 |
直接派生 | 跟 LCL,不拆 |
对话框:TTySelectPathDialog、TTyColorDialog、TTyFontDialog、TTyFindDialog、TTyReplaceDialog、TTyOpenDialog、TTySaveDialog、TTyOpenPictureDialog、TTySavePictureDialog、TTyOpenPreviewDialog、TTySavePreviewDialog |
LCL 的 TCommonDialog 一系(TOpenDialog、TColorDialog……)每层都直接发布 |
直接派生 | 跟 LCL,不拆 |
TTyForm、TTyDialog |
它们扮演的是 TForm 的角色:你的窗体本来就从它们派生 |
照常「新建窗体」,或者 class(TTyForm) |
不拆 |
TTyToolWindowManager |
已经有 TTyCustomToolWindowManager(什么都不发布),但跨栏移动、排队、布局保存这些实现为了单元依赖放在最终类里 |
从 TTyToolWindowManager 派生,别从 TTyCustomToolWindowManager 派生——后者挂得上栏的 Manager,却不会移动窗口、存不了布局 |
等实现能挪进 Custom 类再拆,目前没排期 |
另外 8 个 Ty 自己的对话框(TTyMessage、TTyInputDialog、TTyPasswordDialog、TTyTextDialog、TTySelectValueDialog、TTyProgressDialog、TTyAboutDialog、TTyIconBrowserDialog)是拆了的,LCL 的 TCustomTaskDialog / TTaskDialog 也是这么拆。
数据感知控件包 tycontrols_db 里的 21 个控件也都拆了:TTyDBEdit 的实现在 TTyCustomDBEdit,TTyDBNavigator 的在 TTyCustomDBNavigator,其余同理。DataSource、DataField、ReadOnly、Field 在 Custom 类上是 public(和 LCL 的 TCustomDBComboBox 一样),从 TTyCustomDBXxx 派生时挑需要的发布即可。
TTyCustomControl(窗口化)和 TTyGraphicControl(图形)在 4.0 里什么都不发布,跟 LCL 的 TCustomControl / TGraphicControl 一样。从它们直接派生的控件,下面这段是 Ty 控件惯用的通用属性,整段抄进自己的 published 段即可(顺序就是 Ty 控件的顺序):
published
property Version; // 库版本,对象查看器里点开是 About 对话框
property Enabled;
property Visible; // 对象查看器和 .lfm 里能直接藏控件
property Font; // 主要用来传 PPI;字体族与字号由主题决定
property ShowHint;
property TabOrder; // 窗口化才有
property TabStop; // 窗口化才有
property OnClick;
property OnDblClick;
property OnMouseDown;
property OnMouseUp;
property OnMouseMove;
property OnMouseEnter;
property OnMouseLeave;
property OnMouseWheel;
property OnMouseWheelUp;
property OnMouseWheelDown;
property OnContextPopup;
property OnResize;
property OnChangeBounds;
property AutoSize; // 实现了 CalculatePreferredSize 才有意义
property BorderWidth; // 窗口化才有:子控件区域整体内缩,不是边框粗细
property ChildSizing; // 窗口化才有:LCL 的子控件自动排布
property DragMode; // 拖放全由 LCL 分发,自绘控件白拿
property DragKind;
property DragCursor;
property OnDragOver;
property OnDragDrop;
property OnStartDrag;
property OnEndDrag;
property OnMouseWheelHorz; // 横向滚轮、倾斜轮、触控板横扫只从这三个到达
property OnMouseWheelLeft;
property OnMouseWheelRight;
property OnShowHint; // 按指针位置换提示文字的唯一入口
property PopupMenu;
property Constraints;
property BorderSpacing;
property ParentShowHint;
property Action;
property OnPaint; // 控件画完之后触发,叠加用,不是自绘
property OnKeyDown; // 以下七个窗口化才有
property OnKeyUp;
property OnKeyPress;
property OnUTF8KeyPress;
property OnEnter;
property OnExit;
property OnEditingDone;
property StyleClass; // 主题变体,比如 'primary'
property StyleOverride; // 只改这一个控件的 tycss 片段
property Controller; // 用哪个样式控制器,空着就是全局默认图形控件把标了「窗口化才有」的几行删掉。多数 Ty 控件另外还发布 Align、Anchors,按需加。
这些属性各自的行为见 events.md。
.lfm 不用改,主题不用改。 每个控件的属性名、默认值、写出顺序、默认尺寸、主题键都跟 3.0 一样。要改的只是代码里涉及类层级和类型的地方,编译器会帮你找出大部分。
派生控件现在挂在 Custom 链上,不再是原来父控件的后代。TTyGlyphButton is TTyButton 在 3.0 是 True,在 4.0 是 False。
| 控件 | 3.0 的父类 | 4.0 的父类(TTyCustomXxx 的父类) |
不再是谁的后代 |
|---|---|---|---|
| TTyDropDownButton | TTyButton | TTyCustomButton | TTyButton |
| TTyMenuButton | TTyButton | TTyCustomButton | TTyButton |
| TTyColorButton | TTyButton | TTyCustomButton | TTyButton |
| TTyGlyphButton | TTyGlyphButtonBase | TTyGlyphButtonBase(← TTyCustomButton) | TTyButton |
| TTyGlyphContainerButton | TTyGlyphButtonBase | TTyGlyphButtonBase | TTyButton |
| TTySpeedButton | TTyGlyphButtonBase | TTyGlyphButtonBase | TTyButton |
| TTyToolButton | TTyGlyphButtonBase | TTyGlyphButtonBase | TTyButton |
| TTyRibbonAppMenu | TTyMenuButton | TTyCustomMenuButton | TTyMenuButton、TTyButton |
| TTyNumericEdit | TTyEdit | TTyCustomEdit | TTyEdit |
| TTyMaskEdit | TTyEdit | TTyCustomEdit | TTyEdit |
| TTyURLEdit | TTyEdit | TTyCustomEdit | TTyEdit |
| TTyComboEdit | TTyEdit | TTyCustomEdit | TTyEdit |
| TTyCurrencyEdit | TTyNumericEdit | TTyCustomNumericEdit | TTyNumericEdit、TTyEdit |
| TTyTrackEdit | TTyNumericEdit | TTyCustomNumericEdit | TTyNumericEdit、TTyEdit |
| TTyCalcEdit | TTyNumericEdit | TTyCustomNumericEdit | TTyNumericEdit、TTyEdit |
| TTyFloatSpinEdit | TTyNumericEdit | TTyCustomNumericEdit | TTyNumericEdit、TTyEdit |
| TTyCalcCurrencyEdit | TTyCurrencyEdit | TTyCustomCurrencyEdit | TTyCurrencyEdit、TTyNumericEdit、TTyEdit |
| TTyMRUComboBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyComboBoxEx | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyOfficeComboBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyAdvancedComboBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyCheckComboBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyColorBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyFontComboBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyFontSizeComboBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyFilterComboBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyShellComboBox | TTyComboBox | TTyCustomComboBox | TTyComboBox |
| TTyColorComboBox | TTyColorBox | TTyCustomColorBox | TTyColorBox、TTyComboBox |
| TTyCheckListBox | TTyListBox | TTyCustomListBox | TTyListBox |
| TTyOfficeListBox | TTyListBox | TTyCustomListBox | TTyListBox |
| TTyAdvancedListBox | TTyListBox | TTyCustomListBox | TTyListBox |
| TTyValueListEditor | TTyListBox | TTyCustomListBox | TTyListBox |
| TTyColorListBox | TTyListBox | TTyCustomListBox | TTyListBox |
| TTyFontListBox | TTyListBox | TTyCustomListBox | TTyListBox |
| TTyRadioGroup | TTyGroupBox | TTyCustomGroupBox | TTyGroupBox |
| TTyCheckGroup | TTyGroupBox | TTyCustomGroupBox | TTyGroupBox |
| TTyToolGroupPanel | TTyGroupBox | TTyCustomGroupBox | TTyGroupBox |
| TTyPaintPanel | TTyPanel | TTyCustomPanel | TTyPanel |
| TTyExPanel | TTyPanel | TTyCustomPanel | TTyPanel |
| TTyGridPanel | TTyPanel | TTyCustomPanel | TTyPanel |
| TTyRelativePanel | TTyPanel | TTyCustomPanel | TTyPanel |
| TTyScrollBox | TTyPanel | TTyCustomPanel | TTyPanel |
| TTyControlBar | TTyPanel | TTyCustomPanel | TTyPanel |
| TTyScrollPanel | TTyScrollBox | TTyCustomScrollBox | TTyScrollBox、TTyPanel |
| TTyCoolBar | TTyControlBar | TTyCustomControlBar | TTyControlBar、TTyPanel |
| TTyToolBarEx | TTyToolBar | TTyCustomToolBar | TTyToolBar |
| TTyShellTreeView | TTyShellTreeLink | TTyShellTreeLink(← TTyCustomTreeView) | TTyTreeView |
| TTyShellListView | TTyListView | TTyCustomListView | TTyListView |
| TTyStringGrid | TTyDrawGrid | TTyCustomDrawGrid | TTyDrawGrid |
| TTyLucideIconFont | TTyIconPackFont | TTyIconPackFont(← TTyCustomIconFont) | TTyIconFont |
| TTyLucideImageList | TTyVirtualImageList | TTyCustomVirtualImageList | TTyVirtualImageList |
TTyPageControl、TTyTabSet、TTyRibbon(在 TTyCustomTabStrip 下)和 TTyDrawGrid(在 TTyCustomGrid 下)父类没变,只是中间类不再发布东西。
规则只有一条:想表示「任意 Xxx」,就判 TTyCustomXxx;只想要「恰好这个类」的,保持原样。
// 3.0:工具栏上的 TTyToolButton、TTyGlyphButton 在 4.0 下会抛 EInvalidCast
StatusBar1.SimpleText := (Sender as TTyButton).Caption;
// 4.0
StatusBar1.SimpleText := (Sender as TTyCustomButton).Caption;
// 3.0:对 TTyNumericEdit、TTyMaskEdit 等静默变成 False
if AControl is TTyEdit then ...
// 4.0
if AControl is TTyCustomEdit then ...is 静默变 False、as 运行时抛 EInvalidCast、把派生控件赋给父控件类型的变量编不过——三种都可能遇到。硬转 TTyButton(AGlyphButton) 仍然「能跑」(最终类不加字段),但对象不是那个类,按上面的规则改掉。
判成 Custom 类以后,如果要访问的属性在 Custom 类里是 protected(见第 3 节),而对象确实是库里的控件,就用 as TTyXxx 转成那个最终类:对库里的控件没有问题;万一碰上第三方子类,会抛 EInvalidCast,不会悄悄读错。
有 Custom 类的家族里,事件的 Sender 写的是 Custom 类(跟 LCL 的 TTVCustomDrawEvent = procedure(Sender: TCustomTreeView; ...) 一样)。涉及:
TTyTreeView的 21 个事件类型(OnGetText、OnPaintText、OnCompareNodes、OnInitChildren、OnChecking等):Sender: TTyCustomTreeView;TTyHeaderControl的TTyHeaderSectionEvent、TTyHeaderResizeEvent、TTyHeaderTrackEvent:TTyCustomHeaderControl;TTyStatusBar.OnDrawPanel:AStatusBar: TTyCustomStatusBar;TTyToolBar.OnPaintButton:Sender: TTyCustomToolButton;TTyRibbonGroup.OnDialogLauncher:Sender: TTyCustomRibbonGroup;TTyToolWindowManager.OnCanMoveWindow/OnWindowMoved的窗口、栏参数(不是 Sender):TTyCustomToolWindow、TTyCustomToolWindowBar。
// 3.0
procedure TForm1.TreeGetText(Sender: TTyTreeView; Node: PTyTreeNode; var Text: string);
// 4.0
procedure TForm1.TreeGetText(Sender: TTyCustomTreeView; Node: PTyTreeNode; var Text: string);.lfm 里按方法名关联,不查签名,所以窗体文件不用动;改完声明重新编译即可。
引用组件的属性照 LCL(Images: TCustomImageList)写 Custom 类,这样库里的派生组件和你自己的子类都挂得上:
| 属性 | 3.0 | 4.0 |
|---|---|---|
所有 IconFont |
TTyIconFont |
TTyCustomIconFont |
所有 Controller |
TTyStyleController |
TTyCustomStyleController |
Images / HotImages / DisabledImages(图像集合)、TTyVirtualImageList.Collection |
TTyImageCollection |
TTyCustomImageCollection |
TTyForm.TitleBar / MenuBar(TTyDialog 同) |
TTyTitleBar / TTyMenuBar |
TTyCustomTitleBar / TTyCustomMenuBar |
TTyRibbon.Backstage、TTyRibbonAppMenu.Backstage |
TTyRibbonBackstage |
TTyCustomRibbonBackstage |
TTyShellTreeView.ShellListView |
TTyShellListView |
TTyCustomShellListView |
宿主交出「它接受的任意子项」时也写 Custom 类:
TTyPageControl.ActivePage/Pages[]:TTyCustomTabSheet;TTyRibbon.ActivePage/Pages[]:TTyCustomRibbonPage;TTyToolBar.Buttons[]、IndexOfButton、TTyToolButton.ToolBar:TTyCustomToolButton/TTyCustomToolBar;TTySpeedButton.FindDownButton:TTyCustomSpeedButton;- 工具窗口一族交出的窗口、栏、操作区(
Windows[]、ActiveWindow、Bar、Actions、EnsureActions等):对应的 Custom 类; - 组合框弹层 API(
CreatePopupList等):TTyCustomListBox。
于是下面这样的赋值编不过:
var
Ts: TTyTabSheet;
begin
Ts := PageControl1.ActivePage; // 4.0:ActivePage 是 TTyCustomTabSheet把变量类型改成 Custom 类;确知拿到的是库里的控件、又要用最终类才有的东西,就写 Ts := PageControl1.ActivePage as TTyTabSheet;。
覆写了这些虚方法的,签名一起改。Controller 也是这样:TTyStyleController 只是把 TTyCustomStyleController 的属性发布出来,没加别的,代码里把 Button1.Controller 赋给 TTyStyleController 类型变量的,把变量类型改成 TTyCustomStyleController 就行;覆写了 SetController 的,参数类型一起改。
3.0 的两个基类把 TControl 的一批 protected 成员提成了 published,4.0 还给 LCL。经 TTyCustomControl、TTyGraphicControl 或任何 TTyCustomXxx 类型的引用访问它们就编不过(经最终类类型照常):
OnDblClick、OnMouseDown、OnMouseUp、OnMouseMove、OnMouseEnter、OnMouseLeave、OnMouseWheel、OnMouseWheelUp、OnMouseWheelDown、OnMouseWheelHorz、OnMouseWheelLeft、OnMouseWheelRight、OnContextPopup、DragMode、DragKind、DragCursor、OnDragOver、OnDragDrop、OnStartDrag、OnEndDrag、ParentShowHint,外加窗口化的 OnEditingDone、图形控件的 OnPaint。
OnKeyDown、OnEnter、TabOrder、Enabled、Visible、Font、OnClick、PopupMenu 这些在 LCL 里本来就是 public,不受影响。
要给「任意 Ty 控件」统一挂事件,用 LCL 惯用的 access 类:
type
TControlAccess = class(TControl);
TControlAccess(C).OnMouseDown := @MyMouseDown; // 对一切 TControl 都成立或者按 RTTI:SetMethodProp(C, 'OnMouseDown', TMethod(Handler)),每个最终类都发布了这些名字。
如果你的控件直接继承 TTyCustomControl / TTyGraphicControl / TTyComponent,它在 4.0 里少了 Enabled、Visible、Font、OnClick 等约 50 个 published 属性,已有 .lfm 读入时会报「Unknown property」。把第 6 节那段 published 抄进自己的类就好;非可视组件只需要 property Version;。从任何 TTyXxx 最终类派生的不受影响。
TTyGlyphButtonBase、TTyCustomTabStrip、TTyCustomGrid、TTyIconPackFont 不再发布任何东西;TTyGlyphButtonBase、TTyShellTreeLink、TTyIconPackFont 的父类也换成了 Custom 类。直接继承它们的类要自己发布需要的属性,或者改从对应的最终类派生。.lfm 里写着 object X: TTyCustomGrid 的,换成 TTyDrawGrid。
TTyIconFont.Version: Integer(字形变更计数)改名ChangeStamp;Version现在是库版本字符串,跟其他组件一样。Base.pas里原来解释「基类为什么发布这些属性」的长注释删了,内容并进了第 6 节那段代码的逐行说明和 events.md。