# StellarX GUI Framework API Documentation （中英双语） ## CoreTypes（基础类型） **CoreTypes** 模块定义了 StellarX 框架中使用的所有基础枚举和结构体类型，以确保类型一致性（Core types module defines all fundamental enums and structs used in the StellarX framework to ensure type consistency）。主要包括以下内容： - **FillStyle（填充图案样式）**：定义控件填充图案的枚举类型。例如 Horizontal 表示水平线填充，Vertical 表示垂直线，FDiagonal 表示反斜线，BDiagonal 表示正斜线，Cross 表示十字，DiagCross 表示网格。（Defines patterns for filling control backgrounds. For example, Horizontal for horizontal lines, Vertical for vertical lines, FDiagonal for forward diagonal lines, BDiagonal for backward diagonal lines, Cross for crosshatch, DiagCross for grid pattern.）默认填充图案为水平线 (The default pattern is horizontal line)。 - **FillMode（填充模式）**：定义控件背景的填充模式，包括纯色、无填充、图案填充、自定义图案、自定义图片填充等。（Defines how control backgrounds are filled: solid color, no fill, hatched pattern, custom pattern, or custom image fill, etc.）例如 Solid（固实填充），Null（不填充），Hatched（图案填充），Pattern（自定义图案），DibPattern（自定义图像）。默认填充模式为 Solid 固实填充 (default is solid fill)。 - **LineStyle（线型样式）**：定义控件边框的线型风格枚举。例如 Solid 表示实线，Dash 表示虚线，Dot 表示点线，DashDot 表示点划线，DashDotDot 表示双点划线，Null 表示无边框线。（Defines line style for control borders. For example, Solid for solid line, Dash for dashed line, Dot for dotted line, DashDot for dash-dot line, DashDotDot for double dash-dot, Null for no border line.）默认边框线型为实线 (default line style is solid)。 - **ControlShape（控件形状）**：定义控件的几何形状类型，共提供矩形、圆角矩形、圆形、椭圆，每种形状分别有“有边框”和“无边框”两种版本。（Enumerates geometric shape types for controls: rectangle, rounded rectangle, circle, and ellipse – each in bordered and borderless variants.）例如 RECTANGLE（有边框矩形）、B_RECTANGLE（无边框矩形）、ROUND_RECTANGLE（有边框圆角矩形）、B_ROUND_RECTANGLE（无边框圆角矩形）、CIRCLE（有边框圆形）、B_CIRCLE（无边框圆形）、ELLIPSE（有边框椭圆）、B_ELLIPSE（无边框椭圆）。按钮类支持所有形状，而某些控件可能只支持部分形状（Button supports all shapes, while some controls only support a subset of shapes）。 - **TextBoxmode（文本框模式）**：定义文本框控件的工作模式枚举，包括 `INPUT_MODE`（用户可输入模式）、`READONLY_MODE`（只读模式）和 `PASSWORD_MODE`（密码模式）。这允许设置文本框是否可输入、仅显示或以密码形式显示。（Defines the operating mode of a TextBox control: `INPUT_MODE` for editable text input, `READONLY_MODE` for read-only display, and `PASSWORD_MODE` for password input mode, allowing configuration of whether the text box accepts input or is display-only or masked as password input.） - **ButtonMode（按钮模式）**：定义按钮控件的工作模式枚举，包括 `NORMAL`（普通模式）、`TOGGLE`（切换模式）和 `DISABLED`（禁用模式）。普通模式下按钮每次点击触发回调但不保持状态；切换模式下按钮在选中/未选中之间切换，并触发不同回调；禁用模式下按钮不可点击，显示灰化且文本带删除线。（Defines the working mode of a Button: `NORMAL` mode triggers a callback on each click without maintaining state; `TOGGLE` mode toggles between pressed and unpressed states and triggers different callbacks for each; `DISABLED` mode makes the button non-clickable, typically grayed out with strikethrough text to indicate disabled state.） - **MessageBoxType（消息框类型）**：枚举标准消息框的按钮组合类型，包括 OK（只有“确定”按钮）、OKCancel（“确定”和“取消”）、YesNo（“是”和“否”）、YesNoCancel（“是”“否”“取消”）、RetryCancel（“重试”和“取消”）、AbortRetryIgnore（“中止”“重试”“忽略”）等类型。（Enumerates the standard combinations of buttons for a message box: e.g., OK (OK button only), OKCancel (OK and Cancel), YesNo, YesNoCancel, RetryCancel, AbortRetryIgnore, etc.）开发者可根据需要选择消息框包含的按钮组合 (Developers can select the appropriate set of buttons for the message box as needed)。 - **MessageBoxResult（消息框结果）**：枚举消息框的返回结果类型，与 MessageBoxType 相对应，包括 OK（确定）、Cancel（取消）、Yes（是）、No（否）、Abort（中止）、Retry（重试）、Ignore（忽略）等。（Enumerates the possible results of a message box, corresponding to which button was pressed: OK, Cancel, Yes, No, Abort, Retry, Ignore, etc.）模态消息框会返回这些枚举值表示用户选择 (Modal message boxes return one of these values to indicate the user's choice)。 - **LayoutMode（布局模式）**：定义窗口拉伸时控件的布局策略，包括 `Fixed`（固定布局）和 `AnchorToEdges`（锚定布局）。（Defines how controls behave when the window is resized: `Fixed` for no resizing (controls maintain their size/position), and `AnchorToEdges` for anchoring controls to container edges so they stretch or move accordingly.）通过 **Control** 的接口可以设置控件的布局模式 (The layout mode for a control can be set via the **Control** class’s interface)。 - **Anchor（锚点位置）**：定义控件相对于父窗口的锚定边缘位置，用于 AnchorToEdges 布局模式。包括 Left（左锚定）、Right（右锚定）、Top（上锚定）、Bottom（下锚定）以及 NoAnchor（不锚定）。可以组合两个锚点来固定控件的两个方向。（Defines which edges of the parent container a control is anchored to (used when layout mode is AnchorToEdges). Options include Left, Right, Top, Bottom, plus NoAnchor for no anchoring. Two anchors (horizontal and vertical) are typically used together to lock the control’s position in both directions.） - **TabPlacement（选项卡位置）**：定义 TabControl 选项卡标签栏的位置，包括 Top（页签在顶部）、Bottom（在底部）、Left（在左侧）、Right（在右侧）。选择不同值会将选项卡的标签（按钮）放置在容器的不同边缘。（Defines the placement of the tab headers in a TabControl: Top, Bottom, Left, or Right. The chosen value determines on which edge of the TabControl the tab buttons are displayed.） - **RouRectangle（圆角矩形参数）**：用于定义控件圆角矩形形状时圆角的椭圆尺寸的结构体。包含两个整数成员 ROUND_RECTANGLEwidth 和 ROUND_RECTANGLEheight，默认值均为 20，表示圆角矩形拐角处椭圆的宽度和高度。（A struct defining the ellipse size of the corners for rounded rectangle shapes. It has two int members, ROUND_RECTANGLEwidth and ROUND_RECTANGLEheight (both default to 20), which represent the width and height of the ellipse used for the rounded corners of a rectangle.）通过修改这个结构体，可以调整控件圆角的弧度 (By modifying these values, one can adjust the curvature of a control’s rounded corners). - **ControlText（控件文本样式）**：定义控件字体和文本颜色样式的结构体。它包含多个字段用于描述文本外观： - `nHeight`：字体高度（像素值）(font height in pixels) - `nWidth`：字体宽度（像素值，如果为0则自动适配高度）(font width in pixels; 0 means auto-adjust to height) - `lpszFace`：字体名称，默认“微软雅黑” (font face name, default is "微软雅黑" font) - `color`：文字颜色，默认黑色 (text color, default RGB(0,0,0) black) - `nEscapement`：字符串整体旋转角度（单位0.1度，如900表示90度）(text escapement angle for the entire string, in tenths of degrees, e.g., 900 means 90°) - `nOrientation`：单个字符旋转角度（单位0.1度）(orientation angle of individual characters, also in tenths of degrees) - `nWeight`：字体粗细(字重)，0表示默认，范围0~1000 (font weight/thickness, 0 means default; range 0~1000) - `bItalic`：是否斜体 (italic flag) - `bUnderline`：是否下划线 (underline flag) - `bStrikeOut`：是否删除线 (strikethrough flag) 此结构可用于控件的文本样式自定义，如 **Button**、**Label** 等控件都有 `textStyle` 成员使用该结构。（This struct is used to customize text appearance for controls. For example, **Button**, **Label**, etc., include a `textStyle` member of this type to specify font and text style.） ## Control（控件基类） **类名**：`Control` **中文简要说明**：所有控件的抽象基类，定义通用接口和基础功能，不直接实例化。（*Abstract base class for all UI controls, defining common interfaces and fundamental functionality. It is not meant to be instantiated directly*。） **继承关系**：无（Control 为顶级基类）(None. Control is the top-level base class for all controls). **功能摘要**: Control 提供控件的基本属性（如位置、尺寸）和通用方法，并实现绘图状态保存/恢复机制，确保控件绘制不影响全局状态。它还声明了一些纯虚方法供子类实现，例如 `draw()` 和 `handleEvent()`。（*The Control class provides basic properties (position, size, visibility) and common methods for controls. It implements mechanisms for saving and restoring drawing state to ensure control rendering does not disturb global graphics state. It also declares abstract methods like `draw()` and `handleEvent()` that subclasses must implement.*） **公共方法 (Public Methods)**： - `draw()` – **纯虚函数**，由子类实现，用于绘制控件内容 (pure virtual; draws the control’s appearance, implemented by each concrete control subclass). - `bool handleEvent(const ExMessage& msg)` – **纯虚函数**，由子类实现，处理输入事件消息，返回事件是否被控件消费 (pure virtual; handles input events for the control and returns true if the event is consumed)。 - `void setIsVisible(bool show)` – 设置控件的可见性。传入 `false` 将隐藏控件，`true` 将显示控件。默认实现改变内部 `show` 状态并将控件标记为需要重绘 (Sets the control’s visibility. False to hide the control, true to show it. The base implementation updates the internal `show` flag and marks the control as needing redraw)。**（说明**：某些复合控件会重载此方法以同步子控件，例如 **TabControl** 对该方法进行了重载，实现显示/隐藏所有选项卡页) (Note: Some composite controls override this to also affect their children – e.g. **TabControl** overrides setIsVisible to show/hide all tab pages). - `void setDirty(bool dirty)` – 将控件标记为“脏”，表示需要重绘 (Marks the control as dirty, i.e., requiring a redraw). 默认实现设置内部标志，并**对容器控件**会将所有子控件一起标记 (Base implementation sets the internal flag; container controls like Canvas also mark child controls dirty). - `void setParent(Control* parent)` – 设置控件的父容器指针 (Assigns a parent control container to this control). 用于建立控件层次关系 (Used to establish parent-child relationship for nested controls). - `bool IsVisible() const` – 返回控件当前是否处于可见状态 (Checks if the control is currently set to be visible). - `std::string getId() const` – 获取控件的标识字符串ID (Returns the string identifier of the control). - `bool isDirty() const` – 判断控件是否被标记为需要重绘 (Returns whether the control is marked as dirty (needing redraw)). - `void setX(int x), setY(int y)` – 设置控件左上角的位置坐标 (Sets the control’s top-left position). 基类实现更新位置并将控件标记为脏，需要重绘 (Base implementation updates the coordinate and marks the control dirty)。某些容器控件（如 **Canvas**）会重载这些方法，以便在移动自身时同步更新子控件位置 (Some container controls like **Canvas** override these to also adjust children’s positions when the container moves). - `void setWidth(int w), setHeight(int h)` – 设置控件尺寸宽度和高度 (Sets the control’s width and height). 基类实现更新尺寸并将控件标记为需要重绘 (Base implementation updates the size and marks the control dirty)。 - `int getX() const, getY() const, getWidth() const, getHeight() const` – 获取控件当前的全局坐标位置及宽高 (Returns the control’s current absolute X, Y coordinates and its width and height)。 - `int getRight() const, getBottom() const` – 获取控件右边缘和下边缘的全局坐标 (Returns the coordinate of the control’s right edge (x+width) and bottom edge (y+height)). - `int getLocalX() const, getLocalY() const, getLocalWidth() const, getLocalHeight() const` – 获取控件相对于父容器的坐标和尺寸 (Returns the control’s position and size in its parent’s local coordinate space). - `int getLocalRight() const, getLocalBottom() const` – 获取控件右边缘和下边缘相对于父容器坐标系的位置 (Returns the local-space coordinates of the control’s right and bottom edges). - **布局相关方法 (Layout-related)**: - `void setLayoutMode(StellarX::LayoutMode mode)` – 设置控件的布局模式，如固定或锚定布局 (Sets the control’s layout mode (e.g., Fixed or AnchorToEdges)). 基类存储所选模式，窗口大小变化时会参考此设置调整控件 (The base class stores the mode; on window resize, this informs how the control should adjust, if at all). - `void setAnchor(StellarX::Anchor anchor1, StellarX::Anchor anchor2)` – 设置控件在锚定布局模式下的水平和垂直锚点 (Sets the horizontal and vertical anchor positions for AnchorToEdges layout mode). 例如可以将控件锚定在左上（Top+Left）以保持与窗口左上角的距离不变 (For example, anchoring Top+Left keeps the control’s top-left distance to the container constant). - `StellarX::Anchor getAnchor_1() const, getAnchor_2() const` – 获取当前设置的水平和垂直锚点值 (Returns the currently configured primary and secondary anchor). - `StellarX::LayoutMode getLayoutMode() const` – 获取当前布局模式 (Gets the current layout mode). - `void onWindowResize()` – 虚函数，窗口尺寸变化时由系统或父容器调用，用于让控件丢弃过期的背景缓存并适应新尺寸。基类实现默认丢弃背景快照并标记控件为脏，需要重绘 (Virtual function called when the window or parent container is resized. The base implementation discards any saved background snapshot and marks the control dirty for redraw)。大多数控件使用基类行为，但容器控件会在重载中调整子控件布局 (Most controls use the base behavior, but container controls override this to adjust child layouts). - **其他方法 (Other methods)**: - `void updateBackground()` – 主动释放旧背景快照并重新保存当前背景，用于在控件尺寸变化后更新缓存以防止显示错位。调用该方法会抓取控件当前位置的新背景 (This forces the control to discard any old background image and capture a new background snapshot, typically used after resizing to avoid misalignment of cached content). - `virtual bool model() const = 0` – **纯虚函数**，用于对话框控件检查自身是否为模态。非对话框类可实现为简单返回 false。（*Pure virtual function to indicate if the control is a modal dialog. Non-dialog controls implement this to always return false; only dialog-related classes override it to reflect modal state*）. **保护方法 (Protected Methods)**：*(通常供控件内部或子类使用)* - `void requestRepaint(Control* parent)` – 向上请求父容器重绘。本控件或其子控件需要重绘时调用，遍历到最顶层容器触发实际重绘。基础实现为：如果存在父容器则递归通知父容器重绘，否则（无父，已到窗口根）调用 `onRequestRepaintAsRoot()` (Requests the parent to schedule a repaint of this control. Called when this control (or one of its children) becomes dirty and needs redraw. The base implementation propagates the request up the chain: if a parent exists, call parent’s requestRepaint, otherwise if at the root, call `onRequestRepaintAsRoot()` to trigger a top-level redraw). - `void onRequestRepaintAsRoot()` – 当控件是最顶层且需要重绘时，由框架调用以执行实际的刷新动作。典型实现是在窗口事件循环中检测到需要重绘时调用 (Called when the control is the root (no parent) and a repaint has been requested, to perform the actual redraw. In practice, the framework calls this during the window’s event loop when it detects a repaint is needed). - `void saveBackground(int x, int y, int w, int h)` – 保存控件区域在屏幕上的背景图像快照，用于实现擦除重绘时不留下残影。在控件首次绘制或移动/隐藏时抓取其背景 (Saves a snapshot of the background under the control’s area (at position x,y with size w×h) to facilitate restoring the background when the control is moved or removed, preventing ghosting artifacts). - `void restBackground()` – 恢复先前保存的背景快照，将其绘制回控件区域，从而擦除控件上一次绘制的内容。(Restores the previously saved background image to the control’s area, effectively erasing the control’s last drawn appearance. Typically used at the start of a redraw to clear old content.) - `void discardBackground()` – 丢弃并释放当前保存的背景快照。当控件或窗口尺寸变化、控件销毁时需要调用以防止使用失效的背景缓存。(Discards the stored background snapshot (if any). Called when the control or window size changes, or when the control is destroyed, to avoid using an outdated background cache.) - `void saveStyle()` / `void restoreStyle()` – 保存当前全局绘图状态（颜色、线型、填充等）并在绘制完成后恢复，以防止控件绘制改变全局状态。Control 基类实现了对 EasyX 图形状态的保存和恢复，每个控件在 `draw()` 开始时应调用 `saveStyle()`，结束时调用 `restoreStyle()` (Saves the current global drawing state (colors, line style, fill style, etc.) and restores it after drawing, to ensure the control’s drawing doesn’t alter the global state. The Control base provides these to wrap drawing code: call `saveStyle()` at the start of `draw()`, and `restoreStyle()` at the end). **成员变量 (Member Variables)** *(除特殊说明外，均为 `protected` 访问权限 — Protected unless otherwise noted)*： - `std::string id` – 控件的字符串ID标识符 (String identifier for the control). 可能用于调试或控件查找 (Often used for debugging or identifying controls). - `int x, y` – 控件左上角的**全局**坐标 (X and Y coordinates of the control’s top-left corner in the **global (window) coordinate space**). - `int width, height` – 控件当前的宽度和高度 (Current width and height of the control). - `int localx, localy` – 控件左上角相对于父控件的局部坐标 (Local X, Y position relative to its parent control’s origin). 对于顶级控件（如窗口直接子控件），local 坐标通常与全局相同 (For top-level controls (children of the window), local coordinates are typically the same as global). - `int localWidth, localHeight` – 控件在父容器坐标系下的尺寸大小 (Width and height of the control in the parent’s coordinate system). 初始化时等于控件自身宽高，但在父容器缩放或布局时可能用于计算 (Initialized to the control’s own width/height; used in layout calculations if needed). - `Control* parent` – 父控件指针 (Pointer to the parent control). 为 `nullptr` 则表示本控件无父（可能是顶层元素）(If `nullptr`, this control has no parent, i.e., it’s a root element). - `bool dirty` – 控件重绘标记。如果为 true 表示控件内容已改变或无效，需要在下一个周期重新绘制 (Dirty flag indicating the control needs to be redrawn. True means the control’s content has changed or invalidated and should be redrawn on the next cycle). 绘制完成后通常将 dirty 重置为 false (After drawing, this is reset to false until something changes again). - `bool show` – 控件可见性标志。true 表示控件应显示，false 则控件被隐藏，绘制时应跳过 (Visibility flag: true if the control should be visible, false if hidden. Hidden controls are skipped during rendering). - **布局属性 (Layout-related)**: - `StellarX::LayoutMode layoutMode` – 控件的布局模式（Fixed 或 AnchorToEdges），决定窗口大小变化时的位置调整策略 (Specifies the control’s layout mode (Fixed or AnchorToEdges), determining how it behaves when the window is resized). 默认为 Fixed 固定布局。 - `StellarX::Anchor anchor_1, anchor_2` – 控件相对父容器的锚点设置（如 Top/Bottom/Left/Right）。当 layoutMode 为 AnchorToEdges 时使用，表示控件的哪个边固定在父容器的哪个边上 (Anchor positions (primary and secondary) relative to parent container, used when layoutMode is AnchorToEdges. Determines which side(s) of the control remain fixed to which side of the parent). 例如 anchor_1=Top, anchor_2=Right 表示控件上边和右边相对父窗口距离保持不变 (e.g., Top + Right means the control’s top and right edges maintain constant distance from the parent’s top and right edges). - **背景快照属性 (Background snapshot)**: - `IMAGE* saveBkImage` – 保存的背景图像指针，用于在控件重绘前恢复覆盖区域背景 (Pointer to an IMAGE storing the snapshot of the background behind the control). 如果不为空，表示当前持有一份有效的背景缓存 (If not null, a valid background image is stored). - `int saveBkX, saveBkY` – 背景快照在屏幕上的保存起始坐标 (The X, Y coordinates of where the background snapshot was taken). - `int saveWidth, saveHeight` – 背景快照区域的宽度和高度 (The width and height of the saved background area). - `bool hasSnap` – 标记当前是否有有效的背景快照 (Flag indicating whether a valid background snapshot is currently stored). - `StellarX::RouRectangle rouRectangleSize` – 控件圆角矩形参数。当控件形状为圆角矩形时，使用该结构决定圆角的大小 (Stores the control’s rounded rectangle corner sizes. Used when the control’s shape is a rounded rectangle to determine the curvature radii)。默认圆角宽高为20 (Defaults to 20 for both width and height, as defined in RouRectangle). - **绘图状态缓存 (Drawing state caches)**: 为了在控件绘制时保存并恢复全局绘图状态，每个控件维护以下当前状态指针： - `LOGFONT* currentFont` – 当前字体样式的备份指针 (Pointer to a LOGFONT storing the current font style before control drawing). - `COLORREF* currentColor` – 当前文本绘制颜色的备份 (Pointer storing current text color). - `COLORREF* currentBkColor` – 当前背景填充颜色的备份 (Pointer storing current background fill color). - `COLORREF* currentBorderColor` – 当前边框颜色的备份 (Pointer storing current border color). - `LINESTYLE* currentLineStyle` – 当前线型样式的备份 (Pointer storing current line style settings). 以上指针在控件销毁时会删除以释放资源。调用 `saveStyle()` 时，这些指针会指向保存的全局状态；`restoreStyle()` 则将全局绘图状态恢复并重置这些指针 (These are allocated to hold copies of global drawing settings; they are deleted in the Control destructor to free resources. When `saveStyle()` is called, the current global drawing settings are stored in these objects, and `restoreStyle()` reapplies them and resets the pointers). - **禁用复制和移动 (Deleted copy/move)**: 为防止误用，Control 明确删除了复制构造和赋值运算符，以及移动构造和赋值 (Copy constructor and assignment operator, as well as move constructor and move assignment, are deleted to prevent copying or moving of controls)。控件对象不可被复制，只能以指针或智能指针方式管理 (Control objects cannot be copied; they should be managed via pointers or smart pointers). - **构造函数与析构函数 (Constructors & Destructor)**: - `Control(int x, int y, int width, int height)` – **受保护构造函数**，使用指定的位置和尺寸初始化控件基本属性。被派生类调用，用于设置控件初始的 local/global 坐标和宽高 (Protected constructor used by subclasses to initialize the control’s position (both local and global) and size). - `Control()` – **受保护默认构造函数**，初始化控件位置为 (0,0)，宽高为 (100,100)。通常不会显式使用，除非子类需要默认大小的控件 (Initializes the control at origin (0,0) with a default size of 100×100. Typically invoked by subclass default constructors if needed). - `virtual ~Control()` – 析构函数，基类析构确保清理分配的资源。它删除并释放上述 `currentFont` 等绘图状态缓存指针，并调用 `discardBackground()` 释放背景快照 (Base destructor cleans up allocated resources, deleting the stored font, color, and line style objects, setting them to null, and calling `discardBackground()` to release any saved background image)。 **依赖关系 (Dependencies)**: - **操作系统/图形库**：Control 使用 Win32 API 数据类型（如 `HWND`、`COLORREF` 等）以及 EasyX 图形库进行绘图管理。因此需要 Windows 平台支持 (The Control class includes Windows headers and depends on EasyX graphics library for drawing operations, hence it runs on Windows platform). - **框架核心类型**：Control 依赖 `CoreTypes.h` 中定义的 StellarX 命名空间枚举和结构，如 LayoutMode、Anchor、ControlShape、RouRectangle、ControlText 等，用于自身属性 (It relies on types defined in CoreTypes, such as LayoutMode, Anchor, ControlShape, RouRectangle, and ControlText for its properties and behavior). - **子类关系**：Control 是所有具体控件（按钮、标签、文本框、表格等）的基类。比如 **Button**, **Label**, **TextBox**, **Table** 等类都公开继承自 Control (All concrete control classes like Button, Label, TextBox, Table, etc., publicly inherit from Control). Control 提供的接口（draw、handleEvent等）由子类实现，实现各自的外观和行为 (The interfaces provided by Control (draw, handleEvent, etc.) are overridden by these subclasses to implement their specific appearance and behavior). - **容器关系**：尽管 Control 本身不包含子控件列表，但其派生的容器类（如 **Canvas**、**Window** 等）利用继承的接口管理子控件集合 (Control itself does not store child controls, but derived container classes like Canvas or Window use Control’s interface to manage child controls). ## 派生控件（Derived Controls） 以下类均继承自 **Control** 基类，表示常见的可视控件组件。这些控件实现了 Control 定义的接口，并根据需要添加自己的属性和方法。每个控件的继承关系和特定功能如下： *(The following classes all derive from the **Control** base class, representing common UI components. They implement the interfaces defined by Control and add their own properties and methods as needed. Each control’s inheritance and specific features are detailed below:)* ### Button（按钮控件） **类名**：`Button` **继承**：继承自 Control (`class Button : public Control`) **简要说明**：多功能按钮控件，支持多种状态和样式。提供完整的按钮交互，包括普通点击、切换开关、禁用等模式，并支持自定义外观（颜色、形状、填充）和鼠标悬停提示等。（*A versatile button control supporting multiple states and styles. It provides full button functionality including normal click, toggle (on/off) mode, and disabled state. The Button supports extensive customization of appearance (colors, shape, fill patterns) and features such as hover tooltips.*） **公共方法**： - `Button(int x, int y, int width, int height, const std::string& text, StellarX::ButtonMode mode = NORMAL, StellarX::ControlShape shape = RECTANGLE)` – **构造函数**，创建按钮，指定位置尺寸、显示文本，以及可选的按钮模式和形状。将按钮初始化为默认颜色配置 (Constructs a button at given position and size with the specified label text, and optional ButtonMode and shape. Initializes the button with default color settings for its states). - `Button(int x, int y, int width, int height, const std::string& text, COLORREF ct, COLORREF cf, StellarX::ButtonMode mode = NORMAL, StellarX::ControlShape shape = RECTANGLE)` – **构造函数**，创建具有自定义“按下/未按”颜色的按钮。参数 `ct` 为按钮被点击时颜色，`cf` 为按钮未点击时颜色 (Constructor to create a button with custom colors for the pressed (`ct`) and unpressed (`cf`) states). - `Button(int x, int y, int width, int height, const std::string& text, COLORREF ct, COLORREF cf, COLORREF ch, StellarX::ButtonMode mode = NORMAL, StellarX::ControlShape shape = RECTANGLE)` – **构造函数**，创建具有自定义“按下/未按/悬停”颜色的按钮。额外参数 `ch` 指定鼠标悬停时的按钮背景颜色 (Constructor to create a button with custom pressed (`ct`), unpressed (`cf`), and hover (`ch`) colors). - `~Button()` – **析构函数**，销毁按钮时释放可能加载的图像资源。例如如果按钮使用了自定义填充图像，将在析构时清理 (Releases any resources such as loaded images when the button is destroyed). - `void draw() override` – 绘制按钮外观。实现包括根据按钮状态（正常、悬停、按下、禁用）设置颜色和填充，并绘制按钮边框和文本等。按钮绘制支持多种形状，如果是圆形或椭圆按钮，会进行鼠标区域判定的特殊处理 (Renders the button. The implementation sets the appropriate colors/fill based on button state (normal, hover, pressed, disabled), draws the button’s border and filled shape, and then draws the text centered on the button. Different shapes (rectangle, rounded rect, circle, ellipse) are handled, including special hit-testing for circular/elliptical shapes). - `bool handleEvent(const ExMessage& msg) override` – 处理按钮的鼠标事件。包括检测鼠标按下、释放、移入、移出等，以更新按钮的 `click`（按下状态）和 `hover`（悬停状态），并触发相应回调 (Handles mouse events for the button. This includes detecting mouse down/up to update the `click` state (pressed or not), tracking mouse enter/leave to set the `hover` state, and triggering the appropriate callbacks when clicked or toggled). - 回调设置方法 (Callback setters): - `void setOnClickListener(std::function&& callback)` – 设置按钮在 NORMAL 模式下点击时执行的回调函数。当按钮每次被点击（鼠标按下然后松开）且模式为 NORMAL 时调用此回调 (Assigns a callback to be invoked when the button is clicked in NORMAL mode). - `void setOnToggleOnListener(std::function&& callback)` – 设置按钮在 TOGGLE 模式下从未选中切换为选中状态时的回调。当按钮切换到“按下/选中”状态时调用 (Sets the callback for when a toggle-mode button is toggled on (pressed state)). - `void setOnToggleOffListener(std::function&& callback)` – 设置按钮在 TOGGLE 模式下从选中切换为未选中状态时的回调。当按钮从按下恢复为弹起状态时调用 (Sets the callback for when a toggle-mode button is toggled off (released state)). - 模式和形状设置 (Mode/Shape settings): - `void setbuttonMode(StellarX::ButtonMode mode)` – 设置按钮的工作模式（NORMAL/TOGGLE/DISABLED）。更改模式会影响按钮行为：设置 TOGGLE 会使按钮保持按下状态，设置 DISABLED 会使按钮不可点击 (Changes the button’s operating mode; e.g., setting TOGGLE makes the button stay pressed when clicked, setting DISABLED grays it out and disables interaction). - `void setButtonShape(StellarX::ControlShape shape)` – 设置按钮形状（矩形、圆角矩形、圆形、椭圆等）。修改形状会影响按钮绘制的轮廓和鼠标命中区域 (Sets the geometric shape of the button. This changes how the button is drawn (e.g., with rounded corners or as a circle) and how hover/click hit-testing is calculated). - 外观属性设置 (Appearance setters): - `void setROUND_RECTANGLEwidth(int width)` / `void setROUND_RECTANGLEheight(int height)` – 若按钮形状为圆角矩形，设置其圆角椭圆的宽度或高度。用于调整圆角大小 (If the button’s shape is a rounded rectangle, these adjust the horizontal/vertical radius of the corner’s ellipse to change the corner roundness). - `void setFillMode(StellarX::FillMode mode)` – 设置按钮背景的填充模式。例如纯色填充、图案填充等 (Sets the fill mode for the button’s background, e.g., solid color, hatched pattern, image pattern, etc.). - `void setFillIma(StellarX::FillStyle style)` – 设置按钮背景填充的图案样式。只有当 FillMode 为 Hatched 有效，用于选择具体的填充图案 (Sets the hatched fill pattern for the button’s background, effective if FillMode is set to Hatched. Chooses which hatch style to use). - `void setFillIma(std::string imageName)` – 设置按钮背景填充为指定文件的图像。这会加载给定路径的图像用于填充按钮背景（FillMode 应设为 Pattern/DibPattern）(Uses an external image file to fill the button background. This will load the image from the given file path; the FillMode should be set to Pattern or DibPattern to use the image fill). - `void setButtonBorder(COLORREF color)` – 设置按钮边框颜色。更改边框绘制使用的颜色 (Sets the border color of the button’s outline). - `void setButtonFalseColor(COLORREF color)` – 设置按钮未被按下时的背景颜色。即按钮处于弹起状态的填充色 (Sets the background color for the button’s unpressed (false) state). - `void setButtonText(const char* text)` / `void setButtonText(std::string text)` – 设置按钮显示的文本标签。更改按钮上显示的文字内容 (Sets the label text displayed on the button). - `void setButtonClick(BOOL clicked)` – 强制设置按钮按下状态。传 true 则使按钮显示为按下状态，false 则恢复未按状态；通常用于程序控制 TOGGLE 模式按钮的状态 (Forces the button’s pressed state. True makes the button appear pressed (selected), false makes it unpressed. This is mainly useful for programmatically controlling the state of a TOGGLE mode button). - 查询方法 (Getters): - `bool isClicked() const` – 返回按钮当前是否处于按下（选中）状态。TOGGLE 模式下按下一次后该状态会保持，NORMAL 模式下每次点击会短暂为 true (Indicates whether the button is currently in the pressed state. In TOGGLE mode, this stays true after being clicked until toggled off; in NORMAL mode it is true only during the click). - `std::string getButtonText() const` / `const char* getButtonText_c() const` – 获取按钮的文本标签内容。提供 std::string 和 C 字符串两种形式 (Returns the text label of the button, as a std::string or C-string). - `StellarX::ButtonMode getButtonMode() const` – 获取按钮当前的模式（NORMAL/TOGGLE/DISABLED）. - `StellarX::ControlShape getButtonShape() const` – 获取按钮当前形状类型. - `StellarX::FillMode getFillMode() const` – 获取按钮当前填充模式. - `StellarX::FillStyle getFillIma() const` – 获取按钮当前填充图案样式. - `IMAGE* getFillImaImage() const` – 如果按钮使用了图像填充，获取当前填充所用的 IMAGE 对象指针. - `COLORREF getButtonBorder() const` – 获取按钮边框颜色. - `COLORREF getButtonTextColor() const` – 获取按钮文字颜色 (Returns the text color used for the button’s label). *（说明：文字颜色存储在 `ControlText` 的 color 字段中，此方法便于直接获取）*(Note: The text color is actually stored in the `ControlText` struct as part of textStyle; this getter provides convenient access to it.)*. - `StellarX::ControlText getButtonTextStyle() const` – 获取按钮的文字样式结构副本。包含字体、字号、颜色等信息 (Returns a copy of the ControlText struct representing the button’s current text style, including font face, size, color, etc.). - **Tooltip 提示功能方法** (Button 提示工具条 API): - `void enableTooltip(bool on)` – 启用或禁用鼠标悬停提示功能。设为 true 则当鼠标悬停在按钮上时显示提示文本 (Enable or disable a tooltip that appears when the mouse hovers over the button). 关闭提示时会立即隐藏当前提示 (Disabling tooltips will hide any currently visible tooltip immediately). - `void setTooltipDelay(int ms)` – 设置提示出现的延迟时间（毫秒）。例如 1000 表示鼠标悬停1秒后显示提示 (Sets the delay in milliseconds before the tooltip is shown on hover. e.g., 1000 means the tooltip appears after 1 second of hovering). - `void setTooltipFollowCursor(bool on)` – 设置提示框是否跟随鼠标移动。如果为 true，则提示将出现在鼠标附近位置，并随鼠标移动更新 (Determines if the tooltip should follow the cursor. If true, the tooltip will appear near the cursor and move along with it). - `void setTooltipOffset(int dx, int dy)` – 设置提示框相对于鼠标位置的偏移。可调整提示框出现的位置，例如 (12, 18) 表示在鼠标坐标基础上右移12，下移18 像素 (Sets an offset for the tooltip’s position relative to the cursor. For example, (12, 18) will position the tooltip 12px to the right and 18px below the cursor). - `void setTooltipStyle(COLORREF textColor, COLORREF backgroundColor, bool transparent)` – 设置提示框文本颜色、背景颜色及是否背景透明。若 transparent 为 true，则提示背景不绘制矩形底色 (Configures the tooltip’s text color, background color, and transparency. If `transparent` is true, the tooltip has no opaque background, allowing underlying graphics to show through behind the text). - `void setTooltipText(const std::string& text)` – 设置按钮在 NORMAL 模式下的提示文本。当按钮未切换或不在TOGGLE模式时，将显示此提示内容 (Sets the tooltip text for the button (used in NORMAL mode or when the button is not toggling between two states)). 调用该函数会将 tipTextClick 设置为给定内容，并标记用户自定义标志以避免覆盖 (This updates the internal `tipTextClick` and flags that a custom tooltip is set by the user). - `void setTooltipTextsForToggle(const std::string& onText, const std::string& offText)` – 设置按钮在 TOGGLE 模式下不同状态的提示文本。第一个参数用于按钮选中(Pressed)时的提示，第二个用于未选中(Released)时的提示 (Defines two tooltip strings for a toggle-mode button: one when the button is toggled on (pressed) and one when toggled off). **成员变量** *(Button的大部分成员为私有 private)*： - `std::string text` – 按钮当前显示的文本 (The text label displayed on the button). - `bool click` – 按钮按下状态标志。true 表示按钮当前呈现为按下（TOGGLE模式下为选中），false 表示未按下。(Indicates if the button is in a pressed state. True when the button is currently pressed (or toggled on), false when not pressed.) - `bool hover` – 按钮悬停状态标志。true 表示鼠标当前在按钮区域内 (Indicates if the mouse cursor is currently hovering over the button). - `std::string cutText` – 裁剪后的文本。如果按钮文本过长需要裁剪显示，则存储裁剪结果 (A possibly truncated version of the text used for rendering if the full text does not fit in the button). - `bool needCutText` – 标志是否需要裁剪文本。当文本长度超出按钮宽度时设为 true (Flag indicating if text needs to be truncated to fit the button width). - `bool isUseCutText` – 标志当前是否使用裁剪后的文本显示。为 true 则表示 draw 时使用 `cutText` 而非完整 text (Indicates whether the button is currently using the truncated `cutText` for display instead of the full `text`). - `int padX, padY` – 文本绘制的内边距 (padding)。padX 是左右最小内边距像素，padY 是上下内边距 (Minimum horizontal (padX) and vertical (padY) padding in pixels around the button’s text). 默认 padX=6, padY=4. - **颜色设置 (Color settings)**: - `COLORREF buttonTrueColor` – 按钮被点击（选中）时的填充背景颜色 (Background color when the button is in pressed/true state). - `COLORREF buttonFalseColor` – 按钮未被点击时的填充背景颜色 (Background color when the button is in unpressed/false state). - `COLORREF buttonHoverColor` – 鼠标悬停在按钮上时的背景颜色 (Background color when the mouse is hovering over the button). - `COLORREF buttonBorderColor` – 按钮边框颜色，默认黑色 (The color of the button’s border; default is black). - `StellarX::ButtonMode mode` – 当前按钮模式（NORMAL/TOGGLE/DISABLED）. - `StellarX::ControlShape shape` – 当前按钮形状（矩形、圆角矩形、圆形或椭圆等）. - `StellarX::FillMode buttonFillMode` – 按钮填充模式（纯色、图案等），默认 Solid 纯色填充. - `StellarX::FillStyle buttonFillIma` – 按钮填充图案样式，默认 BDiagonal（右斜线网格），当 FillMode=Hatched 时使用. - `IMAGE* buttonFileIMAGE` – 填充按钮背景的图像指针（如使用自定义图片填充），默认为 nullptr. - **回调函数**： - `std::function onClickCallback` – 按钮点击回调函数指针 (Function to call on button click in normal mode). - `std::function onToggleOnCallback` – 按钮 TOGGLE 模式下切换为选中状态时的回调 (Function to call when a toggle button is toggled on). - `std::function onToggleOffCallback` – 按钮 TOGGLE 模式下切换为未选中状态时的回调 (Function to call when a toggle button is toggled off). - `StellarX::ControlText oldStyle` – 按钮文本原样式的备份 (Backup of the button’s text style before certain changes). 一些操作如禁用按钮时可能暂时修改文本样式（如加删除线），oldStyle 保存原始样式以便恢复 (For example, when disabling the button, the text might be styled with a strikethrough; `oldStyle` stores the original style so it can be restored when re-enabled). - `int oldtext_width, oldtext_height` – 记录上一次绘制时文本的宽度和高度 (Stores the width and height of the text from the last draw, used to detect if recalculation or re-cutting is needed). - `int text_width, text_height` – 当前文本的像素宽度和高度 (The measured pixel width and height of the current text string, used for centering and for truncation logic). - **Tooltip 提示相关**: - `bool tipEnabled` – 是否启用了鼠标悬停提示 (Whether the tooltip feature is enabled for this button). - `bool tipVisible` – 当前提示是否正显示 (Whether the tooltip is currently visible on screen). - `bool tipFollowCursor` – 提示框是否跟随鼠标移动 (Whether the tooltip should move with the cursor). - `bool tipUserOverride` – 用户是否自定义了提示文本 (Flag indicating if the user has overridden the tooltip text via setTooltipText; if false, default texts might be used for toggle states). - `int tipDelayMs` – 提示显示延迟毫秒数，默认1000ms (Delay in milliseconds before tooltip appears; default is 1000 ms). - `int tipOffsetX, tipOffsetY` – 提示框相对鼠标的偏移 (Tooltip offset from the cursor in X and Y). - `ULONGLONG tipHoverTick` – 记录鼠标开始悬停的时间戳 (Timestamp (in GetTickCount units) when the mouse started hovering over the button). - `int lastMouseX, lastMouseY` – 记录最近一次鼠标所在的位置，用于确定 tooltip 出现位置 (The last known mouse coordinates over the button, used for positioning the tooltip). - `std::string tipTextClick` – NORMAL 模式或 Toggle 未选中状态下使用的提示文本 (Tooltip text used in normal mode or when toggle button is in off state). - `std::string tipTextOn` – Toggle 按钮选中状态下使用的提示文本 (Tooltip text when the toggle button is in the on state). - `std::string tipTextOff` – Toggle 按钮未选中状态下使用的提示文本 (Tooltip text when the toggle button is in the off state). - `Label tipLabel` – 用于显示 tooltip 的 Label 控件对象。内部直接复用一个 Label 来呈现提示文本。tooltip 逻辑通过操作 tipLabel 的显示和内容实现 (A Label object used internally to render the tooltip text. The button’s tooltip functionality is implemented by configuring and showing this label near the cursor when needed). **依赖**：Button 依赖 **Label** 控件来显示其 Tooltip 提示 (The Button class internally uses a **Label** control to display tooltips). 它还使用框架的 **ControlShape**、**FillMode**、**FillStyle** 等枚举定义不同的外观选项 (It uses framework enums like ControlShape, FillMode, FillStyle, etc., for its appearance settings). Button 是常用控件，通常作为对话框按钮或触发某动作的 UI 元素使用 (Button is a fundamental interactive control, commonly used in dialogs or as a trigger for actions in the UI). ### Label（标签控件） **类名**：`Label` **继承**：继承自 Control (`class Label : public Control`) **简要说明**：静态文本标签控件，用于显示只读文本内容。Label 不处理用户输入，主要作用是呈现文本，可支持背景透明。（*A static text label control for displaying read-only text. The Label does not handle user input and is mainly for presenting text, with support for transparent background.*） **公共方法**： - `Label()` – 默认构造函数，创建一个空文本的标签，使用默认字体颜色黑色、背景白色，默认大小适配文本 (Default constructor that creates a label with default text “标签” (Chinese for “Label”), black text color, white background. The size will be determined based on text content once set). - `Label(int x, int y, std::string text = "标签", COLORREF textColor = BLACK, COLORREF bkColor = RGB(255,255,255))` – 重载构造函数，在指定位置创建带初始文本的标签，可指定文字颜色和背景色。背景默认白色，text默认“标签” (Overloaded constructor to create a label at given position with initial text and optional text color and background color. The default text is “标签” (label), default text color black, default background white). - `void draw() override` – 绘制标签内容。实现为：如果 `textBkDisap` 为 false，则先绘制背景矩形（填充 `textBkColor`），然后设置文字颜色和字体，将 `text` 绘制在控件位置。如果 `textBkDisap` 为 true，则不绘制背景使其透明叠加 (Renders the label. If `textBkDisap` (background disappear flag) is false, it fills a rectangle with `textBkColor` as background; then draws the `text` at the label’s position using the current font and text color. If `textBkDisap` is true, no background rectangle is drawn, allowing whatever is behind the label to show through, achieving a transparent background effect). Label 根据其文本和样式自动适应大小 (The label’s drawn size adapts to the text content and style). - `void hide()` – 将标签隐藏。实现上相当于 `setIsVisible(false)`，并（可能）清除或不再绘制标签内容 (Hides the label, equivalent to calling setIsVisible(false) so it will no longer be drawn. This is a convenience method to quickly make the label invisible). - `void setTextdisap(bool transparent)` – 设置标签背景是否透明。传入 true 则开启背景透明模式（不绘制背景颜色），false 则有背景色填充 (Enables or disables transparent background for the label. True means the label will not draw any background (transparent), false means it will fill a background with its background color). - `void setTextBkColor(COLORREF color)` – 设置标签背景颜色。仅当背景不透明时有效，改变 Label 绘制时填充的背景矩形颜色 (Sets the background color of the label. Has effect only if the label is not set to transparent; changes the color used to fill behind the text). - `void setText(std::string newText)` – 设置标签显示的文本内容。更新文本后会自动调整控件大小以适应新文本长度，并将控件标记为需要重绘 (Changes the text displayed by the label. After setting, the label may resize itself to fit the new text (depending on implementation) and will be marked dirty for redraw). **事件处理**：Label 重写了 `handleEvent` 但不做任何处理，总是返回 false。这意味着标签不拦截或消费任何事件，事件会传递给底层控件 (The Label overrides `handleEvent` to do nothing and always return false, meaning it does not consume any events and they will pass through it). **成员变量**： - `std::string text` – 标签显示的文本内容 (The text string displayed by the label). - `COLORREF textBkColor` – 文本背景色 (Background color behind the text). 默认情况下在构造时设为白色或指定颜色 (Set in constructor, default white unless specified). - `bool textBkDisap` – 文本背景是否透明的标志。true 表示背景透明（不绘制背景色），false 表示绘制不透明背景 (Flag indicating if the label’s background is transparent. True means do not draw the background (transparent), false means fill background with `textBkColor`). 默认 false (Default is false, meaning background is drawn). - `StellarX::ControlText textStyle` – 标签文本的样式 (字体、字号、颜色等)。默认使用黑色字体、默认大小 (Defaults to a standard font (e.g., 12pt “微软雅黑”) and black color, can be modified to change font style or color). 开发者可以直接修改该结构体的字段（如 textStyle.color 等）然后调用 `draw()` 刷新，以改变标签文字外观 (Developers can modify this struct’s fields (e.g., textStyle.color for text color) and then redraw to change the label’s text appearance). **依赖**：Label 主要依赖 **ControlText** 结构来存储字体和颜色信息，使用 Windows GDI（通过 EasyX）绘制文本。它无子控件且不处理事件，常作为静态显示用途 (The Label uses **ControlText** for font info and EasyX (GDI) to draw text. It has no children and performs no event logic, typically used for static display). ### TextBox（文本框控件） **类名**：`TextBox` **继承**：继承自 Control (`class TextBox : public Control`) **简要说明**：文本输入框控件，支持用户输入和只读显示两种模式，并提供可选的密码模式。内部集成 EasyX 的输入框功能来实现用户输入。（*A text box control that supports both user input mode and read-only display mode, as well as an optional password mode. It internally leverages EasyX’s input box capabilities for text input.*） **公共方法**： - `TextBox(int x, int y, int width, int height, std::string text = "", StellarX::TextBoxmode mode = INPUT_MODE, StellarX::ControlShape shape = RECTANGLE)` – 构造函数，在指定位置创建文本框，初始化显示文本、模式和形状。默认模式为可输入，默认形状为有边框矩形 (Constructs a TextBox at the given position and size, with an initial text (which defaults to empty), a mode (defaults to input mode), and shape (defaults to a bordered rectangle)). - `void draw() override` – 绘制文本框外观。根据当前形状绘制文本框的边框和背景，然后绘制文本内容。若模式为密码模式，则绘制时会隐藏实际文字（例如用星号替代）(Renders the text box. It draws the rectangle (or chosen shape) for the text box border and background, then draws the text. If the mode is password, the actual characters are hidden (likely rendered as asterisks or bullets)). - `bool handleEvent(const ExMessage& msg) override` – 处理文本框的鼠标和键盘事件。当检测到鼠标点击文本框时，若模式为可输入，则调用 EasyX 提供的 `InputBox` 弹出文本输入对话框获取用户输入。获取输入后更新内部文本并标记重绘 (Handles events for the text box. If a mouse click is detected within the text box and the mode is INPUT_MODE, it uses EasyX’s InputBox (a system modal input dialog) to get user input. After the user enters text and closes the InputBox, the TextBox updates its internal text with the new value and marks itself dirty for redraw). 在 READONLY_MODE 下，点击不会触发输入框 (In READONLY_MODE, clicking does nothing). - `void setMode(StellarX::TextBoxmode mode)` – 设置文本框的工作模式（输入或只读或密码）。更改模式会影响交互行为：只读模式下禁止输入，密码模式下输入的文字以特殊符号显示 (Sets the TextBox’s mode. Changing the mode alters its behavior: in READONLY_MODE, user input is disabled; in PASSWORD_MODE, the text is masked when displayed). - `void setMaxCharLen(size_t len)` – 设置文本框允许输入的最大字符长度。限制用户通过 InputBox 输入的字符数量 (Sets the maximum number of characters that can be input in the text box. This limits the length of text accepted by the InputBox dialog). - `void setTextBoxshape(StellarX::ControlShape shape)` – 设置文本框的形状类型。可选矩形或圆角矩形等，但一般文本框使用矩形外观 (Sets the shape of the text box (rectangle, rounded rectangle, etc.). Typically text boxes use a rectangular shape). - `void setTextBoxBorder(COLORREF color)` – 设置文本框边框颜色。改变文本框四周边框的绘制颜色 (Changes the border color of the text box’s outline). - `void setTextBoxBk(COLORREF color)` – 设置文本框背景填充颜色。 (Sets the background fill color of the text box). - `void setText(std::string text)` – 设置文本框显示的文本内容。如果在 INPUT_MODE 下，可以程序matically预填内容；在 READONLY_MODE 下用于显示只读文本 (Sets the text content of the text box. In input mode, can be used to pre-fill text; in read-only mode, use it to display static text). 设置后标记控件需要重绘 (After setting, the control is marked dirty for redraw). - `std::string getText() const` – 获取文本框当前的文本内容。如果处于密码模式，返回的仍是实际文本而非掩码字符 (Returns the current text content of the text box. In password mode, this returns the actual stored text, not the masked display). **成员变量**： - `std::string text` – 文本框当前包含的文本内容 (The text currently stored/displayed in the text box). - `StellarX::TextBoxmode mode` – 文本框当前模式（INPUT_MODE 可输入、READONLY_MODE 只读、PASSWORD_MODE 密码）. - `StellarX::ControlShape shape` – 文本框外观形状（矩形、圆角矩形等）. - `bool click` – 文本框点击状态标志。用于指示当前控件是否处于选中/激活（点击后正在输入）的状态。例如，click 为 true 时可能表示输入框正在获取输入 (A flag possibly indicating if the textbox is “active” or clicked. True might mean the text box was clicked and is awaiting input, though the exact usage depends on implementation details). - `size_t maxCharLen` – 文本框允许输入的最大字符数，默认10。超过此长度的输入会被截断 (Maximum number of characters allowed in the text box. Defaults to 10. Input beyond this length will be truncated or disallowed). - `COLORREF textBoxBkClor` – 文本框背景颜色，默认白色 (Background color of the text box, default is white). - `COLORREF textBoxBorderClor` – 文本框边框颜色，默认黑色 (Border color of the text box, default is black). - `StellarX::ControlText textStyle` – 文本框文本样式。决定文本绘制的字体、颜色等 (The font and text appearance settings for the text content of the text box). 可以调整其中字体大小以改变文本框中文字的显示大小 (Modifying this (e.g., font height) will change how the text appears inside the box). **依赖**：TextBox 依赖 **CoreTypes** 中的 **TextBoxmode** 枚举来区分模式，还使用 EasyX 的 `InputBox` 函数进行实际文本输入对话框（在 Windows 环境下弹出模态输入窗口）。在图形上，它类似 **Button** 使用 **ControlShape** 控制边框形状。TextBox 提供了简单的文本输入能力，对于复杂文本编辑需要另行扩展 (Internally, the TextBox calls EasyX’s InputBox to get user input in a modal dialog, which is a limitation to Windows platform. Graphically, it uses ControlShape for its outline similar to Button. It is intended for basic text input; more complex text editing would require additional functionality beyond this control). ### Table（表格控件） **类名**：`Table` **继承**：继承自 Control (`class Table : public Control`) **简要说明**：高级表格控件，用于显示二维表格数据，支持分页显示和大量数据高效渲染。Table 提供表头、数据行分页、翻页按钮等完整功能，适合用于数据报告、记录浏览等场景。（*An advanced table/grid control for displaying tabular data. It supports pagination and efficient rendering of large data sets. The Table provides features such as headers, paginated data rows, navigation buttons for page flips, etc., making it suitable for reports, record browsers, and similar use cases.*） **主要特性**: 自动分页计算、每页行数可配置、自适应列宽行高、翻页导航按钮、背景缓存优化绘制性能等。（*Key features include automatic pagination and page index calculation, configurable rows per page, auto-calculated column widths and row heights, navigation buttons for paging, and background buffering to optimize rendering performance.*） **公共方法**： - `Table(int x, int y)` – 构造函数，在指定位置创建一个空的表格控件。默认表格初始宽高由内容决定（通常在设置数据后计算）。默认每页显示行数为 5。创建后需调用 `setHeaders` 和 `setData` 来填充表头和数据 (Constructs a Table at the given position (top-left). The initial size may be determined after data is provided. By default, it shows 5 rows per page. After construction, one should call `setHeaders` and `setData` to populate the table). - `~Table()` – 析构函数，清理表格资源 (Destructor to clean up any resources. It will delete any dynamically allocated components, like navigation buttons or labels created internally). - `void draw() override` – 绘制表格当前页的内容。绘制流程包括表头、数据行以及页脚（页码和翻页按钮）。Table 内部通过辅助的私有 `drawHeader()`, `drawTable()`, `drawPageNum()`, `drawButton()` 方法分别绘制不同部分。(Draws the table for the current page. The drawing routine includes rendering the header row, the data rows for the current page, and the footer (page number display and navigation buttons). Internally it likely uses helper functions like `drawHeader()`, `drawTable()` (for data cells), `drawPageNum()`, and `drawButton()` for different sections.) Table 会根据内容自动计算列宽和行高，并支持隔行变色、高亮当前行等（如果实现了的话）(The Table calculates column widths and row heights based on content, and may support features like alternating row colors or highlighting if implemented). - `bool handleEvent(const ExMessage& msg) override` – 处理表格的事件。包括翻页按钮的点击事件，可能还有对行的点击选择等 (Handles events for the table, such as detecting clicks on the "Previous" or "Next" page buttons, and potentially row click events for selection if such feature exists). 当点击翻页按钮时，会更新 `currentPage` 并触发重绘显示新页数据 (On clicking navigation buttons, it updates `currentPage` and triggers a redraw to display the new page of data). - 设置数据与外观的方法 (Data and appearance setters): - `void setHeaders(std::initializer_list headers)` – 设置表格表头列名。传入一个字符串列表，每个元素作为一列的标题。调用后会自动计算列宽，并标记需要重绘表头 (Sets the table’s header labels. The initializer_list of strings provides a title for each column. This triggers a recalculation of column widths and marks the table for redraw). - `void setData(std::vector data)` – 设置表格数据。**注意**: 这里参数类型可能是错误，应为 `std::vector>` 或初始化列表（见下）(Note: The signature in code appears to be `setData(std::vector)` which is likely a typo; actual implementation probably expects a 2D structure. Use the initializer_list overload for clarity). - `void setData(std::initializer_list> data)` – 设置表格数据。传入一个列表，每个元素是代表一行的字符串向量。Table 将保存数据并自动分页计算 `totalPages` 和 `currentPage` 等 (Sets the table data by providing an initializer_list of rows, where each row is a vector of strings for the columns. The table stores this data and computes `totalPages` based on rowsPerPage, resetting currentPage to 1). - `void setRowsPerPage(int rows)` – 设置每页显示的行数。改变此值会重新计算总页数并调整当前显示 (Sets how many rows are displayed per page. Changing this will recalculate `totalPages` and adjust the current page if needed). - `void showPageButton(bool show)` – 设置是否显示翻页按钮。如果数据量小仅一页，开发者可选择隐藏翻页控制 (Determines whether the page navigation buttons (prev/next) are visible. If the data fits on one page, one might hide the navigation controls). - `void setTableBorder(COLORREF color)` – 设置表格边框颜色（单元格网格线颜色）。改变表格绘制时单元格边框和外框的颜色 (Sets the color used for the table grid lines and border). - `void setTableBk(COLORREF color)` – 设置表格背景颜色。作为单元格背景的底色 (Sets the background color used for the table’s cells). - `void setTableFillMode(StellarX::FillMode mode)` – 设置表格单元格背景填充模式。可选择纯色或图案填充 (Sets the fill mode for the table cells background, e.g., solid fill or hatched pattern). - `void setTableLineStyle(StellarX::LineStyle style)` – 设置表格线型样式。用于单元格边框线，可选实线、虚线等 (Sets the line style for the table grid lines (cells borders), e.g., solid, dashed). - `void setTableBorderWidth(int width)` – 设置表格网格线和外边框的宽度（像素）(Sets the width (thickness) of the table’s grid lines and border in pixels). - `void clearHeaders()` – 清空表头。将 headers 列表置空，并标记需要重绘 (Clears all header labels. After calling, the table will have no columns defined until new headers are set). - `void clearData()` – 清空表格数据。移除所有数据行，重置当前页等 (Clears all table data rows and resets pagination state). - `void resetTable()` – 清空表头和数据。相当于依次调用 clearHeaders() 和 clearData(), 将表格恢复初始空状态 (Clears both headers and data, resetting the table to an initial empty state). - `void onWindowResize() override` – 当容器窗口大小变化时调用。实现为丢弃背景快照并标记表格为脏，需要在新尺寸下重绘 (Called when the window is resized. The Table’s implementation likely discards any saved background (if using caching) and marks itself dirty to redraw according to the new size). - 查询方法 (Getters): - `int getCurrentPage() const` – 获取当前页码（从1开始计数）. - `int getTotalPages() const` – 获取总页数. - `int getRowsPerPage() const` – 获取每页显示的行数设置. - `bool getShowPageButton() const` – 获取当前是否设置为显示翻页按钮. - `COLORREF getTableBorder() const` – 获取表格边框（网格线）颜色. - `COLORREF getTableBk() const` – 获取表格背景颜色. - `StellarX::FillMode getTableFillMode() const` – 获取表格当前填充模式. - `StellarX::LineStyle getTableLineStyle() const` – 获取表格当前线型样式. - `std::vector getHeaders() const` – 获取当前表头列表的副本. - `std::vector> getData() const` – 获取当前表格数据的副本. - `int getTableBorderWidth() const` – 获取表格边框/网格线宽度. - `int getTableWidth() const, int getTableHeight() const` – 获取表格当前总宽度和总高度。这通常对应绘制时计算出的整个表格占用尺寸，包括表头和页脚 (Returns the overall width and height of the table as currently rendered, including header and footer areas. These are typically calculated during the last draw). **成员变量** *(主要为私有属性)*： - `std::vector> data` – 表格数据存储，按行列组织的字符串二维数组。每个内部 `std::vector` 代表一行的数据，所有行长度应与 headers 列数匹配 (Stores the table’s data in a 2D vector of strings (rows × columns). Each inner vector represents one row. The number of elements in each row should match the number of header columns). - `std::vector headers` – 表格列标题列表。长度即列数 (List of column headers. The size of this vector defines the number of columns in the table). - `std::string pageNumtext` – 页码标签文本模版。默认值 "页码标签"，可能用于显示当前页/总页的信息 (A template or base text for the page number label, default "页码标签". This might be combined with current page info to display pagination status like “第 X 页/共 Y 页”). - `int tableBorderWidth` – 表格边框和网格线宽度，默认值来自 `TABLE_DEFAULT_BORDER_WIDTH` 宏，通常为1 (Thickness of table grid lines and border. Default comes from TABLE_DEFAULT_BORDER_WIDTH, typically 1 pixel). - `std::vector colWidths` – 每列宽度像素值的数组。绘制时每列的起始位置和单元格矩形基于此计算 (Array of pixel widths for each column. These are calculated from header/text lengths and used to layout the table cells). - `std::vector lineHeights` – 每行高度像素值的数组。通常各行高度相同，由字体高度和 padding 决定；也可能表头行和数据行区分 (Array of heights for each row. Often uniform for all data rows and possibly a different height for header; determined by text height and vertical padding). - `int rowsPerPage` – 每页显示行数，默认 5. - `int currentPage` – 当前页码，默认 1（第一页）. - `int totalPages` – 总页数，默认 1。根据数据行数和 rowsPerPage 计算得到 (Total number of pages, computed based on number of data rows and rowsPerPage). - **特性开关**: - `bool isShowPageButton` – 是否显示翻页按钮，默认 true. - `bool isNeedDrawHeaders` – 是否需要绘制表头标志，暂未使用（代码注释为“暂时废弃”）. - `bool isNeedCellSize` – 是否需要计算单元格尺寸标志。可能用于延迟计算优化 (Flag indicating if cell sizes need recalculation. Possibly used to optimize and avoid recalculating cell metrics on every draw). - `bool isNeedButtonAndPageNum` – 是否需要计算翻页按钮和页码信息标志。类似地用于控制是否更新页脚 (Flag indicating if navigation buttons and page number label need to be recalculated/positioned. Could be used to skip re-layout of footer if not needed). - **导航控件**: - `Button* prevButton` – “上一页”按钮指针。指向 Table 内部创建的 Button 对象，用于翻页到前一页。nullptr 表示未创建或隐藏 (Pointer to the "Previous Page" button control. Created internally by the Table for pagination. If nullptr, the button is not present or not needed). - `Button* nextButton` – “下一页”按钮指针。用于翻到下一页 (Pointer to the "Next Page" button). - `Label* pageNum` – 页码显示的标签指针。用于显示当前页/总页信息 (Pointer to a Label that displays the page number text, e.g., "第 X 页/共 Y 页"). - **内部坐标缓存**（用于绘制过程的临时值）: - `int dX, dY` – 当前单元格绘制的起始坐标 (likely "draw X/Y": the starting x,y for drawing cells). 初始化为表格区域左上角 (Initialized to x,y of the table). 绘制过程中更新以逐行逐列推进 (These are updated as the table draws each cell to track the current drawing position). - `int uX, uY` – 当前单元格绘制的结束坐标 (likely "end X/Y": maybe unused or similar to dX,dY as drawing coordinates). - `int pX, pY` – 页码标签 Label 的左上角坐标 (Coordinates for where the page number label is placed). - **颜色和样式**: - `StellarX::FillMode tableFillMode` – 表格单元格填充模式, 默认 Solid。 - `StellarX::LineStyle tableLineStyle` – 表格网格线线型, 默认 Solid 实线。 - `COLORREF tableBorderClor` – 表格边框和网格线颜色, 默认黑色 (RGB(0,0,0))。 - `COLORREF tableBkClor` – 表格背景底色, 默认白色 (RGB(255,255,255))。 - `StellarX::ControlText textStyle` – 表格内容文本样式。用于设置表格单元格中文字的字体和颜色，默认继承自 ControlText 默认值 (Determines font and color for text drawn in the table’s cells). 可以修改例如字体大小以调整表格内容字号 (Can be adjusted to change text size of table content). **依赖**：Table 控件内部组合使用 **Button**（翻页按钮）和 **Label**（页码显示）控件来实现完整功能，因此它依赖这些子控件的接口来处理事件和绘制文字。Table 作为容器包含这些控件并在翻页时对它们进行布局和更新 (The Table internally composes **Button** controls for navigation and a **Label** for page number, thus it relies on their functionality for event handling and text rendering. The Table acts as a container for these controls, positioning and updating them as pages change). Table 还会使用 GDI 绘制单元格边框和背景，对性能要求高时利用了背景缓存等优化 (The Table uses GDI (EasyX) to draw cell grids and background, and likely employs background buffering optimizations to handle large data efficiently). ## 复合控件（Composite Controls） 复合控件是指包含其他控件作为子元素，实现更复杂界面功能的控件。例如 TabControl 包含多个页面 Canvas 和对应的按钮，Dialog 包含文本、按钮等控件。下面是这些复合控件的接口说明： *(Composite controls contain other controls as child elements to provide more complex UI functionality. For example, TabControl contains multiple Canvas pages and their respective tab buttons; Dialog contains text and button controls. Below are the interface details of these composite controls:)* ### TabControl（选项卡控件） **类名**：`TabControl` **继承**：继承自 Canvas (`class TabControl : public Canvas`) **简要说明**：选项卡容器控件，可在单一界面区域内承载多个子页面，通过页签（标签按钮）进行切换。TabControl 提供类似选项卡对话框的界面，每个选项卡有一个标题按钮和对应的内容区域。（*A tabbed container control that can hold multiple child “pages” in the same area and switch between them using tab header buttons. It provides a tabbed dialog-like interface where each tab has a header button and an associated content area.*） **功能特点**：TabControl 支持将页签栏放置在容器的不同位置（上、下、左、右）。每个选项卡由一个按钮（作为页签）和一个 Canvas 容器（作为页面内容）组成。一次仅显示一个选项卡的内容，其余页面隐藏。TabControl 自动管理页签按钮的布局和当前激活页内容的显示切换。（*The TabControl allows the tab bar to be placed at the top, bottom, left, or right of the control. Each tab consists of a Button (tab header) and a Canvas (page content). Only one page is visible at a time, with others hidden. The TabControl automatically handles laying out the tab header buttons and toggling the visibility of the page content for the active tab.*） **公共方法**： - `TabControl()` – 默认构造函数，创建一个默认大小的选项卡控件。内部调用 Canvas 基类构造将位置设为 (0,0), 宽高默认100×100，并设置控件ID为 "TabControl" (Calls the Canvas constructor to initialize a TabControl at (0,0) of default size, and sets its id to "TabControl"). - `TabControl(int x, int y, int width, int height)` – 构造函数，在指定位置和尺寸创建一个选项卡控件。初始化后无选项卡，需要通过 `add` 方法添加页面 (Creates a TabControl at specified position with given width and height. Initially it contains no tabs; use `add()` to add tab pages). - `void add(std::pair, std::unique_ptr>&& control)` – **添加选项卡页面**，将一个按钮-页面对添加为新的选项卡。`pair.first` 是页签按钮，`pair.second` 是对应内容 Canvas。调用该方法后，TabControl 会负责管理该按钮和页面的布局与显示 (Adds a new tab to the TabControl given a pair of a Button (tab header) and a Canvas (tab page content). After adding, the TabControl takes ownership and will manage the layout and display of the tab’s button and page). 调用后自动调整所有页签按钮大小并初始化新页面坐标，将新选项卡默认设置为隐藏内容。(The method will recalc the size of all tab buttons, position the new page, and by default hide the new page’s content so that it’s not shown until activated.) - `void add(std::string tabText, std::unique_ptr control)` – **向已有选项卡添加子控件**。此重载用于将一个新的控件添加到已有的某个选项卡页面内。`tabText` 指定目标选项卡的标题文本，`control` 是要添加的控件指针。调用时会在匹配标题的选项卡页面 Canvas 内添加该控件，并保持其相对坐标 (Adds a control to one of the existing tab pages. The `tabText` identifies which tab’s page to add to (by matching the tab’s title text), and `control` is the new child control to add. The method sets the new control’s parent to the target page’s Canvas and adjusts its coordinates to be relative to that page). 如果 `tabText` 没找到对应页签，则不执行操作 (If no tab with the given title is found, the call does nothing). - `void setTabPlacement(StellarX::TabPlacement placement)` – 设置选项卡页签栏的位置。可以在 TabControl 的顶部、底部、左侧或右侧显示页签。调用后立即重新布局页签和页面区域 (Sets the placement of the tabs (Top, Bottom, Left, or Right). Recomputes the layout of tab header buttons and page content areas accordingly). - `void setTabBarHeight(int height)` – 设置页签栏的高度（或宽度，如果在左/右侧）。调整这个值可以改变页签按钮的大小。默认高度有最小值限制 (Sets the height of the tab bar (if tabs are top/bottom) or width (if tabs are left/right)). This effectively changes the size of each tab button on that dimension. There is an internal minimum enforced for tab button size to ensure usability (e.g., `BUTMINHEIGHT`, `BUTMINWIDTH`). - `void setActiveIndex(int index)` – 显式设置当前激活的选项卡索引。索引从0开始。若指定索引有效且不等于当前激活，则将对应页签按钮设为点击状态，切换显示该页内容。如果在首次绘制前调用，则会将此索引存为默认激活页 (Sets the active tab by index (0-based). If called after the control is shown and the index is valid (and different from current), it programmatically “clicks” that tab’s button to activate the page. If called before the first draw (initialization phase), the index is stored as the default to activate on first render rather than switching immediately). - `int getActiveIndex() const` – 获取当前激活的选项卡索引。如果没有页签被选中则可能返回 -1 (Returns the index of the currently active tab. If no tab is active, it returns -1). - `int count() const` – 获取当前选项卡总数量. - `int indexOf(const std::string& tabText) const` – 根据页签标题文本查找对应的索引。如果存在多个同名页签，返回第一个匹配的索引；如未找到则返回 -1 (Returns the index of the tab with the given title text. If multiple tabs have the same title, returns the first match. Returns -1 if not found). - `void setIsVisible(bool visible) override` – 重载自 Canvas：设置整个 TabControl（以及其中所有页签按钮和页面）的可见性。如果设置为可见，则只显示当前激活的页面，但**所有**页签按钮都会显示；如果设置为不可见，则页签和页面全部隐藏。此外，该实现会确保隐藏状态下子页面不会遗留背景快照 (Overrides Canvas::setIsVisible to show/hide the TabControl along with all its tabs and pages. When made visible, all tab header buttons are shown and only the currently active page’s Canvas is shown (others remain hidden); when invisible, all tabs and pages are hidden. It also handles clearing out saved snapshots for hidden pages to prevent stale visuals). - `void onWindowResize() override` – 当父窗口尺寸改变时调用。实现为：调用 Control 基类的 onWindowResize() 丢弃自身背景，然后重新计算页签栏和页面区域布局。之后对每个页签按钮和页面调用各自 onWindowResize() 使其内容也调整 (On parent window resize, the TabControl’s override first calls Control::onWindowResize() to discard its background and mark dirty. It then recalculates the tab bar and page layout (size and position) for the new control size. Finally it forwards the onWindowResize call to each tab’s Button and Canvas so they can adjust their internals if needed). - `void setDirty(bool dirty) override` – 重载自 Control：将 TabControl 及其所有子页签按钮和页面的脏标记设为给定值。通常在需要整组重绘时调用 (Overrides Control::setDirty to set the dirty flag for the TabControl itself and all its child tab buttons and page Canvases to the given value (true/false). This is useful to invalidate or validate the entire tab set at once). - `void requestRepaint(Control* parent) override` – 重载自 Control：处理 TabControl 自身或子控件请求重绘的逻辑。如果 `parent` 参数就是当前 TabControl 本身，则表示一次针对整个选项卡控件的重绘请求；实现中会检查每个子控件（按钮和页面）的 dirty 状态，将需要重绘的子控件各自绘制一遍。否则（parent 不是本控件），调用基类 Canvas 的 onRequestRepaintAsRoot() 让更高层容器处理。(Overrides Control::requestRepaint. If the `parent` passed in is this TabControl itself (meaning a repaint of the whole tab control is requested), the implementation iterates through all tab pairs and if a tab’s Button or Canvas is dirty and visible, it calls their draw() to repaint them. If `parent` is not this (meaning the request is bubbled further up), it defers to the base behavior by calling onRequestRepaintAsRoot().) 这一特殊实现确保当 TabControl 本身重绘时，其子页面内容也会刷新 (This ensures that when the TabControl is repainted, all visible child content is also redrawn). **事件处理**：TabControl 实现自己的 `handleEvent` 逻辑，将事件分发给当前页的子控件或页签按钮。具体而言，当鼠标点击一个页签按钮时，相应按钮会触发回调使该选项卡切换为激活状态；TabControl::handleEvent 会优先将事件传给所有页签按钮（通常是排列在最上层）检查是否有按钮点击。如果没有页签按钮消费事件，则再把事件传递给当前激活的页面 Canvas 里的子控件。这样实现当用户点击不同区域时由不同元素响应 (The TabControl’s event handling sends incoming messages first to the tab header buttons (which are typically drawn above the page content) to see if any button consumes the event (e.g., a click on a tab). If none of the buttons handle the event, it then forwards the event to the currently visible page’s Canvas (which in turn dispatches to its child controls). This ensures the correct element responds depending on where the user clicked). **成员变量**： - `std::vector< std::pair< std::unique_ptr