docs: explain shell activity and platform support boundaries

This commit is contained in:
2026-11-12 19:10:08 +08:00
parent c28c08a29a
commit 50571e156e
6 changed files with 50 additions and 1 deletions
+11
View File
@@ -12,6 +12,7 @@ use winit::{
/// The custom draggable row does not receive AppKit's titlebar double-click
/// action automatically. Use the native click count and native window actions.
/// 读取系统偏好的标题栏双击行为,委托原生窗口执行相应动作。
// shell/app 在自绘标题控制区左键按下时调用;true 表示本次双击已处理,调用方不再开始普通窗口拖动。
pub fn titlebar_double_click(window: &Window) -> bool {
// AppKit 必须在主线程调用;不在主线程、无有效句柄或句柄非 AppKit 时返回未处理。
let Some(main_thread) = MainThreadMarker::new() else {
@@ -26,6 +27,7 @@ pub fn titlebar_double_click(window: &Window) -> bool {
// SAFETY: called on the event-loop thread during a left-button press, with
// a live winit-owned NSView. No native object outlives the Window borrow.
unsafe {
// 从当前 AppKit 事件读取原生 clickCount;无事件就不猜测双击,也不执行窗口动作。
let Some(event) = NSApplication::sharedApplication(main_thread).currentEvent() else {
return false;
};
@@ -33,6 +35,7 @@ pub fn titlebar_double_click(window: &Window) -> bool {
if event.clickCount() != 2 {
return false;
}
// 借用 winit 提供的活动 NSView,再取得所属 NSWindow;不创建窗口或把原生指针保存到外部状态。
let view = &*handle.ns_view.as_ptr().cast::<NSView>();
let Some(native) = view.window() else {
return false;
@@ -41,6 +44,7 @@ pub fn titlebar_double_click(window: &Window) -> bool {
if native.styleMask().contains(NSWindowStyleMask::FullScreen) {
return true;
}
// 读取系统标题栏双击设置,字符串转成 Rust 自有值后按约定选原生动作。
let action = NSUserDefaults::standardUserDefaults()
.stringForKey(&NSString::from_str("AppleActionOnDoubleClick"))
.map(|value| value.to_string());
@@ -58,7 +62,9 @@ pub fn titlebar_double_click(window: &Window) -> bool {
/// Called only on winit's main thread, after native creation and before drawing.
/// AppKit can restore its default button positions when laying out the title bar.
/// 调整真实 macOS 窗口三键的位置,与全尺寸内容和侧栏控制区对齐。
// shell/app 创建窗口后和绘制前调用;主线程调用由外层保证,此函数本身没有创建 MainThreadMarker 检查。
pub fn align_controls(window: &Window) {
// 取得当前 Window 的句柄,失败或非 AppKit 平台表示无法调整,返回不改变现有原生布局。
let Ok(handle) = window.window_handle() else {
return;
};
@@ -76,6 +82,7 @@ pub fn align_controls(window: &Window) {
if native.styleMask().contains(NSWindowStyleMask::FullScreen) {
return;
}
// 读取内容视图边界,用与侧栏相同的 HEADER 高度确定标题行中心。
let bounds = view.bounds();
let center = f64::from(crate::sidebar::HEADER) / 2.0;
// AppKit 视图可能以左下或左上为原点;先在内容视图内算标题行中心,再转到按钮父视图。
@@ -84,19 +91,23 @@ pub fn align_controls(window: &Window) {
} else {
bounds.origin.y + bounds.size.height - center
};
// 只处理关闭、最小化和缩放三个真实系统按钮,不创建伪按钮代替原生交互。
for kind in [
NSWindowButton::NSWindowCloseButton,
NSWindowButton::NSWindowMiniaturizeButton,
NSWindowButton::NSWindowZoomButton,
] {
// 系统样式可能不提供某个按钮,缺失时跳过该项,其他按钮仍继续对齐。
let Some(button) = native.standardWindowButton(kind) else {
continue;
};
// 需要按钮父视图做坐标转换;没有父视图时不能直接写内容视图坐标。
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.