247 lines
11 KiB
Rust
247 lines
11 KiB
Rust
//! 即时绘制控件的跨帧交互状态：稳定 WidgetId、悬停、按下捕获、键盘焦点和释放激活。
|
|
//! 控件用语义 key 标识，而不是屏幕位置或行号。释放时必须仍命中同一个启用目标，拖出控件不能意外触发点击。
|
|
//!
|
|
use crate::geometry::{Point, Rect};
|
|
use std::hash::{Hash, Hasher};
|
|
|
|
/// Stable across frames, resizing and text changes. Use semantic keys, never row indices.
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
|
|
/// 由语义 key 生成的稳定控件身份，跨帧移动和文字变化不应改变它。
|
|
pub struct WidgetId(u64);
|
|
impl WidgetId {
|
|
/// 对调用方语义 key 求哈希，生成不随控件位置或标签变化的跨帧 WidgetId；相同 key 会得到同一身份。
|
|
pub fn new(key: impl Hash) -> Self {
|
|
// 语义 key 哈希为会话内身份；不依赖布局坐标，但调用方仍需避免重复 key，哈希并非全局唯一保证。
|
|
let mut hash = std::collections::hash_map::DefaultHasher::new();
|
|
key.hash(&mut hash);
|
|
Self(hash.finish())
|
|
}
|
|
}
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
|
/// 分隔条和滚动条的操作方向。
|
|
pub enum Axis {
|
|
Horizontal,
|
|
Vertical,
|
|
}
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
|
/// 管理控件角色，决定焦点资格和系统光标。
|
|
pub enum Role {
|
|
Button,
|
|
Tab,
|
|
Toggle,
|
|
TextField,
|
|
Row,
|
|
Swatch,
|
|
Splitter(Axis),
|
|
Scrollbar(Axis),
|
|
}
|
|
impl Role {
|
|
/// 判断控件角色是否可以接受键盘焦点。
|
|
fn focusable(self) -> bool {
|
|
// 行用于指针选择，分隔条/滚动条用于拖动，这三类不加入键盘 Tab 焦点循环。
|
|
!matches!(self, Self::Splitter(_) | Self::Scrollbar(_) | Self::Row)
|
|
}
|
|
}
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
|
/// 宿主控件请求的系统光标种类。
|
|
pub enum Cursor {
|
|
Default,
|
|
Pointer,
|
|
Text,
|
|
ResizeHorizontal,
|
|
ResizeVertical,
|
|
Grab,
|
|
Disabled,
|
|
}
|
|
#[derive(Clone, Debug)]
|
|
/// 本帧可命中的管理控件，绑定几何、角色、启用条件与可选 action。
|
|
pub struct Target<A> {
|
|
pub id: WidgetId,
|
|
pub rect: Rect,
|
|
pub role: Role,
|
|
pub enabled: bool,
|
|
pub action: Option<A>,
|
|
}
|
|
#[derive(Clone, Copy, Debug)]
|
|
/// 绘制使用的组合交互状态，避免按钮自己重新推断焦点/捕获。
|
|
pub struct VisualState {
|
|
pub hovered: bool,
|
|
pub pressed: bool,
|
|
pub focused: bool,
|
|
pub selected: bool,
|
|
pub enabled: bool,
|
|
}
|
|
|
|
/// Retained input state for an immediate-mode frame. Actions fire on release inside
|
|
/// the same enabled control, so dragging away cancels a click.
|
|
#[derive(Clone, Debug, Default)]
|
|
/// 即时绘制之外保留的输入状态，确保按下与释放跨帧仍匹配同一控件。
|
|
pub struct Interaction {
|
|
pointer: Option<Point>,
|
|
hovered: Option<WidgetId>,
|
|
// 按下时捕获的控件；即使指针移动到别处，也保留原身份直到释放或取消。
|
|
pointer_active: Option<WidgetId>,
|
|
// 键盘按下时的焦点身份；释放时再次匹配，避免焦点已变却激活新控件。
|
|
key_active: Option<WidgetId>,
|
|
focused: Option<WidgetId>,
|
|
// 区分键盘导航和鼠标获得焦点，visual 仅为键盘来源显示焦点外观。
|
|
keyboard_focus: bool,
|
|
}
|
|
impl Interaction {
|
|
/// 按逆绘制顺序选择指针处的管理控件，避免重叠控件同时激活。
|
|
pub fn hit<'a, A>(&self, targets: &'a [Target<A>]) -> Option<&'a Target<A>> {
|
|
let p = self.pointer?;
|
|
// 几何命中包含禁用控件，因此上层禁用项会挡住下层项；是否允许操作由 press/cursor 分别判断。
|
|
targets.iter().rev().find(|t| t.rect.contains(p))
|
|
}
|
|
/// 更新指针与悬停目标，但不在移动时直接触发点击。
|
|
pub fn pointer_moved<A>(&mut self, p: Point, targets: &[Target<A>]) {
|
|
self.pointer = Some(p);
|
|
self.hovered = self.hit(targets).map(|t| t.id);
|
|
}
|
|
/// 清除离开窗口后的指针/悬停状态。
|
|
pub fn pointer_left(&mut self) {
|
|
// 离开窗口只清位置和悬停，保留捕获身份供外层拖动流程使用；完整失焦由 blur 处理。
|
|
self.pointer = None;
|
|
self.hovered = None;
|
|
}
|
|
/// 捕获启用控件的稳定身份，并按角色更新键盘焦点。
|
|
pub fn press<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<Target<A>> {
|
|
// 鼠标按下撤销旧键盘激活并关闭键盘焦点外观；点空白或不可聚焦角色会清除 focused。
|
|
self.key_active = None;
|
|
self.keyboard_focus = false;
|
|
let target = self.hit(targets).filter(|t| t.enabled).cloned();
|
|
self.pointer_active = target.as_ref().map(|t| t.id);
|
|
self.focused = target.as_ref().filter(|t| t.role.focusable()).map(|t| t.id);
|
|
target
|
|
}
|
|
/// 只有释放时仍处于原启用目标内才返回 action，拖出后释放不触发。
|
|
pub fn release<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<A> {
|
|
// take 先消费捕获，保证同一次按下最多激活一次；TextField 不走按钮 release action。
|
|
let active = self.pointer_active.take()?;
|
|
self.hit(targets)
|
|
.filter(|t| t.enabled && t.id == active && t.role != Role::TextField)
|
|
.and_then(|t| t.action.clone())
|
|
}
|
|
/// 撤销当前操作的后续交付资格，并执行对应取消清理。
|
|
pub fn cancel(&mut self) {
|
|
self.pointer_active = None;
|
|
self.key_active = None;
|
|
}
|
|
/// 撤销失焦后的键盘/指针激活状态，防止回到窗口时补发旧操作。
|
|
pub fn blur(&mut self) {
|
|
self.cancel();
|
|
self.focused = None;
|
|
self.keyboard_focus = false;
|
|
self.pointer_left();
|
|
}
|
|
/// 用本帧目标集合校正跨帧焦点和捕获，已消失控件不保留可激活身份。
|
|
pub fn reconcile<A>(&mut self, targets: &[Target<A>]) -> bool {
|
|
let before = (
|
|
self.hovered,
|
|
self.pointer_active,
|
|
self.focused,
|
|
self.key_active,
|
|
);
|
|
// 重建 UI 后必须仍存在且启用才保留焦点/捕获；hover 则依据当前指针重新命中，包含禁用项。
|
|
let exists = |id| targets.iter().any(|t| t.id == id && t.enabled);
|
|
self.focused = self.focused.filter(|id| exists(*id));
|
|
self.pointer_active = self.pointer_active.filter(|id| exists(*id));
|
|
self.key_active = self.key_active.filter(|id| exists(*id));
|
|
self.hovered = self.hit(targets).map(|t| t.id);
|
|
before
|
|
!= (
|
|
self.hovered,
|
|
self.pointer_active,
|
|
self.focused,
|
|
self.key_active,
|
|
)
|
|
}
|
|
/// 返回当前仍持有焦点的稳定控件身份。
|
|
pub fn focused<'a, A>(&self, targets: &'a [Target<A>]) -> Option<&'a Target<A>> {
|
|
targets
|
|
.iter()
|
|
.find(|t| Some(t.id) == self.focused && t.enabled)
|
|
}
|
|
/// 沿启用且可聚焦的目标循环导航，支持正向与反向遍历。
|
|
pub fn focus_next<A: Clone>(&mut self, targets: &[Target<A>], back: bool) -> Option<Target<A>> {
|
|
// 键盘导航先取消未完成按压，避免切换焦点后补发旧激活；候选顺序沿本帧目标顺序。
|
|
self.cancel();
|
|
self.keyboard_focus = true;
|
|
let candidates = targets
|
|
.iter()
|
|
.filter(|t| t.enabled && t.role.focusable())
|
|
.collect::<Vec<_>>();
|
|
if candidates.is_empty() {
|
|
self.focused = None;
|
|
return None;
|
|
}
|
|
let current = candidates.iter().position(|t| Some(t.id) == self.focused);
|
|
// 有当前焦点时环绕前进/后退；无有效焦点时正向选首项、反向选末项。
|
|
let index = match current {
|
|
Some(i) if back => (i + candidates.len() - 1) % candidates.len(),
|
|
Some(i) => (i + 1) % candidates.len(),
|
|
None if back => candidates.len() - 1,
|
|
None => 0,
|
|
};
|
|
let target = candidates[index];
|
|
self.focused = Some(target.id);
|
|
Some(target.clone())
|
|
}
|
|
/// 为当前焦点控件记录键盘激活，后续释放仍须匹配目标。
|
|
pub fn key_press<A>(&mut self, targets: &[Target<A>]) {
|
|
self.key_active = self
|
|
.focused(targets)
|
|
.filter(|t| t.role != Role::TextField)
|
|
.map(|t| t.id);
|
|
}
|
|
/// 结束键盘激活并按有效控件身份返回操作。
|
|
pub fn key_release<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<A> {
|
|
// 只有释放时仍聚焦相同启用目标才返回动作；take 防止重复 key-up 重复激活。
|
|
let active = self.key_active.take()?;
|
|
self.focused(targets)
|
|
.filter(|t| t.id == active)
|
|
.and_then(|t| t.action.clone())
|
|
}
|
|
/// 组合悬停、按下、焦点、选中和启用状态，供控件选择正确样式。
|
|
pub fn visual(&self, id: WidgetId, selected: bool, enabled: bool) -> VisualState {
|
|
// 禁用控件不显示交互状态；指针按压需仍悬停才显示 pressed，拖出后保留捕获但取消按下外观。
|
|
let hovered = enabled && self.hovered == Some(id);
|
|
VisualState {
|
|
hovered,
|
|
pressed: enabled
|
|
&& (self.key_active == Some(id) || (hovered && self.pointer_active == Some(id))),
|
|
focused: enabled && self.keyboard_focus && self.focused == Some(id),
|
|
selected,
|
|
enabled,
|
|
}
|
|
}
|
|
/// 返回本次拖动/按压捕获的控件，移动过程中不随悬停目标跳变。
|
|
pub fn captured(&self, id: WidgetId) -> bool {
|
|
self.pointer_active == Some(id)
|
|
}
|
|
/// 按命中角色选择系统光标，例如文本、分隔条或可点击按钮。
|
|
pub fn cursor<A>(&self, targets: &[Target<A>]) -> Cursor {
|
|
// 拖动分隔条/滚动条时优先沿用捕获目标的光标，避免指针跨过其他控件导致拖动光标跳变。
|
|
let target = self
|
|
.pointer_active
|
|
.and_then(|id| {
|
|
targets.iter().find(|t| {
|
|
t.id == id && matches!(t.role, Role::Splitter(_) | Role::Scrollbar(_))
|
|
})
|
|
})
|
|
.or_else(|| self.hit(targets));
|
|
match target {
|
|
Some(t) if !t.enabled => Cursor::Disabled,
|
|
Some(t) => match t.role {
|
|
Role::TextField => Cursor::Text,
|
|
Role::Splitter(Axis::Horizontal) => Cursor::ResizeHorizontal,
|
|
Role::Splitter(Axis::Vertical) => Cursor::ResizeVertical,
|
|
Role::Scrollbar(_) => Cursor::Grab,
|
|
_ => Cursor::Pointer,
|
|
},
|
|
None => Cursor::Default,
|
|
}
|
|
}
|
|
}
|