Duilib 源码分析之 CControlUI 篇

今天来介绍一下 Duilib 中所有类型控件的基类： CControlUI，后续后陆续介绍各个不同的控件的实现。对于基类 CControlUI 主要介绍下共通的方法和属性 (由于本人水平有限，以下内容只是个人见解，仅供参考，如有错误请指正，不胜感激，本贴基于 Duilib 的版本是 “Duilib 开源项目圈2群” 中下载的版本，在代码上可能会有些出入)

• CDuiString GetName() const 和 void SetName(LPCTSTR pstrName) ，获取或设置控件的名字，对应于成员变量 m_sName ，设置名字后可以通过 CControlUI* CPaintManagerUI::FindSubControlByName(CControlUI* pParent, LPCTSTR pstrName) const 或 CControlUI* CPaintManagerUI::FindControl(LPCTSTR pstrName) const 获取对应的控件
• LPCTSTR GetClass() const 获取控件的类名，每种控件对应固定、唯一的一个类名
• LPVOID GetInterface(LPCTSTR pstrName) 根据类名称获取当前对象，我认为这个方法的应用场合是当你需要判断某控件是否是某一个类型控件时用的，例如我有一个 CControlUI* 的指针，我想知道它是否是个 CTextUI 控件，就可以通过 GetInterface(L"TextUI") 判断返回值是否为空来判断，其实也可以用 GetClass 和 L"TextUI" 比较来实现。
• UINT GetControlFlags() const 具体由子类实现，代表此控件支持某种行为，例如是否支持鼠标悬停时鼠标样式改变，是否支持 tab 选中等
• bool Activate() 在基类中只是判断控件是否是可见并未禁用的，在子类中基类的此方法返回 true 的前提下并触发控件的行为，例如对应 CButtonUI 相当于点击此按钮，对于 CComboUI 代表弹出下拉框等
• CPaintManagerUI* GetManager() const 和 SetManager(CPaintManagerUI* pManager, CControlUI* pParent, bool bInit = true) 获取或设置当前控件对应的 CPaintManagerUI， 对应于成员变量 m_pManager， 是在解析 xml 创建控件时把当前窗口绑定的 CPaintManagerUI 传入到此成员中。 另外对于 CContainer 的子成员，在调用 SetManager 时同时会传入 parent
• CControlUI* GetParent() const 获取父控件
• bool SetTimer(UINT nTimerID, UINT nElapse) 和 void KillTimer(UINT nTimerID) 添加或删除指定 ID 的 Timer。详细可参考 ： Duilib 源码分析之 Timer 篇
• CDuiString GetText() const 和 void SetText(LPCTSTR pstrName) ，获取或设置控件显示的文字，对应于成员变量 m_sText ，例如 CLabelUI CTextUI CEditUI等需要显示文字的控件。 当改变文字时会调用 Invalidate() 进行重绘
• bool IsResourceText() const 和 void SetResourceText(bool bResource) 这个函数具体使用场合可以参考帖子：Duilib 源码分析之 CResourceManager 篇
• bool IsDragEnabled() const 和 void SetDragEnable(bool bDrag) 判断或设置控件是否可拖拽
• bool IsDropEnabled() const 和 void SetDropEnable(bool bDrop) 判断或设置控件可放置拖拽过来的内容
• LPCTSTR GetGradient() 和 void SetGradient(LPCTSTR pStrImage) 判断或设置背景色的渐变方向，默认是垂直渐变，若设置 m_sGradient = L"hor"则会进行水平方向的渐变，通过改变 void CRenderEngine::DrawGradient(HDC hDC, const RECT& rc, DWORD dwFirst, DWORD dwSecond, bool bVertical, int nSteps) 中的 bVertical 来控制的
• DWORD GetBkColor() const 和 void SetBkColor(DWORD dwBackColor) (Color2 和 Color3 对应的函数不再列出)。 获取和设置背景色，当有两种背景色时，绘制渐变色；当有三种渐变色时，从开始到中间进行 Color 到 Color2 的渐变，从中间到最后进行 Color2 到 Color3 的渐变
• LPCTSTR GetBkImage() 和 void SetBkImage(LPCTSTR pStrImage) 获取或设置控件的背景图片，在绘制控件时作为背景图片，控件本身图片或文字的绘制后于背景图片的绘制
• LPCTSTR GetForeImage() 和 void SetForeImage(LPCTSTR pStrImage) 获取或设置控件的前景图片，在绘制控件时作为前景图片，控件本身图片或文字的绘制先于前景图片的绘制
• DWORD GetFocusBorderColor() const 和 void CControlUI::SetFocusBorderColor(DWORD dwBorderColor) 获取或设置控件在获取焦点情况下的边框颜色，成员变量 m_dwFocusBorderColor 用于 void CControlUI::PaintBorder(HDC hDC)方法中。 当 m_dwFocusBorderColor 改变时会进行重绘。
• bool IsColorHSL() const 和 void SetColorHSL(bool bColorHSL) 是否使用 HSL 色彩空间 ，关于 HSL 可参考百度百科：HSL， 在 m_bColorHSL 为 true 的情况下，会对当前的颜色进行调整，且是基于 CPaintManagerUI 中的 HSL 进行调整，先将当前颜色转成 HSL, 当把转换后的 HSL 的 H 进行处理： fH += (H - 180); ，这其中我也暂时没弄明白为什么要做 H - 180 操作 (H 值是 CPaintManagerUI 中的成员 m_H 的值，虽然说默认为 180)
• SIZE GetBorderRound() const 和 void SetBorderRound(SIZE cxyRound) 获取或设置边框圆角的椭圆大小
• bool DrawImage(HDC hDC, LPCTSTR pStrImage, LPCTSTR pStrModify = NULL) 绘制控件的图片，例如绘制一个图片代表按钮，上面再绘制文字
• int GetBorderSize() const 等一系列和边框大小相关的方法就不一一介绍了
• int GetBorderStyle() const 和 void SetBorderStyle(int nStyle) 边框的样式 (Pen 的样式)，默认为 PS_SOLID，代表实线，还可以设置 PS_DASH PS_DOT等各种虚线样式等 。 关于如何绘制边框可以参考：Duilib 源码分析之 PaintBorder 篇
• 控件位置相关方法暂不做介绍
• CDuiString GetToolTip() const 和 void SetToolTip(LPCTSTR pstrText) 获取或设置 Tooltip，当鼠标悬停到控件上时 popup 出来的一个文字提示框 。 具体实现方式可以参考 Duilib 源码分析之 ToolTip 篇
• void SetToolTipWidth(int nWidth) 和 int GetToolTipWidth(void) ToolTip 单行的最大宽度
• WORD GetCursor() 和 void SetCursor(WORD wCursor) 获取和设置鼠标移动到控件上时鼠标的样式。在控件的 GetControlFlags() 有 UIFLAG_SETCURSOR 属性的前提下会读取鼠标显示进行显示
• TCHAR GetShortcut() const 和 void SetShortcut(TCHAR ch) 获取或设置控件的快捷键，主要用于按钮、菜单项等，在按下 (Alt + 快捷键字母) 的情况下相应事件。 快捷键相关实现可以参考： Duilib 源码分析之 Shortcut 篇
• bool IsContextMenuUsed() const 和 void SetContextMenuUsed(bool bMenuUsed) 判断或设置是否有鼠标右键单击后弹出菜单的功能，在设置为 true 的情况下，则需要相应 DUI_MSGTYPE_MENU 事件
• const CDuiString& GetUserData() void SetUserData(LPCTSTR pstrText) UINT_PTR GetTag() const void SetTag(UINT_PTR pTag) 这 4 个是辅助函数，用户可以将任意一个字符串或者一个指针绑定到这个控件上
• bool IsVisible() const 和 void SetVisible(bool bVisible = true) 判断或设置控件是否可见，当改变控件的可变状态时会进行重绘
• void SetInternVisible(bool bVisible = true) (待更新)
• bool IsEnabled() const 和 void SetEnabled(bool bEnable = true) 判断或设置控件是否可用，不可用状态下的点击、鼠标进入等事件不会再相应。且可分别为控件设置可用和不可用状态下不同的样式，例如背景色的改变
• bool IsMouseEnabled() const 和 void SetMouseEnabled(bool bEnable = true) 设置为 false 后，会禁用当前控件的鼠标事件，如鼠标移动、单击、双击、右键、滚轮操作
• bool IsKeyboardEnabled() const 和 void SetKeyboardEnabled(bool bEnable = true) 若设置为 true，则按钮可以通过 tab 按键设置选中状态，且在选中状态下，可以通过按空格或回车键实现点击事件
• bool IsFocused() const 和 void SetFocus() 判断当前控件是否已设置焦点，或设置当前焦点在当前控件上。 注意此时的 “焦点” 指的是逻辑焦点，实际的焦点是在当前窗口上的
• bool IsFloat() const 和 void SetFloat(bool bFloat = true) 当前控件若此属性为 true ，则此控件在计算位置时不收其他控件的影响，没有相对位置的关系。而只是和父控件的位置有关，此控件的 pos 是相对于父控件的
• CControlUI* FindControl(FINDCONTROLPROC Proc, LPVOID pData, UINT uFlags) 根据 Proc 定义的方法查找符合 uFlags 的控件
• void Invalidate() 重绘当前控件，重绘前会循环取得当前控件和父控件的交集矩形区域，然后重绘此矩形
• bool IsUpdateNeeded() const void NeedUpdate() void NeedParentUpdate() (待更新)
• DWORD GetAdjustColor(DWORD dwColor) 若 m_bColorHSL 为 true ，则根据当前控件的 HSL 调整当前颜色，相关解释可参考方法 bool IsColorHSL() const 但其中的源码含义还不清楚
• void Init() void DoInit() ?? 调用时机?
• void Event(TEventUI& event) void DoEvent(TEventUI& event) 控件相应事件，简单的时间相应在对应的控件内直接实现，另有一些需要用户自定义行为，例如按钮按下后的动作，此时会通过调用 void SendNotify(CControlUI* pControl, LPCTSTR pstrMessage, WPARAM wParam = 0, LPARAM lParam = 0, bool bAsync = false) 发送给监听者，收到消息后，根据消息类型和对应的具体控件执行特定的动作
• void AddCustomAttribute(LPCTSTR pstrName, LPCTSTR pstrAttr) LPCTSTR GetCustomAttribute(LPCTSTR pstrName) const bool RemoveCustomAttribute(LPCTSTR pstrName) void RemoveAllCustomAttribute() 在 xml 中定义控件属性时，除了 Duilib 中支持的属性，如果我们随意自定义属性的话，就会存到 m_mCustomAttrHash中，当需要使用自定义属性的时候，可以再通过 GetCustomAttribute获取。 感觉这相当于临时增加某个对象的成员变量的用法一样，可以在需要的时候适当使用。
• void SetAttribute(LPCTSTR pstrName, LPCTSTR pstrValue) 对控件设置属性。 在初始解析 xml 时会分别设置我们写在 xml 中的属性，当然也可以在代码中随时对控件增加或者改变某属性，如果是设置大小颜色背景图之类的则会引起重绘
• CControlUI* ApplyAttributeList(LPCTSTR pstrList) 前一个 SetAttribute 是对某一个属性进行设置，而这个方法可以同时设置多个属性，传入的参数是属性的字符串，例如传入字符串 “width=\”50\” height=\”50\”“
• SIZE EstimateSize(SIZE szAvailable) 计算控件的宽高，不同的控件大多计算方法不同，例如 UIEdit 则是根据文字来计算大小
• void DoPaint(HDC hDC, const RECT& rcPaint) void PaintBkColor(HDC hDC) void PaintBkImage(HDC hDC) void PaintStatusImage(HDC hDC) void PaintForeColor(HDC hDC) void PaintForeImage(HDC hDC) void PaintText(HDC hDC) void PaintBorder(HDC hDC) 绘制控件，绘制的顺序也是按照这些函数的顺序绘制的，先绘制背景色，最后绘制边框
• void DoPostPaint(HDC hDC, const RECT& rcPaint) (待更新)
• CDuiString GetVirtualWnd() const (待更新)