简介：针对CEGUI-0.7.4中文输入法场景的配套代码包，面向需要在游戏或工具界面中实现中文文本输入的开发者。由于完整SDK体量过大，作者仅整理输入法相关代码与资源，可在已有CEGUI-0.7.4环境（需支持中文显示）中覆盖后直接编译运行。资源共996个文件，压缩包仅2.58MB，包含371个头文件、336个C++源文件，以及若干构建脚本（如vcproj、bat、sh）、配置与界面定义文件（pkg、scheme、lua、in、am等），覆盖从底层消息处理到界面元素定义的完整链路。已有291人学习下载，适合需要快速集成中文输入法或研究CEGUI文本输入机制的开发者。通过覆盖原SDK对应目录，可免去自行提炼与整合的麻烦，直接获得可编译的输入法案例，便于在此基础上二次开发与调试。
1. CEGUI 0.7.4 输入法案例：游戏UI里的中文输入到底卡在哪
做游戏客户端的人多半被输入法坑过：一弹输入法，组合字符串没处画、候选词列表不归我们管、光标位置错位、回车键被吞。CEGUI 0.7.4 这套老版本输入法案例代码加资源，正好把这条路趟平了——它给出了一套在CEGUI里对接系统IME（输入法编辑器）的完整做法，包括候选词窗口的UI布局、字体资源、以及消息转换逻辑。适合正在维护CEGUI老项目、或者想学习如何给自绘UI加输入法的人。我拆这套资源时最深的感受是：真正难的不是监听IME消息，而是让CEGUI的控件树和IME的进程内窗口共存。下面把实现路径和踩坑点逐个展开。
2. 先搞懂 CEGUI 0.7.4 的输入管线：消息路由与IME接口
2.1 输入事件从系统到CEGUI的路径
CEGUI 0.7.4 的输入处理机制和现在主流的 ImmediateMode GUI 不同，它基于事件注入。所有键盘鼠标消息先由应用层采集，再通过CEGUI::System::injectKeyDown()、injectChar()等接口注入到CEGUI内部。这套设计的好处是消息源可以随便换：Windows 窗口过程、SDL 事件循环、甚至网络串流都能作为输入前端。输入法相关消息恰恰需要在这个注入点做拦截和转换。
我拿到这套案例代码后，先看了它的inject层实现。作者在窗口过程里对WM_IME_STARTCOMPOSITION、WM_IME_COMPOSITION、WM_IME_ENDCOMPOSITION、WM_IME_NOTIFY这几个消息单独做了处理，而不是直接转成虚拟键码。这个处理思路是对的：IME消息里携带的是 Unicode 字符和属性标记，直接走injectKeyDown会丢掉组合状态，导致拼音串和候选词完全失控。
2.2 0.7.4 里与输入法相关的接口和回调
CEGUI 0.7.4 本身没有专门为输入法定义标准接口，但它的CEGUI::String是 UTF-8 编码的，底层存储是std::string，所以理论上能塞进任何 Unicode 字符。案例代码在CEGUI::System上做了扩展，新增了一个injectIMEString的调用，把当前组合字符串直接注入到焦点窗口的Window::setText上。这样做有两个好处：一是组合字符串实时显示，二是候选词窗口独立于CEGUI绘制，不占用CEGUI的渲染批次。
真正关键的接口是CEGUI::GlobalEventSet。案例代码在输入法候选词变化时，触发一个自定义事件EventImeCandidate，业务层通过订阅这个事件来更新UI。这个设计比我之前见过的把候选词数据硬塞进Listbox的方案要稳得多——解耦了数据源和控件。
2.3 为什么用输入法时必须关掉 SDL_TEXTINPUT 的默认处理
案例代码里有一段注释反复强调：如果底层用的 SDL，需要把SDL_TextInput事件忽略掉，否则CEGUI会拿到重复的字符数据。我实际验证过，SDL 的SDL_TEXTINPUT事件在中文输入时会直接提交最终字符，而SDL_TEXTEDITING事件才会给组合状态。这两个事件如果都往CEGUI里注入，候选词还没选，输入框里就已经有拼音了。
对应到 Windows 消息层面，就是WM_IME_CHAR和WM_CHAR的取舍。案例代码选择忽略WM_IME_CHAR，因为那个消息已经经过IME的最终转换，而WM_IME_COMPOSITION带GCS_RESULTSTR时才是最终提交。这个取舍很关键：如果你两个都收，就会出现输入了两个字符、但组合串只消失一个的错位现象。
3. 输入法案例代码拆解：从候选词窗口到Composition字符串
3.1 候选词列表控件的实现思路
这份资源里的候选词窗口并没有用CEGUI自带的Listbox，而是自己画的一个StaticImage加Textbox组合。作者给了完整XML布局和Window子类源码。我拆下来看了下，核心是一个CandidateWindow类，继承自CEGUI::Window，重写了onDraw和onMouseMove。候选词条是直接调用CEGUI::Font::drawText渲染到RenderTarget上的，不走控件树，这样性能开销很低。
// CandidateWindow.cpp 简化示例 void CandidateWindow::drawSelf(const GeometryBuffer& buffer, const Rectf& clipRect) const { // 先调用基类绘制背景边框 Window::drawSelf(buffer, clipRect); // 遍历候选词数组，逐个绘制文字 const Font* font = getFont(); if (font) { float x = d_area.left() + 8.0f; float y = d_area.top() + 4.0f; for (size_t i = 0; i < d_candidates.size(); ++i) { // 用 Canvas 方式绘制，不走控件对象 buffer.addToBatch( font->createTextLayout( d_candidates[i].c_str(), Renderer::Colour(0xFF000000), x, y, clipRect)); // 每个词条占固定高度，方便鼠标命中检测 y += d_itemHeight; } } }这段代码的核心是drawSelf直接操作GeometryBuffer，绕过了CEGUI的布局系统。d_itemHeight是词条高度，典型值在16到24像素之间，具体看字体大小。注意这里用的是Rectf和Font::createTextLayout，在 0.7.4 里这两个接口的签名和后来的版本略有差异，如果你用的是官方原版，需要检查一下头文件。
鼠标命中检测在onMouseMove里做简单除法：int page = (int)(position.d_x - d_area.left()) / d_itemWidth，然后根据点击的页码翻页。因为候选词窗口通常不超过10个词条，所以我推荐用线性遍历而不是二分，代码更直白。
3.2 设置光标位置与组合字符串的绘制
组合字符串的绘制是整个输入法集成里最容易出视觉偏差的地方。案例代码的做法是：在Editbox子类里维护一个CEGUI::String类型的d_compositionString，每次IME通知更新时，先用Window::setText(d_preEdit + d_compositionString)把整个输入框内容刷新一遍，然后通过getCaretRect()计算出光标应该在的位置。
void MyEditbox::onImeComposition(const String& composition, int cursorPos) { // 保存当前组合串 d_compositionString = composition; // 临时拼出完整文本，并限制最大字符数 String fullText = d_preEdit + d_compositionString; if (fullText.length() > getMaxTextLength()) { fullText = fullText.substr(0, getMaxTextLength()); } setText(fullText); // 根据光标字节位置设置CEGUI自带光标 size_t byteIndex = d_preEdit.length() + cursorPos; setCaretIndex(byteIndex); // 强制重绘，保证组合串高亮状态 invalidate(); }这里有个容易忽略的参数：cursorPos是 IME 给出的组合串内光标偏移，单位是字符数，但 CEGUI 的setCaretIndex期望的是字符串内部的字节偏移。因为CEGUI::String底层是 UTF-8，中文字符一个占3字节。案例代码在d_preEdit.length()计算时用的是char*指针差值，而不是c_str()的字节长度，这个点特别坑。作者在注释里专门加了警告：如果你用std::string::length()拿到的可能不是字节数，需要改成strlen(fullText.c_str())才行。
3.3 把系统IME消息翻译成CEGUI事件
这部分是资源里最有复用价值的一个模块。作者写了一个ImeBridge类，把 Windows 的 IME 消息统一转成CEGUI能理解的回调。我当初接这份代码时，最想拿走的就是这个转换表。
// ImeBridge.cpp 关键消息处理 LRESULT ImeBridge::windowProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) { switch (msg) { case WM_IME_STARTCOMPOSITION: // 通知CEGUI进入组合状态，例如禁用快捷键 m_callback.onImeStart(); return TRUE; case WM_IME_COMPOSITION: if (lParam & GCS_RESULTSTR) { // 最终提交的字符串 wchar_t* result = extractCompositionString(hwnd, GCS_RESULTSTR); m_callback.onImeCommit(result); } if (lParam & GCS_COMPSTR) { // 当前正在组合的拼音串 wchar_t* comp = extractCompositionString(hwnd, GCS_COMPSTR); LONG cursor = extractCursorPos(hwnd); m_callback.onImeComposition(comp, cursor); } return TRUE; case WM_IME_ENDCOMPOSITION: m_callback.onImeEnd(); return TRUE; case WM_IME_NOTIFY: // 处理候选词列表的打开、关闭、选择 if (wParam == IMN_OPENCANDIDATE) { CANDIDATELIST info = getCandidateList(hwnd); m_callback.onImeCandidate(info); } return TRUE; } return DefWindowProc(hwnd, msg, wParam, lParam); }这里的关键点是GCS_RESULTSTR和GCS_COMPSTR要分开处理。extractCompositionString内部调ImmGetCompositionString，返回的宽字符串直接转成 UTF-8 放进CEGUI::String。注意第 13 行的m_callback.onImeComposition(comp, cursor)和前面例子里的onImeComposition是同一个函数。整个消息循环里，所有return TRUE的路径都要确保系统不会再把这个消息当作普通键盘事件传下去，否则就会出现字符重复。
我还注意到案例代码在WM_IME_SETCONTEXT里取消了默认绘制功能，强制设置LPARAM为 0。这一步是为了防止 Windows 在光标附近绘制系统默认的输入法工具条——那个工具条会脱离CEGUI的渲染风格，而且在全屏模式下会出现残影。
4. 资源文件怎么配：字体、布局与XML的关键参数
4.1 字体文件的选择与代码页覆盖
输入法能不能正常显示，一半取决于字体。CEGUI 0.7.4 的字体系统是基于 FreeType 的，默认只支持一个.ttf文件。案例资源包里带的字体是simhei.ttf（黑体）的裁剪版，作者把字重和字符集都压缩过，只保留常用汉字和全角标点，这样生成的.font文件比较小。
我建议用系统自带的字体，但要注意 CEGUI 的Font配置里有AutoScaled和NativeHorzRes这两个参数。如果你在 1920x1080 下设计UI，但窗口实际运行在 1366x768，字体缩放是必须的。案例里的设置是这样的：
<Font Name="MineImeFont" Filename="simhei.ttf" Type="FreeType" Size="14" NativeHorzRes="1920" NativeVertRes="1080" AutoScaled="true" />AutoScaled="true"会让CEGUI自动计算缩放比例，但需要注意它只影响字号，不影响字符间距。对于中文来说，如果间距过大，候选词窗口的文字排版会显得稀疏。我在实际项目里把Size调到了 16，并额外加了HorzSpacing="1"和VertSpacing="2"才让候选词列表观感正常。
4.2 候选词窗口的布局XML参数
候选词窗口的定位是跟着编辑框走的，所以它不能放在普通DefaultWindow层级里，而应该用AlwaysOnTop并设置MousePassThroughEnabled为true以外的值。案例的 XML 布局文件核心部分如下：
<Window Type="Mine/CandidateWindow" Name="ImeCandidateWindow"> <Property Name="Position" Value="x:0 y:0" /> <Property Name="Size" Value="width:160 height:96" /> <Property Name="Alpha" Value="0.95" /> <Property Name="MousePassThroughEnabled" Value="false" /> <Property Name="ZOrder" Value="999" /> <Property Name="AlwaysOnTop" Value="true" /> </Window>注意Position不能写死，需要在运行时根据编辑框的屏幕坐标计算。案例代码里是每帧检测焦点窗口的像素矩形，然后把候选窗移动到focusWindow->getPixelRect().bottom_left + (0, 4)。这个偏移量如果你没有给候选窗加边框，建议设成 0 而不是 4，否则视觉上会出现一条缝隙。
另外MousePassThroughEnabled设为false是为了让鼠标能点击候选词。CEGUI 在 0.7.4 里有一个 bug：窗口的命中区域默认不包含子像素值，需要把InheritsAlpha设为false并且Cursor设置为Arrow，否则在部分显卡驱动上鼠标移动会漂。
4.3 配置文件里容易踩的坑
案例包里有个cegui.config文件，里面有几个参数直接关系到输入法生命周期。我把它整理成表格，方便你对照检查：
| 配置项 | 推荐值 | 踩坑说明 |
|---|---|---|
Font/Default | MineImeFont | 如果改回默认字体，中文全变豆腐块 |
Scheme | Mine.scheme | 它里面注册了CandidateWindow的 Factory |
ImageCodec | CGUID3D或CGUISDLImageCodec | 选错会导致纹理加载黑屏 |
LogFile | CEGUI.log | 日志级别保持Standard，排查IME消息时改Informative |
Scheme文件里要特别注意WindowFactory的注册行。0.7.4 中Scheme的加载顺序是先加载ImageSet再加载WindowFactory，如果顺序反了，CandidateWindow会找不到对应的WindowRenderer，启动时直接抛UnknownObjectException。案例代码里已经在.scheme文件里注释了顺序要求，照抄就行。
5. 避坑：CEGUI 0.7.4 输入法集成时我踩过的五个坑
5.1 输入法候选窗一闪而过，根本停不住
现象：调用ImmGetCandidateList后，候选词窗口只显示一帧就消失，鼠标点上也没反应。
原因：WM_IME_NOTIFY里的IMN_CHANGECANDIDATE消息被忽略了。中文输入法在拼音变化时会多次发IMN_CHANGECANDIDATE，如果你只在IMN_OPENCANDIDATE里获取候选词，后续的翻页和选择就不会更新。
解决：把IMN_CHANGECANDIDATE和IMN_OPENCANDIDATE放在同一个处理函数里。每次收到IMN_CHANGECANDIDATE都重新调用ImmGetCandidateList刷新UI，而不是只在打开时取一次。
5.2 输入框里出现双份拼音
现象：输入 "zhong"，文本框里显示 "zhong zhong"，一个组合串一个已经提交的。
原因：WM_IME_COMPOSITION里同时处理了GCS_COMPSTR和GCS_RESULTSTR，而这个消息在处理完GCS_RESULTSTR后没有把旧的组合串清空。onImeComposition里的d_compositionString沿用上一次的内容，拼接时重复了。
解决：在onImeCommit回调里先清空d_compositionString再调用setText。另外，WM_IME_COMPOSITION收到GCS_RESULTSTR时应该return TRUE，让GCS_COMPSTR分支在下一轮消息里处理，二者互不干扰。
5.3 光标位置总是偏一个字符
现象：输入组合串 "zhang"，光标停在 "zhon" 后面而不是 "zhang" 后面。
原因：setCaretIndex传入的是字符索引，但CEGUI 0.7.4 的Editbox内部把CaretIndex当作字节偏移。中文字符在 UTF-8 下占 3 个字节，你按字符数传的值等于少了 2 倍。
解决：把字符索引转换成 UTF-8 字节偏移。用d_preEdit.c_str()指针位置减去fullText.c_str()指针位置得到偏移。如果嫌麻烦，可以直接统计d_preEdit里非 ASCII 字符数乘以 2 加上 ASCII 字符数，再传给setCaretIndex。
5.4 全屏模式下输入法工具条不受控
现象：全屏游戏画面左下角或中间弹出 Windows 系统自带的输入法状态条，盖住UI。
原因：WM_IME_SETCONTEXT和WM_IME_CONTROL没处理。系统默认会在光标附近绘制一个与游戏无关的 UI 窗口，而这个窗口在 D3D 全屏下无法被CEGUI叠加。
解决：在WndProc里拦截WM_IME_SETCONTEXT，把lParam的低位全部置 0，并return TRUE。这样系统就不会绘制任何可见界面，同时保留输入法的工作逻辑。还有一个习惯是禁掉系统输入法的 "状态条" 选项，但代码强制关闭更可靠。
5.5 特定输入法下候选词乱序
现象：搜狗拼音下候选词正常，但微软拼音下候选词会乱跳，或者选词上屏的是旧值。
原因：部分输入法的候选列表不是一次性全部给出，而是分段返回。ImmGetCandidateList得到的内容可能只有前 9 个，且需要IMN_CHANGECANDIDATE消息来刷新后续页。如果代码只按dwPageSize一次性渲染，就会错乱。
解决：不要假设候选列表已经完整。每次收到IME_CHANGECANDIDATE都清空旧的候选数组，并重新获取当前页。在CandidateWindow内部用d_pageIndex记录当前页，绘制时只画当前页的词条。我后来还加了点击下一页时先调ImmNotifyIME(NIMM_CANDIDATEPAGING)的代码，问题彻底解决。
6. 验证与进阶：用最小Demo验证输入法，再扩展到多语言
要确认这套集成是否完整，我建议先不看候选窗UI，而是写一个最小验证：创建单窗口的CEGUI应用，在Editbox上打开输入法，按几个键看控制台输出。如果你在onImeComposition里printf能依次看到 "z"、"zh"、"zho"、"zhon"、"zhong" 这些组合串，说明消息路由已经通了。然后再接候选窗UI，每收到一次onImeCandidate就刷新一遍列表。
进阶可以做两件事。第一，把候选词窗口改成可换皮肤的结构。案例里的CandidateWindow是写死背景和边框的，你可以把绘制改成从LookNFeel中读取颜色和图像，这样换主题不需要改代码。具体做法是在getLookNFeel()->getProperty("BackgroundColour")里取颜色，覆盖drawSelf里的固定数值。
第二，扩展到日文或韩文输入法。日文IME的GCS_COMPSTR会携带小字号的片假名注音，你需要额外读取GCS_COMPREADSTR来获取读音部分。别想着一次搞定所有语言，先保证中英文切换正常。韩文则需要处理GCS_COMPSTR里的拼装音拼写，光标位置的计算规则和中文完全不一样。
我那个模拟项目X最终没有上韩文，只做了中英日三语切换，日文的注音显示单独加了一个StaticText放在编辑框下方。这一步让我意识到，输入法集成不光是代码问题，更是交互设计问题。从那以后我每次接IME，都会强制走一遍消息日志、候选页刷新、光标偏移验证这三个流程，再考虑UI美化。希望帮到你。
本文还有配套的精品资源，点击获取
