#ifndef __DUILIB_DIAG_H__
#define __DUILIB_DIAG_H__

#pragma once

// =============================================================================
// 诊断日志的**唯一出口**。
//
// 为什么需要它：
//   历史上 DuiLib 的触摸诊断函数 `TouchTrace::Log` 定义在 UIManager.cpp 的
//   **匿名 namespace** 里 —— 匿名命名空间是内部链接，别的 .cpp（如 Control/UIButton.cpp）
//   根本引用不到。当时为了跨 .cpp 写日志，一度在 UIButton.cpp 里直接抄了一份
//   写文件的代码，因为复制粘贴的路径/格式逻辑太脏而被删掉；随后才有了本模块。
//
//   **现在 UIManager.cpp / UIBase.cpp / UIButton.cpp 的所有诊断调用都已统一走这里**
//   （原先 UIManager.cpp 自己那份本地实现已删除，UIBase.h 里的声明也一并删了）。
//   全库只有本 .cpp 真正落盘，格式 `[tick][tid] 文本`，UTF-8，
//   追加写 exe 同目录 touch_trace.log。
//
// ⚠️ 本模块纯粹是诊断用，不参与任何业务逻辑。问题定位后可以整体删除：
//    删除时把全库的 `DuiLibDiag::` 调用一并去掉（搜索 `DuiLibDiag::` 与 `UIDiag.h` 确认无遗漏）。
//
// ⚠️ 要**关日志**：改 UIDiag.cpp 里 `Enabled()` 的返回值即可，别去调用点加条件 ——
//    否则以后想再开就得满库找开关。
// =============================================================================

namespace DuiLibDiag
{
	// 写 exe 同目录 touch_trace.log。
	void Log(LPCTSTR fmt, ...);

	// 【R49d · 临时诊断】键盘"谁收到了"追踪专用通道。
	//
	// 与 Log() 的区别：
	//   · **不受 Enabled() 开关控制** —— 由 UIDiag.cpp 里的 kKeyTrace 独立开关（默认开）；
	//   · 写**另一个文件** dlgkey_trace.log（与 touch_trace.log 分开，便于单独回传）；
	//   · 只被极少量调用点使用（真模态弹框的键盘 / 命令消息），量极小，长期开着也无妨。
	// 问题定位后连同调用点一起删除。
	void LogKey(LPCTSTR fmt, ...);

	// 按钮被激活时的现场快照。用途：
	//   · 定位"弹框刚出来就被自动点掉"——会看到弹框内的按钮在弹框创建后
	//     极短时间内被激活，且 mgrCaptured=0；
	//   · 定位"单击穿透到背后的商品控件"——会看到主窗口控件在弹框存活期间被激活。
	// captureState: 管理器的 IsCaptured()
	// buttonState : 按钮的 m_uButtonState（含 UISTATE_HOT / PUSHED / CAPTURED 等位）
	// pushed      : 是否带 UISTATE_PUSHED
	void LogButtonActivate(LPCTSTR name, bool captureState, unsigned buttonState, bool pushed);
}

#endif // __DUILIB_DIAG_H__