a

2026-07-03 16:05:30 +08:00
commit df489d5640
1101 changed files with 779140 additions and 0 deletions
@@ -0,0 +1,434 @@
+# 主界面
+
+<cite>
+**本文引用的文件**
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp)
+- [MainFrm.h](file://h/MainFrm.h)
+- [Splash.cpp](file://cpp/Views/Splash.cpp)
+- [Splash.h](file://h/Splash.h)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp)
+- [ChildFrm.cpp](file://cpp/Views/ChildFrm.cpp)
+- [ChildFrm.h](file://h/ChildFrm.h)
+- [Resource.h](file://Resource.h)
+- [GeoMative.rc2](file://res/GeoMative.rc2)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向用户与开发者，系统性阐述主界面（CMainFrame）的布局结构、菜单系统、工具栏、状态栏与多文档界面（MDI）架构；解释应用启动初始化流程与主窗口的消息映射机制；结合MFC资源定义说明界面元素的可视化设计与事件绑定方式；提供主界面导航指南（窗口切换、视图管理与快捷操作）；并给出开发者扩展方法（新增菜单项、集成自定义视图、处理WM_COMMAND消息）。同时覆盖启动画面（Splash）的显示逻辑与UI状态同步机制。
+
+## 项目结构
+主界面相关的核心文件集中在 Views 与 Main 目录：
+- 主框架：cpp/Views/MainFrm.cpp、h/MainFrm.h
+- 启动画面：cpp/Views/Splash.cpp、h/Splash.h
+- 应用入口与初始化：cpp/Main/GeoMative.cpp
+- 子框架（MDI子窗口）：cpp/Views/ChildFrm.cpp、h/ChildFrm.h
+- 资源与ID定义：Resource.h、res/GeoMative.rc2
+
+```mermaid
+graph TB
+subgraph "应用层"
+App["CGeoMativeApp<br/>应用入口与初始化"]
+end
+subgraph "主界面层"
+MainFrm["CMainFrame<br/>主MDI框架"]
+ToolBar["CToolBar<br/>工具栏"]
+StatusBar["CStatusBar<br/>状态栏"]
+Splash["CSplashWnd<br/>启动画面"]
+end
+subgraph "子窗口层"
+ChildFrm["CChildFrame<br/>MDI子窗口"]
+ChildView["CChildView<br/>子窗口视图"]
+end
+subgraph "资源层"
+ResH["Resource.h<br/>资源ID常量"]
+RC2["GeoMative.rc2<br/>非可编辑资源"]
+end
+App --> MainFrm
+MainFrm --> ToolBar
+MainFrm --> StatusBar
+App --> Splash
+MainFrm --> ChildFrm
+ChildFrm --> ChildView
+ResH --> MainFrm
+ResH --> Splash
+RC2 --> App
+```
+
+图表来源
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L190-L230)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L164-L224)
+- [ChildFrm.cpp](file://cpp/Views/ChildFrm.cpp#L85-L118)
+- [Resource.h](file://Resource.h#L17-L20)
+- [GeoMative.rc2](file://res/GeoMative.rc2#L1-L14)
+
+章节来源
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L190-L230)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L164-L224)
+- [ChildFrm.cpp](file://cpp/Views/ChildFrm.cpp#L85-L118)
+- [Resource.h](file://Resource.h#L17-L20)
+- [GeoMative.rc2](file://res/GeoMative.rc2#L1-L14)
+
+## 核心组件
+- CMainFrame：继承自 CMDIFrameWnd，负责主MDI框架的创建、工具栏/状态栏初始化、菜单命令分发、MDI子窗口管理、消息映射与UI状态更新。
+- CChildFrame：MDI子窗口，承载视图控件，处理焦点与命令转发。
+- CSplashWnd：启动画面窗口类，负责显示与定时关闭。
+- CGeoMativeApp：应用入口，负责初始化数据库、网络、线程、语言设置、主窗口创建与显示。
+
+章节来源
+- [MainFrm.h](file://h/MainFrm.h#L12-L118)
+- [ChildFrm.h](file://h/ChildFrm.h#L12-L62)
+- [Splash.h](file://h/Splash.h#L12-L56)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L139-L230)
+
+## 架构总览
+主界面采用经典的MFC MDI架构：
+- 应用启动时由 CGeoMativeApp 创建并显示 CMainFrame。
+- CMainFrame 在 OnCreate 中创建工具栏与状态栏，并通过资源ID加载工具栏位图。
+- 启动画面通过 CSplashWnd::ShowSplashScreen 在主窗口创建前显示，随后在初始化流程中逐步完成数据库连接、网络初始化、线程启动与UI状态更新。
+- MDI子窗口通过 CChildFrame 承载视图，支持多文档切换与管理。
+
+```mermaid
+sequenceDiagram
+participant App as "CGeoMativeApp"
+participant Frame as "CMainFrame"
+participant Splash as "CSplashWnd"
+participant Child as "CChildFrame"
+participant View as "CChildView"
+App->>App : 初始化数据库/网络/线程/语言
+App->>Splash : EnableSplashScreen()
+App->>Frame : new CMainFrame / LoadFrame()
+App->>Frame : ShowWindow(SW_SHOWMAXIMIZED)
+Frame->>Splash : ShowSplashScreen(Frame)
+Splash-->>Frame : 定时器触发/鼠标键盘事件隐藏
+Frame->>Frame : OnCreate() 创建工具栏/状态栏
+App->>App : 初始化完成，更新状态栏
+Frame->>Child : CreateNewChild(...) 创建MDI子窗口
+Child->>View : OnCreate() 创建视图
+```
+
+图表来源
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L139-L230)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L164-L224)
+- [Splash.cpp](file://cpp/Views/Splash.cpp#L45-L142)
+- [ChildFrm.cpp](file://cpp/Views/ChildFrm.cpp#L85-L118)
+
+## 详细组件分析
+
+### 主框架（CMainFrame）布局与消息映射
+- 布局结构
+  - 工具栏：在 OnCreate 中创建并停靠，使用资源ID加载工具栏位图。
+  - 状态栏：在 OnCreate 中创建并设置指示器数组。
+  - MDI子窗口：通过 OnMngDataWin、OnMngExecWin、OnMngDevWin 等命令创建或激活对应子窗口。
+- 消息映射
+  - BEGIN_MESSAGE_MAP 到 END_MESSAGE_MAP 映射了大量命令与消息，包括文件导入导出、测试窗口、同步、设备检测、语言切换、网络响应、升级通知等。
+  - WM_COMMAND 通过 ON_COMMAND 绑定到具体处理函数，如 OnFileExp、OnFileImp、OnTestrspWin、OnSynWin 等。
+  - 自定义消息通过 ON_MESSAGE 绑定，如 WM_SCHEDULE、WM_REFRESH、WM_NEWLINK、WM_BREAKLINE、WM_UPG_GEOMATIVE 等。
+  - 鼠标提示通过 ON_NOTIFY_EX(TTN_NEEDTEXT,0,OnToolTipText) 实现。
+- 启动画面集成
+  - 在 OnCreate 中调用 CSplashWnd::ShowSplashScreen(this)，并在短暂休眠后继续初始化流程。
+
+```mermaid
+classDiagram
+class CMainFrame {
+LoadFrame(nIDResource, dwDefaultStyle, pParentWnd, pContext)
+OnCreate(lpCreateStruct)
+OnMngDataWin()
+OnMngExecWin()
+OnMngDevWin()
+OnFileExp()
+OnFileImp()
+OnTestrspWin()
+OnSynWin()
+OnLoggingTest()
+OnSetLinkUsb()
+OnSetLinkBluetooth()
+OnHelpUpg()
+OnLicenseUpg()
+OnPasswordManage()
+OnShowGeoWebsite()
+OnChangeChinese()
+OnChangeEnglish()
+OnDeviceChange(nEventType, dwData)
+OnTimer(nIDEvent)
+OnToolTipText(nID, pNMHDR, pResult)
+OnSchedule(wParam, lParam)
+OnRefresh(wParam, lParam)
+OnNewLink(wParam, lParam)
+OnBreakLine(wParam, lParam)
+OnUpgGeomative(wParam, lParam)
+DetectLine(wParam, lParam)
+CloseWindows(wParam, lParam)
+OnClearUpgInfo(wParam, lParam)
+OnShowUpgInfo(wParam, lParam)
+OnChangeLanguage(wParam, lParam)
+OnMsgNotifyDeviceOnOrOff(wParam, lParam)
+OnRefreshMainWndMenu(wParam, lParam)
+GetToolBar()
+SetStatusText(strText)
+GetGeoMativeVersion()
+LastErrorEx()
+}
+class CMDIFrameWnd
+CMainFrame --|> CMDIFrameWnd
+```
+
+图表来源
+- [MainFrm.h](file://h/MainFrm.h#L12-L118)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L58-L94)
+
+章节来源
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L58-L94)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L164-L224)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L254-L328)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L330-L579)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L581-L622)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L624-L668)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L675-L753)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L755-L800)
+
+### 启动画面（CSplashWnd）
+- 显示逻辑
+  - EnableSplashScreen 控制是否启用启动画面。
+  - ShowSplashScreen 创建并显示启动画面窗口，居中显示，设置定时器在指定毫秒后自动隐藏。
+  - PreTranslateAppMessage 拦截键盘与鼠标消息以提前关闭启动画面。
+- UI状态同步
+  - 启动画面在主窗口创建前显示，主窗口初始化完成后通过 UpdateWindow 更新主界面状态。
+
+```mermaid
+sequenceDiagram
+participant App as "CGeoMativeApp"
+participant Frame as "CMainFrame"
+participant Splash as "CSplashWnd"
+App->>Splash : EnableSplashScreen(true)
+App->>Frame : new CMainFrame / LoadFrame()
+App->>Frame : ShowWindow()
+Frame->>Splash : ShowSplashScreen(Frame)
+Splash->>Splash : OnCreate() 居中/设置定时器
+Splash->>Splash : OnTimer() 定时器触发
+Splash->>Frame : HideSplashScreen() 销毁窗口
+Frame->>Frame : UpdateWindow() 刷新主窗口
+```
+
+图表来源
+- [Splash.cpp](file://cpp/Views/Splash.cpp#L45-L142)
+- [Splash.h](file://h/Splash.h#L12-L56)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L193-L194)
+
+章节来源
+- [Splash.cpp](file://cpp/Views/Splash.cpp#L45-L142)
+- [Splash.h](file://h/Splash.h#L12-L56)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L193-L194)
+
+### 子框架（CChildFrame）与视图（CChildView）
+- CChildFrame
+  - PreCreateWindow 修改创建样式，移除客户端边框。
+  - OnCreate 创建默认视图控件并占满客户区。
+  - OnSetFocus 将焦点传递给子视图。
+  - OnCmdMsg 优先让视图处理命令，否则交由父类处理。
+- CChildView
+  - 作为子窗口的默认视图，承载具体业务控件与交互。
+
+```mermaid
+classDiagram
+class CChildFrame {
+PreCreateWindow(cs)
+OnCreate(lpCreateStruct)
+OnSetFocus(pOldWnd)
+OnFileClose()
+OnCmdMsg(nID, nCode, pExtra, pHandlerInfo)
+-m_wndView : CChildView
+}
+class CMDIChildWnd
+class CChildView
+CChildFrame --|> CMDIChildWnd
+CChildFrame --> CChildView : "拥有"
+```
+
+图表来源
+- [ChildFrm.h](file://h/ChildFrm.h#L12-L62)
+- [ChildFrm.cpp](file://cpp/Views/ChildFrm.cpp#L18-L118)
+
+章节来源
+- [ChildFrm.cpp](file://cpp/Views/ChildFrm.cpp#L85-L118)
+- [ChildFrm.h](file://h/ChildFrm.h#L12-L62)
+
+### 菜单系统与工具栏
+- 资源ID
+  - 主工具栏资源ID：IDR_MAINFRAME
+  - 多种功能工具栏资源ID：如 IDR_TB_PRO_DB、IDR_TB_SPT_DB 等，分布在 Resource.h 中。
+- 菜单与命令
+  - 主框架的消息映射中包含大量命令处理函数，如 OnMngDataWin、OnMngExecWin、OnMngDevWin、OnFileExp、OnFileImp、OnTestrspWin、OnSynWin、OnLoggingTest、OnSetLinkUsb、OnSetLinkBluetooth、OnHelpUpg、OnLicenseUpg、OnPasswordManage、OnShowGeoWebsite、OnChangeChinese、OnChangeEnglish 等。
+- 事件绑定
+  - ON_COMMAND 将菜单项与处理函数绑定。
+  - ON_MESSAGE 将自定义消息与处理函数绑定。
+  - ON_NOTIFY_EX(TTN_NEEDTEXT,0,OnToolTipText) 提供工具提示文本。
+
+章节来源
+- [Resource.h](file://Resource.h#L17-L60)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L58-L94)
+
+### 状态栏与指示器
+- 指示器数组包含 ID_SEPARATOR、ID_INDICATOR_CAPS、ID_INDICATOR_NUM、ID_INDICATOR_SCRL 等标准指示器。
+- CMainFrame 提供 SetStatusText 方法用于更新状态栏第一指示器文本。
+
+章节来源
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L96-L102)
+- [MainFrm.h](file://h/MainFrm.h#L39-L46)
+
+### MDI子窗口管理与窗口切换
+- 管理窗口
+  - OnMngDataWin：创建或激活数据管理子窗口。
+  - OnMngExecWin：创建或激活执行/任务管理子窗口。
+  - OnMngDevWin：创建或激活设备管理子窗口。
+- 子窗口创建
+  - 通过 CreateNewChild(RUNTIME_CLASS(...), IDR_MAINFRAME) 创建子窗口。
+  - ShowWindow(SW_SHOWMAXIMIZED) 或 ActivateFrame() 激活窗口。
+- 视图管理
+  - CChildFrame 在 OnCreate 中创建默认视图控件，OnSetFocus 将焦点交给视图。
+  - OnCmdMsg 优先让视图处理命令，保证视图优先响应。
+
+章节来源
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L624-L668)
+- [ChildFrm.cpp](file://cpp/Views/ChildFrm.cpp#L85-L118)
+
+### 启动初始化流程与UI状态同步
+- 应用入口
+  - CGeoMativeApp::InitInstance 完成OLE初始化、3D控件启用、主窗口创建与显示、数据库连接、网络初始化、线程创建、语言设置、菜单刷新等。
+- UI状态更新
+  - 在数据库更新与初始化过程中，通过 SetStatusText 更新状态栏文本，向用户反馈进度。
+- 启动画面
+  - 在主窗口创建前显示启动画面，初始化完成后销毁并刷新主窗口。
+
+```mermaid
+flowchart TD
+Start(["应用启动"]) --> InitApp["CGeoMativeApp::InitInstance()"]
+InitApp --> OLEInit["初始化OLE/控件容器"]
+InitApp --> CreateFrame["创建并显示主窗口"]
+InitApp --> DBConn["连接数据库"]
+InitApp --> NetInit["网络初始化/线程启动"]
+InitApp --> LangCfg["语言设置/菜单刷新"]
+InitApp --> SplashShow["显示启动画面"]
+CreateFrame --> StatusReady["状态栏就绪"]
+DBConn --> StatusUpdates["更新状态栏"]
+NetInit --> StatusUpdates
+LangCfg --> StatusUpdates
+SplashShow --> SplashHide["启动画面隐藏"]
+StatusUpdates --> Ready(["应用就绪"])
+```
+
+图表来源
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L139-L230)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L370-L422)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L193-L194)
+
+章节来源
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L139-L230)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L370-L422)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L193-L194)
+
+## 依赖关系分析
+- 组件耦合
+  - CMainFrame 依赖 CDevMngFrame、CDataMngFrame、CSptMngFrame 等管理框架类，用于创建/激活对应MDI子窗口。
+  - CMainFrame 依赖 CScheduler 进行调度与UI刷新。
+  - CMainFrame 依赖 CSplashWnd 进行启动画面显示。
+  - CChildFrame 依赖 CChildView 作为默认视图。
+- 外部依赖
+  - 数据库连接：通过 ADO 连接 Access 数据库。
+  - 网络通信：网络初始化与工作线程启动。
+  - 系统线程：扫描设备线程、系统时间线程等。
+
+```mermaid
+graph LR
+MainFrm["CMainFrame"] --> DevMng["CDevMngFrame"]
+MainFrm --> DataMng["CDataMngFrame"]
+MainFrm --> SptMng["CSptMngFrame"]
+MainFrm --> Scheduler["CScheduler"]
+MainFrm --> Splash["CSplashWnd"]
+ChildFrm["CChildFrame"] --> ChildView["CChildView"]
+App["CGeoMativeApp"] --> MainFrm
+App --> DB["ADO数据库连接"]
+App --> Net["网络模块"]
+App --> Threads["系统线程"]
+```
+
+图表来源
+- [MainFrm.h](file://h/MainFrm.h#L12-L48)
+- [ChildFrm.h](file://h/ChildFrm.h#L12-L38)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L233-L292)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L578-L622)
+
+章节来源
+- [MainFrm.h](file://h/MainFrm.h#L12-L48)
+- [ChildFrm.h](file://h/ChildFrm.h#L12-L38)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L233-L292)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L578-L622)
+
+## 性能考虑
+- 启动画面显示时长：启动画面定时器与用户交互（键盘/鼠标）会尽快结束，避免阻塞主流程。
+- 线程与定时器：心跳包、设备扫描、市场数据上传等定时器需合理设置间隔，避免频繁唤醒影响性能。
+- 数据库连接：连接字符串与锁策略已配置，注意异常捕获与资源释放，避免阻塞UI线程。
+- 网络初始化：网络连接失败时及时提示并回退到离线模式，减少UI等待时间。
+
+[本节为通用指导，不直接分析具体文件]
+
+## 故障排查指南
+- 启动失败
+  - OLE 初始化失败：检查系统COM组件与权限，查看提示信息。
+  - 数据库连接失败：确认数据库路径与密码正确，检查Jet OLEDB驱动安装。
+  - 网络初始化失败：检查IP/端口配置与网络连通性。
+- 设备连接问题
+  - 设备掉线：OnBreakLine 处理设备断开，关闭串口并清理内存数据，必要时弹窗提示。
+  - 新设备连接：OnNewLink 处理新设备发现，自动注册与状态更新，必要时弹窗提示。
+- UI无响应
+  - 检查定时器与线程是否正常运行，避免长时间阻塞消息循环。
+  - 状态栏文本更新：通过 SetStatusText 反馈当前状态，便于定位问题阶段。
+
+章节来源
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L156-L170)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L279-L310)
+- [GeoMative.cpp](file://cpp/Main/GeoMative.cpp#L503-L521)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L254-L328)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L330-L579)
+
+## 结论
+CMainFrame 作为Geomative Studio的主界面核心，承担了MDI框架、工具栏/状态栏、菜单与命令处理、启动画面集成与UI状态同步等职责。通过清晰的消息映射与资源ID定义，实现了良好的可扩展性与可维护性。开发者可在现有基础上轻松添加新菜单项、集成自定义视图与处理WM_COMMAND消息，同时遵循现有的初始化流程与UI状态更新机制，确保应用稳定运行。
+
+[本节为总结性内容，不直接分析具体文件]
+
+## 附录
+
+### 开发者扩展指南
+- 添加新菜单项
+  - 在资源脚本中定义菜单项与图标ID（参考 Resource.h 中的IDR_*与IDD_*定义）。
+  - 在 MainFrm.h 的消息映射声明中添加对应处理函数原型。
+  - 在 MainFrm.cpp 的消息映射中添加 ON_COMMAND 绑定。
+  - 在 OnCreate 或相应时机更新菜单显示（如需要动态刷新）。
+- 集成自定义视图
+  - 在 ChildFrm.cpp 的 OnCreate 中创建自定义视图控件，或通过 CreateNewChild 动态创建。
+  - 确保视图优先处理命令，必要时重写 OnCmdMsg 并将未处理命令交由父类。
+- 处理WM_COMMAND消息
+  - 在 MainFrm.cpp 的消息映射中添加 ON_COMMAND 条目，实现具体业务逻辑。
+  - 对于复杂操作，建议封装到独立的管理器或对话框类中，保持消息处理函数简洁。
+- 启动画面与UI状态同步
+  - 使用 CSplashWnd::ShowSplashScreen 在主窗口创建前显示启动画面。
+  - 在初始化流程中通过 SetStatusText 更新状态栏，向用户反馈进度。
+  - 在异常或失败场景及时提示并引导用户检查配置。
+
+章节来源
+- [Resource.h](file://Resource.h#L17-L60)
+- [MainFrm.h](file://h/MainFrm.h#L59-L118)
+- [MainFrm.cpp](file://cpp/Views/MainFrm.cpp#L58-L94)
+- [ChildFrm.cpp](file://cpp/Views/ChildFrm.cpp#L85-L118)
+- [Splash.cpp](file://cpp/Views/Splash.cpp#L45-L142)