42 KiB
42 KiB
增强组件属性手册（Smart.CustomComponents 全部 13 控件 + 条目类型 + 枚举，穷尽版）
生成来源：反射
Smart.CustomComponents.dll（bin\Debug 编译产物）+ 源码逐文件核对（src\Libraries\CustomComponents\Controls）。属性名/类型/默认值以 DLL 与源码为准。 工具箱类别：增强组件（13 个控件）。Designer.cs 代码生成规则另见codegen.md。 序列化列约定：Content 集合=逐条目生成；不序列化=设计器/手写都不写；非默认才写=与默认值相同则省略；ShouldSerialize=与出厂值比较不同才写。
目录
- 停靠面板 DockSurface（WeifenLuo.WinFormsUI.Docking.DockPanel）
- 圆角按钮 RoundedButton（System.Windows.Forms.Control）
- 图片按钮 ImageButton（System.Windows.Forms.Control）
- 增强数据表格 EnhancedDataGridView（System.Windows.Forms.DataGridView）
- 多选下拉框 MultiSelectComboBox（System.Windows.Forms.Control）
- 可调高下拉框 ResizableComboBox（System.Windows.Forms.Control）
- 可调高文本框 ResizableTextBox（System.Windows.Forms.Control）
- OK/NG 状态灯 OKNGStatusControl（System.Windows.Forms.Control）
- 侧边菜单 SideMenuPanel（System.Windows.Forms.UserControl）
- 功能区 RibbonStrip（System.Windows.Forms.UserControl）
- 变量显示标签 VariableDisplayLabel（System.Windows.Forms.Control）
- 变量编辑框 VariableEditTextBox（System.Windows.Forms.TextBox）
- 日志记录器 Logger（非可视组件）（System.ComponentModel.Component）
停靠面板 DockSurface
继承：Smart.CustomComponents.DockSurface ← WeifenLuo.WinFormsUI.Docking.DockPanel
停靠窗口宿主容器。设计器拖入窗体后通过 DockWindows 集合声明若干停靠窗口，用"生成停靠窗口代码"（等价手写三文件）生成窗口类。主题=VS2015Light 起步。
属性（全部 4 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| DockTheme | SurfaceTheme | VS2015Light | 非默认才写 | 停靠主题；Designer.cs 生成配套 Theme 对象（VS2015Light→ThemeVS2015Light），改主题须同步改引用的 Theme 程序集 |
| TabDirection | TabTipDirection | Left | 非默认才写 | 选项卡提示方向（左/右），少量布局场景才改 |
| DockWindows | DockWindowItemCollection | Content 集合 | 停靠窗口声明集合，条目类型 DockWindowItem；生成走"三文件流程"（codegen.md §3） | |
| LayoutFileName | String | dock_layout.xml | 非默认才写 | 运行时布局持久化 XML 文件名，相对 exe 目录 |
继承属性（名称全列）
- 继承 DockPanel（33 个）：DockBackColor, ActiveAutoHideContent, AllowEndUserDocking, AllowEndUserNestedDocking, Contents(RO), RightToLeftLayout, ShowDocumentIcon, DocumentTabStripLocation, Extender(RO), DockPaneFactory(RO), FloatWindowFactory(RO), DockWindowFactory(RO), Panes(RO), DockArea(RO), DockBottomPortion, DockLeftPortion, DockRightPortion, DockTopPortion, DockWindows(RO), DocumentsCount(RO), Documents(RO), FloatWindows(RO), DefaultFloatWindowSize, DocumentStyle, SupportDeeplyNestedContent, ShowAutoHideContentOnHover, DocumentWindowBounds(RO), ActiveContent(RO), ActivePane(RO), ActiveDocument(RO), ActiveDocumentPane(RO), Skin(RO), Theme
- 继承 Panel（5 个）：AutoSize, AutoSizeMode, BorderStyle, TabStop, Text
- 继承 ScrollableControl（8 个）：AutoScroll, AutoScrollMargin, AutoScrollPosition, AutoScrollMinSize, DisplayRectangle(RO), HorizontalScroll(RO), VerticalScroll(RO), DockPadding(RO)
- 继承 Control（70 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
自有事件：无（仅基类事件）。
- 运行时错误 "DockPanel.Theme must be set to a valid theme" = 二级依赖链（System.Resources.Extensions 等 4 个）没引用全。
- 诊断日志：bin\Debug\DockWindows.Log.txt。
- API：EnsureDefaultTheme()（代码兜底挂主题）。
- 不可当作普通 Control 用（没有 Size/Location 语义），占满窗体或容器使用。
圆角按钮 RoundedButton
继承：Smart.CustomComponents.RoundedButton ← System.Windows.Forms.Control
Element-UI 配色的圆角按钮，8 种风格预设 + 三态（常态/悬停/按下）颜色可覆写。点击用基类 Click 事件。
属性（全部 9 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Style | RoundedButtonStyle | Primary | 非默认才写 | 风格预设 Primary/Success/Warning/Danger/Info/Dark/Light/Outline，Designer.cs 写英文名（如 RoundedButtonStyle.Success） |
| Radius | Int32 | 10 | 非默认才写 | 圆角半径 px，0=直角 |
| NormalColor | Color | — | 常态底色；出厂 24,144,255（随 Style 预设，ShouldSerialize 按出厂色比较） | |
| HoverColor | Color | — | 悬停底色；出厂 64,169,255 | |
| PressColor | Color | — | 按下底色；出厂 9,109,217 | |
| BorderWidth | Int32 | 0 | 非默认才写 | 边框宽 px，0=无边框（Outline 风格通常设 1~2） |
| BorderColor | Color | — | 边框色；出厂 217,217,217 | |
| TextAlign | ContentAlignment | MiddleCenter | 非默认才写 | 文字对齐（ContentAlignment），默认 MiddleCenter |
| BackColor | Color | 不序列化 | 被隐藏（自绘不用），绝不写 |
继承属性（名称全列）
- 继承 Control（73 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Text, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
自有事件：无（仅基类事件）。
- 三色只在改变出厂预设时序列化（ShouldSerialize 与出厂色比较）。
- 改色想完整自定义时三态色都要写，避免悬停跳回蓝色。
图片按钮 ImageButton
继承：Smart.CustomComponents.ImageButton ← System.Windows.Forms.Control
图片+文字的按钮。属性名与枚举值本身就是中文标识符，Designer.cs 直接写中文（全项目唯一例外）。
属性（全部 12 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| BackgroundImage | Image | 不序列化 | ||
| BackgroundImageLayout | ImageLayout | 不序列化 | ||
| BackColor | Color | 不序列化 | ||
| 图片路径 | String | — | 图片文件绝对/相对路径；非空才序列化（ShouldSerialize图片路径） | |
| 图片缩放 | 图片缩放模式 | Fit | 非默认才写 | Original/Fit/Stretch/Tile，默认 Fit |
| 图片锚点 | 图片锚点位置 | Center | 非默认才写 | Center/N/S/E/W，默认 Center |
| 图片透明度 | Double | 1 | 非默认才写 | 0.0~1.0，默认 1 |
| 图文布局 | 图文布局枚举 | 文字居中 | 非默认才写 | 文字居中/图下文上/图上文下/图右文左/图左文右/纯图片；枚举成员是中文 |
| 文字间距 | Int32 | 1 | 非默认才写 | 图与文字间距 px，默认 1 |
| Text | String | — | 按钮文字（类目 外观） | |
| Font | Font | — | 文字字体 | |
| ForeColor | Color | — | 文字颜色 |
继承属性（名称全列）
- 继承 Control（68 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
自有事件：无（仅基类事件）。
- Designer.cs 示例：this.imageButton1.图文布局 = Smart.CustomComponents.图文布局枚举.图左文右;
- 点击用基类 Click。
增强数据表格 EnhancedDataGridView
继承：Smart.CustomComponents.EnhancedDataGridView ← System.Windows.Forms.DataGridView
在标准 DataGridView 上增加：Excel 风格选择高亮、剪贴板多单元格粘贴、SQLite 三键绑定（x86 混合模式 System.Data.SQLite 1.0.119，无需 Interop.dll）。列仍用标准 Columns 序列化。
属性（全部 9 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| EnableExcelStyleSelection | Boolean | True | 非默认才写 | 列头/行头点击整列整行高亮 + 框选区域高亮，默认开 |
| EnableCellPaste | Boolean | False | 非默认才写 | 允许从 Excel 复制后粘贴多单元格，默认关 |
| SqliteDatabasePath | String | — | SQLite 数据库文件路径（.db）；相对路径相对 exe | |
| SqliteQuery | String | — | 绑定用的 SELECT 查询语句 | |
| AutoBindSqliteOnLoad | Boolean | False | 非默认才写 | 窗体载入时自动执行 BindSqliteData() |
| CreateTableButton | String | — | 设计时动作：属性面板点"…"按当前列生成建表 SQL/执行（值恒空，不序列化，绝不手写） | |
| BindDataButton | String | — | 设计时动作：点"…"立即按三件套绑定一次（值恒空，不序列化） | |
| ClearBindButton | String | — | 设计时动作：点"…"解除数据绑定（值恒空，不序列化） | |
| ColumnHeadersHeightSizeMode | DataGridViewColumnHeadersHeightSizeMode | EnableResizing | 非默认才写 | 遮蔽基类同名属性；默认 EnableResizing（表头可拖拽调高），与基类一致不用写 |
继承属性（名称全列）
- 继承 DataGridView（79 个）：AdjustedTopLeftHeaderBorderStyle(RO), AdvancedCellBorderStyle(RO), AdvancedColumnHeadersBorderStyle(RO), AdvancedRowHeadersBorderStyle(RO), AllowUserToAddRows, AllowUserToDeleteRows, AllowUserToOrderColumns, AllowUserToResizeColumns, AllowUserToResizeRows, AlternatingRowsDefaultCellStyle, AutoGenerateColumns, AutoSize, AutoSizeColumnsMode, AutoSizeRowsMode, BackColor, BackgroundColor, BackgroundImage, BackgroundImageLayout, BorderStyle, CellBorderStyle, ClipboardCopyMode, ColumnCount, ColumnHeadersBorderStyle, ColumnHeadersDefaultCellStyle, ColumnHeadersHeight, ColumnHeadersVisible, Columns(RO), CurrentCell, CurrentCellAddress(RO), CurrentRow(RO), DataMember, DataSource, DefaultCellStyle, DisplayRectangle(RO), EditMode, EditingControl(RO), EditingPanel(RO), EnableHeadersVisualStyles, FirstDisplayedCell, FirstDisplayedScrollingColumnHiddenWidth(RO), FirstDisplayedScrollingColumnIndex, FirstDisplayedScrollingRowIndex, ForeColor, Font, GridColor, HorizontalScrollingOffset, IsCurrentCellDirty(RO), IsCurrentCellInEditMode(RO), IsCurrentRowDirty(RO), MultiSelect, NewRowIndex(RO), Padding, ReadOnly, RowCount, RowHeadersBorderStyle, RowHeadersDefaultCellStyle, RowHeadersVisible, RowHeadersWidth, RowHeadersWidthSizeMode, Rows(RO), RowsDefaultCellStyle, RowTemplate, ScrollBars, SelectedCells(RO), SelectedColumns(RO), SelectedRows(RO), SelectionMode, ShowCellErrors, ShowCellToolTips, ShowEditingIcon, ShowRowErrors, SortedColumn(RO), SortOrder(RO), StandardTab, Text, TopLeftHeaderCell, UserSetCursor(RO), VerticalScrollingOffset(RO), VirtualMode
- 继承 Control（65 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), ImeMode
- 继承 Component（1 个）：Container(RO)
事件
自有事件：无（仅基类事件）。
- API：BindSqliteData()（按三件套绑定）；CreateSqliteTableFromColumns(dbPath, tableName, dropIfExists)（按列建表，返回 SQL）；PreviewCreateTableSql(tableName, dropIfExists)。
- Designer.cs 列走 DataGridViewColumn 序列化（DataGridViewTextBoxColumn 等），与本库无关。
- 排错：EDG.Ctor.Log.txt 记录"谁改了列高模式+调用栈"；属性面板改了不生效 → 查 Designer.cs 残留显式模式行 + HintPath 是否指向旧版 DLL。
多选下拉框 MultiSelectComboBox
继承：Smart.CustomComponents.MultiSelectComboBox ← System.Windows.Forms.Control
带勾选、可搜索、可自定义输入的多选下拉框，选中项渲染成 Token（标签）。
属性（全部 19 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Items | ComboBoxItemCollection | Content 集合 | 下拉项字符串集合（Content 集合，逐条生成） | |
| Text | String | — | 显示文本；运行时取已选用 SelectedItems/SelectedValues | |
| MultiSelect | Boolean | True | 非默认才写 | 允许多选（Token 叠加）；false 时单选 |
| AllowCustomInput | Boolean | False | 非默认才写 | 允许输入集合外自定义项 |
| Searchable | Boolean | True | 非默认才写 | 下拉内搜索框开关 |
| SelectedIndices | List | 不序列化 | ||
| SelectedValues | List | 不序列化 | ||
| SelectedItems | List | 不序列化 | ||
| SelectedText | String | 不序列化 | 隐藏，不序列化 | |
| MaxDropDownItems | Int32 | 8 | 非默认才写 | 下拉最大可见行数，默认 8 |
| DropDownWidth | Int32 | 0 | 非默认才写 | |
| DropDownHeight | Int32 | 0 | 非默认才写 | |
| DroppedDown | Boolean | 不序列化 | ||
| TokenBackColor | Color | — | Token 底色，出厂 64,158,255 | |
| TokenForeColor | Color | — | Token 文字色，出厂 White | |
| BorderColor | Color | — | 边框色，出厂 173,178,184 | |
| HoverBorderColor | Color | — | 悬停边框色，出厂 64,158,255 | |
| ArrowColor | Color | — | 箭头色，出厂 96,98,102 | |
| ArrowHoverColor | Color | — | 箭头悬停色，出厂 64,158,255 |
继承属性（名称全列）
- 继承 Control（73 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
| 事件 | 签名 |
|---|---|
| SelectedItemsChanged | EventHandler |
| DropDown | EventHandler |
| DropDownClosed | EventHandler |
| TextChangedEx | EventHandler |
- API：SelectIndex(i)/UnselectIndex(i)/ToggleIndex(i)/ClearSelection()/SelectAll()；ToggleDropDown()/OpenDropDown()/CloseDropDown()。
- 事件：SelectedItemsChanged、DropDown、DropDownClosed、TextChangedEx。
- 取值：selectedValues 属性（List）或 SelectedIndices。
可调高下拉框 ResizableComboBox
继承：Smart.CustomComponents.ResizableComboBox ← System.Windows.Forms.Control
高度可自由调整的下拉框（标准 ComboBox 高度锁死，这是它存在的意义）。下拉面板自绘，支持排序/整合高度。
属性（全部 17 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Items | ComboBoxItemCollection | Content 集合 | 下拉项字符串集合（Content 集合） | |
| Text | String | — | 当前显示文本 | |
| SelectedIndex | Int32 | -1 | 非默认才写 | 选中索引，默认 -1 |
| SelectedItem | Object | 不序列化 | 选中项（隐藏，运行时用） | |
| SelectedText | String | 不序列化 | 隐藏，不序列化 | |
| DropDownStyle | ComboBoxStyle | DropDownList | 非默认才写 | DropDownList（只可选）/DropDown（可输入），默认 DropDownList |
| MaxDropDownItems | Int32 | 8 | 非默认才写 | 默认 8 |
| DropDownWidth | Int32 | 0 | 非默认才写 | |
| DropDownHeight | Int32 | 0 | 非默认才写 | |
| IntegralHeight | Boolean | True | 非默认才写 | 行高取整，默认 true |
| Sorted | Boolean | False | 非默认才写 | 自动排序，默认 false |
| Flat | Boolean | False | 非默认才写 | 扁平外观开关 |
| BorderColor | Color | — | 出厂 173,178,184 | |
| HoverBorderColor | Color | — | 出厂 64,158,255 | |
| ArrowColor | Color | — | 出厂 96,98,102 | |
| ArrowHoverColor | Color | — | 出厂 64,158,255 | |
| DroppedDown | Boolean | 不序列化 | 只读状态 |
继承属性（名称全列）
- 继承 Control（73 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
| 事件 | 签名 |
|---|---|
| SelectedIndexChanged | EventHandler |
| SelectedValueChanged | EventHandler |
| DropDown | EventHandler |
| DropDownClosed | EventHandler |
| TextChangedEx | EventHandler |
- API：ToggleDropDown()/OpenDropDown()/CloseDropDown()。
- 事件：SelectedIndexChanged、SelectedValueChanged、DropDown、DropDownClosed、TextChangedEx。
- Designer.cs 里 SelectedText 绝不写。
可调高文本框 ResizableTextBox
继承：Smart.CustomComponents.ResizableTextBox ← System.Windows.Forms.Control
高度可自由调整的单行文本框，带占位提示与三态边框色（常态/悬停/聚焦）。
属性（全部 15 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Text | String | — | 文本内容 | |
| MaxLength | Int32 | 32767 | 非默认才写 | 最大长度，默认 32767 |
| ReadOnly | Boolean | False | 非默认才写 | 只读 |
| CharacterCasing | CharacterCasing | Normal | 非默认才写 | 大小写转换，默认 Normal |
| PasswordChar | Char | \0（不掩码，写法 \0） | 非默认才写 | 密码掩码字符，默认 \0（不掩码） |
| TextAlign | HorizontalAlignment | Left | 非默认才写 | Left/Center/Right，默认 Left |
| PlaceholderText | String | — | 占位提示文字 | |
| Flat | Boolean | False | 非默认才写 | 扁平外观（去圆角） |
| BorderColor | Color | — | 常态边框色，出厂 173,178,184 | |
| HoverBorderColor | Color | — | 悬停边框色，出厂 64,158,255 | |
| FocusBorderColor | Color | — | 聚焦边框色，出厂 64,158,255 | |
| PlaceholderColor | Color | — | 占位文字色，出厂 192,196,206 | |
| SelectionStart | Int32 | 不序列化 | ||
| SelectionLength | Int32 | 不序列化 | ||
| SelectedText | String | 不序列化 |
继承属性（名称全列）
- 继承 Control（73 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
| 事件 | 签名 |
|---|---|
| TextChanged | EventHandler |
- 事件：TextChanged（基类）。
- API：SelectAll()、Select(start, length)。
OK/NG 状态灯 OKNGStatusControl
继承：Smart.CustomComponents.OKNGStatusControl ← System.Windows.Forms.Control
圆形 OK(绿)/NG(红) 状态灯，可绑定变量名由变量系统驱动。
属性（全部 2 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| BindVariable | String | — | 绑定的变量名（变量绑定编辑器选择） | |
| IsOK | Boolean | — | true=OK(绿)，false=NG(红)；源码初始值 true |
继承属性（名称全列）
- 继承 Control（74 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Text, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
自有事件：无（仅基类事件）。
- 绝不写 Text（自绘覆盖文字）。
- 运行时 this.okngStatusControl1.IsOK = false; 切红灯。
侧边菜单 SideMenuPanel
继承：Smart.CustomComponents.SideMenuPanel ← System.Windows.Forms.UserControl
折叠式侧边菜单 + 内容页面：MenuItems 声明菜单树（可递归子项），Pages 声明页面（MenuKey 关联菜单项），点击菜单自动切页。
属性（全部 19 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| MenuItems | BindingList | Content 集合 | 菜单项集合（Content，条目 SideMenuItem 可递归 Children） | |
| Pages | BindingList | Content 集合 | 页面集合（Content，条目 SideMenuPage : Panel，设计器里页面字段名 sideMenuPageN） | |
| ActivePage | SideMenuPage | 不序列化 | 当前页（只读，隐藏） | |
| MenuWidth | Int32 | 160 | 非默认才写 | 菜单宽 px，默认 160 |
| MenuCollapsed | Boolean | False | 非默认才写 | 折叠菜单，默认 false |
| ItemHeight | Int32 | 34 | 非默认才写 | 菜单行高 px，默认 34 |
| Indent | Int32 | 18 | 非默认才写 | 子级缩进 px，默认 18 |
| IconSize | Int32 | 18 | 非默认才写 | 图标尺寸 px，默认 18 |
| ShowIcons | Boolean | True | 非默认才写 | 显示图标，默认 true |
| MenuBackColor | Color | — | 出厂 White | |
| MenuForeColor | Color | — | 出厂 80,80,80 | |
| SelectedColor | Color | — | 选中底色，出厂 230,247,255 | |
| SelectedForeColor | Color | — | 选中文字色，出厂 24,144,255 | |
| HoverColor | Color | — | 悬停底色，出厂 245,245,245 | |
| ArrowColor | Color | — | 展开箭头色，出厂 150,150,150 | |
| SplitterColor | Color | — | 菜单/内容分隔线色，出厂 235,235,235 | |
| ContentPanel | SideMenuContentPanel | 不序列化 | 内容容器（只读，隐藏；运行时向它加控件） | |
| SelectedNode | SideMenuItem | 不序列化 | 当前选中菜单项（隐藏） | |
| ForeColor | Color | 不序列化 | 隐藏（用 MenuForeColor 系列代替） |
继承属性（名称全列）
- 继承 UserControl（5 个）：AutoSize, AutoSizeMode, AutoValidate, BorderStyle, Text
- 继承 ContainerControl（6 个）：AutoScaleDimensions, AutoScaleMode, BindingContext, ActiveControl, CurrentAutoScaleDimensions(RO), ParentForm(RO)
- 继承 ScrollableControl（8 个）：AutoScroll, AutoScrollMargin, AutoScrollPosition, AutoScrollMinSize, DisplayRectangle(RO), HorizontalScroll(RO), VerticalScroll(RO), DockPadding(RO)
- 继承 Control（69 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
| 事件 | 签名 |
|---|---|
| SelectedNodeChanged | EventHandler< |
- API：SelectNode(SideMenuItem)、ShowPage(string key)、CanDropAt(Point)、GetActiveDropTarget()。
- 事件：SelectedNodeChanged（参数 SelectedNodeChangedEventArgs.Node）。
- 设计期默认集合内容只能在 Designer.Initialize 且 !host.Loading 时注入——绝不写进构造函数（会运行时翻倍）。
功能区 RibbonStrip
继承：Smart.CustomComponents.RibbonStrip ← System.Windows.Forms.UserControl
Excel 风格功能区：Tabs（选项卡）→ Groups（分组）→ Buttons（按钮）三层集合。设计器支持拖拽重排按钮、双击选项卡改名；点击按钮在运行时统一走 ButtonClick 事件。
属性（全部 10 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Tabs | BindingList | Content 集合 | 选项卡集合（Content，条目 RibbonTab.Groups→RibbonGroup.Buttons→RibbonButton） | |
| ActiveTabIndex | Int32 | 0 | 非默认才写 | 当前选项卡索引，默认 0 |
| ActiveTab | RibbonTab | 不序列化 | 当前选项卡（只读，隐藏） | |
| AccentColor | Color | A=255, R=33, G=115, B=70 | 非默认才写 | 主题强调色（选中选项卡下划线等），出厂 33,115,70（Excel 绿） |
| TabBarColor | Color | A=255, R=243, G=242, B=241 | 非默认才写 | 选项卡条底色，出厂 243,242,241 |
| ContentColor | Color | White | 非默认才写 | 内容区底色，出厂 White |
| SeparatorColor | Color | A=255, R=180, G=180, B=180 | 非默认才写 | 组分隔线色，出厂 180,180,180 |
| ForeColor | Color | 不序列化 | 隐藏（组名/文字色内部固定） | |
| BackgroundImage | Image | 不序列化 | ||
| BackgroundImageLayout | ImageLayout | 不序列化 |
继承属性（名称全列）
- 继承 UserControl（5 个）：AutoSize, AutoSizeMode, AutoValidate, BorderStyle, Text
- 继承 ContainerControl（6 个）：AutoScaleDimensions, AutoScaleMode, BindingContext, ActiveControl, CurrentAutoScaleDimensions(RO), ParentForm(RO)
- 继承 ScrollableControl（8 个）：AutoScroll, AutoScrollMargin, AutoScrollPosition, AutoScrollMinSize, DisplayRectangle(RO), HorizontalScroll(RO), VerticalScroll(RO), DockPadding(RO)
- 继承 Control（67 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BackColor, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
| 事件 | 签名 |
|---|---|
| ButtonClick | EventHandler< |
- 事件：ButtonClick(object sender, RibbonButtonEventArgs e)；e.Tab/e.Group/e.Button 分别为所在选项卡/分组/按钮（用 e.Button.Text 分发）。
- 图标：RibbonButton.Image 序列化为
buttonN.Image = RibbonButton.FromFile("路径")（有来源路径时；ImageFile 属性本身隐藏）。 - Designer.cs 生成规则（三层 Content 集合）见 codegen.md §2.5。
变量显示标签 VariableDisplayLabel
继承：Smart.CustomComponents.VariableDisplayLabel ← System.Windows.Forms.Control
只读展示绑定变量当前值的标签，值变化触发 ValueChanged。
属性（全部 3 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| BindVariable | String | — | 绑定的变量名（变量绑定编辑器选择） | |
| DisplayValue | String | — | 当前显示值，默认 "——"（运行时由变量系统刷新） | |
| TextAlign | ContentAlignment | MiddleLeft | 非默认才写 | ContentAlignment，默认 MiddleLeft |
继承属性（名称全列）
- 继承 Control（74 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Text, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
- 继承 Component（1 个）：Container(RO)
事件
| 事件 | 签名 |
|---|---|
| ValueChanged | EventHandler |
- 只读控件：不接受输入（PreProcessMessage 恒 false）。
- ⚠ 没有 BorderStyle（继承 Control 不是 Label，s23 案例抄错即设计器中止加载）；要边框容器就用 Panel/GroupBox 包一层。
- 事件：ValueChanged。
变量编辑框 VariableEditTextBox
继承：Smart.CustomComponents.VariableEditTextBox ← System.Windows.Forms.TextBox
标准 TextBox + 变量绑定：BindVariable 指向变量，Value 与 Text 同步。
属性（全部 2 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| BindVariable | String | — | 绑定的变量名（变量绑定编辑器选择） | |
| Value | String | 不序列化 | 与 Text 同步的镜像值（隐藏，不序列化） |
继承属性（名称全列）
- 继承 TextBox（11 个）：AcceptsReturn, AutoCompleteMode, AutoCompleteSource, AutoCompleteCustomSource, CharacterCasing, Multiline, PasswordChar, ScrollBars, Text, TextAlign, UseSystemPasswordChar
- 继承 TextBoxBase（21 个）：AcceptsTab, ShortcutsEnabled, AutoSize, BackColor, BackgroundImage, BackgroundImageLayout, BorderStyle, CanUndo(RO), ForeColor, HideSelection, Lines, MaxLength, Modified, Padding, PreferredHeight(RO), ReadOnly, SelectedText, SelectionLength, SelectionStart, TextLength(RO), WordWrap
- 继承 Control（67 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), ImeMode
- 继承 Component（1 个）：Container(RO)
事件
自有事件：无（仅基类事件）。
- 其余全部属性/事件与标准 TextBox 一致（Text/Multiline/PasswordChar/TextChanged…见 winforms-controls.md#TextBox）。
- Designer.cs 只需写 BindVariable 与常用 TextBox 属性。
- ⚠ 没有 PlaceholderText（那是 ResizableTextBox 的自有属性，s23 案例抄错即设计器中止加载）；要占位提示就用 ResizableTextBox。
日志记录器 Logger（非可视组件）
继承：Smart.CustomComponents.Logger ← System.ComponentModel.Component
拖到窗体托盘的日志组件，代码里直接调中文方法写日志。
属性（全部 4 个自有属性）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| 日志文件名 | String | logs\app.log | 非默认才写 | 日志文件路径，默认 logs\app.log |
| 日志级别 | 日志级别枚举 | 信息 | 非默认才写 | 调试/信息/警告/错误/致命，默认 信息 |
| 按天滚动 | Boolean | True | 非默认才写 | 按日期滚动文件，默认 true |
| 最多保留份数 | Int32 | 30 | 非默认才写 | 滚动保留份数，默认 30 |
继承属性（名称全列）
- 继承 Component（2 个）：Site, Container(RO)
事件
自有事件：无（仅基类事件）。
- API：写调试(msg)/写信息(msg)/写警告(msg)/写错误(msg)/写异常(msg, ex)；设计模式下调用是空操作。
- 事件：无（仅 Disposed）。
Content 集合条目类型（全部属性）
DockWindowItem（DockSurface.DockWindows 的条目）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| ClassName | String | DockWindow | 非默认才写 | |
| Title | String | 停靠窗口 | 非默认才写 | |
| PersistString | String | 不序列化 | ||
| DockState | DockState | DockLeft | 非默认才写 | |
| DefaultWidth | Int32 | 220 | 非默认才写 | |
| DefaultHeight | Int32 | 180 | 非默认才写 | |
| FixedPosition | Boolean | False | 非默认才写 | |
| ShowCloseButton | Boolean | True | 非默认才写 | |
| ContentXml | String | 不序列化 | ||
| ColumnsXml | String | 不序列化 | ||
| SourceFile | String | 不序列化 | ||
| HasContent | Boolean | 不序列化 |
- Hidden 属性（PersistString/ContentXml/ColumnsXml/SourceFile）由三文件生成器消费，绝不手写。
- HasContent 只读，指示是否已挂窗口内容。
SideMenuItem（SideMenuPanel.MenuItems 的条目）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Text | String | — | ||
| Icon | Image | — | ||
| IsExpanded | Boolean | False | 非默认才写 | |
| Children | BindingList | Content 集合 |
- Children 可递归嵌套子菜单（Content 集合）。
SideMenuPage（SideMenuPanel.Pages 的条目）: Panel
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| MenuKey | String | — |
- MenuKey 与某个菜单项对应（点击该菜单项显示本页）；其余属性同 Panel。
RibbonTab（RibbonStrip.Tabs 的条目）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Text | String | — | ||
| Groups | BindingList | Content 集合 |
- Groups 为分组集合（Content）。
RibbonGroup（RibbonTab.Groups 的条目）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Text | String | — | ||
| Buttons | BindingList | Content 集合 |
- Buttons 为按钮集合（Content）。
RibbonButton（RibbonGroup.Buttons 的条目）
| 属性 | 类型 | 默认值 | 序列化 | 说明 |
|---|---|---|---|---|
| Name | String | — | ||
| ImageFile | String | 不序列化 | ||
| Image | Image | — | ||
| Text | String | — | ||
| SizeStyle | RibbonButtonSize | Small | 非默认才写 | |
| Enabled | Boolean | True | 非默认才写 |
- Image 有路径时序列化为
= RibbonButton.FromFile("路径")；ImageFile 本身隐藏。 - Name 用于设计器标识；运行时分发用 Text。
枚举全值表（Designer.cs 一律写英文标识符，ImageButton 枚举例外——本身就是中文）
RoundedButtonStyle：Primary=0、Success=1、Warning=2、Danger=3、Info=4、Dark=5、Light=6、Outline=7
Smart.CustomComponents.DockSurface+SurfaceTheme：VS2015Light=0、VS2015Blue=1、VS2015Dark=2、VS2013Light=3、VS2013Blue=4、VS2013Dark=5、VS2012Light=6、VS2005=7、VS2003=8、Default=9
Smart.CustomComponents.DockSurface+TabTipDirection：Left=0、Right=1
RibbonButtonSize：Large=0、Small=1
日志级别枚举：调试=0、信息=1、警告=2、错误=3、致命=4
图片锚点位置：Center=0、N=1、S=2、E=3、W=4
图片缩放模式：Original=0、Fit=1、Stretch=2、Tile=3
图文布局枚举：文字居中=0、图下文上=1、图上文下=2、图右文左=3、图左文右=4、纯图片=5
DockState 枚举（DockWindowItem.DockState 用，WeifenLuo）
值：Unknown、Float、DockTop、DockBottom、DockLeft、DockRight、Document、Hidden（常用：DockLeft/DockRight/DockBottom/Document/Float）。
共享基类属性速览
大多数增强控件继承 System.Windows.Forms.Control；Control 基类全部 73 个属性（含默认值）的完整表格见 winforms-controls.md 第 0 节"Control 基类属性总表"，此处不重复。