Skip to content

Latest commit

 

History

History
544 lines (412 loc) · 31.7 KB

subclassing.md

File metadata and controls

544 lines (412 loc) · 31.7 KB

从 TyControls 控件派生

English: subclassing.en.md

从 4.0 起,大多数控件都分成两层,跟 LCL 的 TCustomEdit / TEdit 一个路数(没拆的几个见第 5 节末尾):

  • TTyCustomXxx:全部实现都在这里。属性按 LCL 的规矩放在 public 或 protected,一个都不发布。
  • TTyXxx:组件面板上的那个类,只有一段 published,把该露的属性列出来。

想包一个自己的控件、只给用户看一部分属性,就从 TTyCustomXxx 派生;想要全部属性再加几个,就从 TTyXxx 派生。后一种跟 3.0 一样,什么都不用改。

本页先讲怎么派生,后面是限制,最后一节是从 3.0 升级要注意的地方。


1. 一个最小的例子

一个只露文字、只读开关和 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 全丢。

发布顺序就是 .lfm 的写出顺序

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 本来就不按条目钳。

2. 主题

控件靠 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 的「附加包的样式」。


3. Custom 类里属性的可见性

跟 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;

4. 设计期

属性编辑器会跟过来。 库里的属性编辑器注册在 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 里按名字重新生成,旧窗体里存着的那块读到就丢掉。你的子类不管发布了什么,都是这样。


5. 限制

  • 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 派生时挑需要的发布即可。


6. 直接从基类写一个全新的控件

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。


7. 从 3.0 升级

.lfm 不用改,主题不用改。 每个控件的属性名、默认值、写出顺序、默认尺寸、主题键都跟 3.0 一样。要改的只是代码里涉及类层级和类型的地方,编译器会帮你找出大部分。

7.1 父类变了的控件

派生控件现在挂在 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 下)父类没变,只是中间类不再发布东西。

7.2 is、as 和强转

规则只有一条:想表示「任意 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,不会悄悄读错。

7.3 事件处理过程的签名

有 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 里按方法名关联,不查签名,所以窗体文件不用动;改完声明重新编译即可。

7.4 属性、返回值的类型

引用组件的属性照 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 的,参数类型一起改。

7.5 经基类或 Custom 类引用访问 protected 成员

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)),每个最终类都发布了这些名字。

7.6 直接继承基类的自定义控件

如果你的控件直接继承 TTyCustomControl / TTyGraphicControl / TTyComponent,它在 4.0 里少了 Enabled、Visible、Font、OnClick 等约 50 个 published 属性,已有 .lfm 读入时会报「Unknown property」。把第 6 节那段 published 抄进自己的类就好;非可视组件只需要 property Version;。从任何 TTyXxx 最终类派生的不受影响。

7.7 中间类

TTyGlyphButtonBase、TTyCustomTabStrip、TTyCustomGrid、TTyIconPackFont 不再发布任何东西;TTyGlyphButtonBase、TTyShellTreeLink、TTyIconPackFont 的父类也换成了 Custom 类。直接继承它们的类要自己发布需要的属性,或者改从对应的最终类派生。.lfm 里写着 object X: TTyCustomGrid 的,换成 TTyDrawGrid。

7.8 其他

  • TTyIconFont.Version: Integer(字形变更计数)改名 ChangeStamp;Version 现在是库版本字符串,跟其他组件一样。
  • Base.pas 里原来解释「基类为什么发布这些属性」的长注释删了,内容并进了第 6 节那段代码的逐行说明和 events.md。