docs: 逐模块细化中文逻辑注释并覆盖测试与示例

This commit is contained in:
2026-11-12 10:31:35 +08:00
parent d29a1be329
commit cd23e70db1
123 changed files with 2664 additions and 249 deletions
+7
View File
@@ -13,6 +13,7 @@ use winit::{
/// action automatically. Use the native click count and native window actions.
/// 读取系统偏好的标题栏双击行为,委托原生窗口执行相应动作。
pub fn titlebar_double_click(window: &Window) -> bool {
// AppKit 必须在主线程调用;不在主线程、无有效句柄或句柄非 AppKit 时返回未处理。
let Some(main_thread) = MainThreadMarker::new() else {
return false;
};
@@ -28,6 +29,7 @@ pub fn titlebar_double_click(window: &Window) -> bool {
let Some(event) = NSApplication::sharedApplication(main_thread).currentEvent() else {
return false;
};
// 依赖系统原生连击计数,不自行推算两次输入时间,保持用户设置与系统行为一致。
if event.clickCount() != 2 {
return false;
}
@@ -35,12 +37,14 @@ pub fn titlebar_double_click(window: &Window) -> bool {
let Some(native) = view.window() else {
return false;
};
// 全屏时把双击视作已处理,但不执行缩放/最小化,避免自绘标题行改变全屏状态。
if native.styleMask().contains(NSWindowStyleMask::FullScreen) {
return true;
}
let action = NSUserDefaults::standardUserDefaults()
.stringForKey(&NSString::from_str("AppleActionOnDoubleClick"))
.map(|value| value.to_string());
// 按系统偏好执行动作;缺省采用 Zoom,禁用或未知选项不动作,但仍返回已处理。
match action.as_deref() {
Some("Minimize") => native.performMiniaturize(None),
None | Some("Maximize" | "Fill") => native.performZoom(None),
@@ -74,6 +78,7 @@ pub fn align_controls(window: &Window) {
}
let bounds = view.bounds();
let center = f64::from(crate::sidebar::HEADER) / 2.0;
// AppKit 视图可能以左下或左上为原点;先在内容视图内算标题行中心,再转到按钮父视图。
let content_y = if view.isFlipped() {
bounds.origin.y + center
} else {
@@ -90,10 +95,12 @@ pub fn align_controls(window: &Window) {
let Some(parent) = button.superview() else {
continue;
};
// 按钮可能位于不同 AppKit 容器,必须使用 convertPoint 而不能直接赋内容视图坐标。
let target = parent.convertPoint_fromView(NSPoint::new(0.0, content_y), Some(view));
let frame = button.frame();
let y = target.y - frame.size.height / 2.0;
// Preserve native button size, horizontal spacing and behavior.
// 只改变足够明显的纵向偏差,保留系统按钮横向间距、尺寸与原生动作,避免反复微调布局。
if (frame.origin.y - y).abs() > 0.01 {
button.setFrameOrigin(NSPoint::new(frame.origin.x, y));
}