use actl_core::target::Target;
use actl_core::{CtlError, ErrorCode};
use uiautomation::{UIAutomation, UIElement, UITreeWalker};
use crate::window::{ensure_window_responsive, find_window, top_level_of_focused};
use crate::{internal, timing};
pub struct Located {
pub window_title: String,
pub role: String,
pub name: Option<String>,
pub automation_id: Option<String>,
pub resolved_by: &'static str,
pub(crate) element: UIElement,
}
pub fn locate(app: Option<&str>, target: &Target, near: Option<&str>) -> Result<Located, CtlError> {
if matches!(target, Target::Uia(_)) && near.is_some() {
return Err(CtlError::protocol(
"uia selectors do not support --near; use within and unique conditions",
));
}
if let Target::Coord(..) = target {
return Err(CtlError::protocol(format!(
"{} cannot be resolved to an element; coordinate targets are physical-only (click xy:x,y --app <win> --physical)",
target.describe()
)));
}
let auto = UIAutomation::new().map_err(internal)?;
if let Target::Uia(selector) = target {
let root = crate::scoped_locate::window(&auto, app)?;
return crate::scoped_locate::locate(&auto, &root, selector);
}
let walker = auto.create_tree_walker().map_err(internal)?;
let root = {
let _t = actl_core::trace::scope("locate.window");
match app {
Some(pattern) => find_window(&auto, &walker, pattern)?,
None => {
if matches!(target, Target::Ref(_)) {
return Err(CtlError::protocol(format!(
"{} requires --app: refs are scoped to the window the snapshot came from; \
pass --app <title-substr> or re-snapshot",
target.describe()
)));
}
top_level_of_focused(&auto, &walker)?
}
}
};
let window_title = root
.get_name()
.map_err(|e| crate::read_channel::failure("window.name", e))?;
let _wake_ms = {
let _t = actl_core::trace::scope("locate.wake");
ensure_window_responsive(&root)
};
if let Target::Ref(n) = target {
let mut counter = 0u32;
let _t = actl_core::trace::scope("locate.ref-replay");
return match collect_until_ref(&walker, &root, 0, *n, &mut counter)? {
Some(hit) => {
crate::identity::check_ref(&root, &hit, *n)?;
located_from(hit, window_title, "ref-replay")
}
None => Err(CtlError::new(
ErrorCode::StaleRef,
format!(
"{} does not resolve — the tree changed since the snapshot",
target.describe()
),
)),
};
}
let mut counter = 0u32;
let mut matches = Vec::new();
if let Target::Id(_) = target {
let hits = {
let _t = actl_core::trace::scope("locate.fastpath");
fast_exact_ids(&auto, &root, target)?
};
match hits {
Some(hits) if hits.len() == 1 => {
return located_from(hits[0].clone(), window_title, "primary");
}
Some(hits) if hits.is_empty() => {
let _t = actl_core::trace::scope("locate.l4");
if let Some(hit) = locate_virtualized(&walker, &root, target)? {
return located_from(hit, window_title, "item-container");
}
return Err(CtlError::new(
ErrorCode::NotFound,
format!(
"no element matches {} (exact and virtualized-container levels)",
target.describe()
),
));
}
_ => {} }
}
{
let _t = actl_core::trace::scope("locate.dfs");
collect_matches(&walker, &root, 0, target, false, &mut counter, &mut matches)?;
}
if matches.is_empty() {
if let Target::Name(_) = target {
let mut fuzzy = Vec::new();
collect_matches(&walker, &root, 0, target, true, &mut counter, &mut fuzzy)?;
if !fuzzy.is_empty() {
fuzzy.sort_by_key(|c: &Candidate| c.ref_no);
return select(
fuzzy,
target,
near,
&walker,
&root,
window_title,
"fuzzy-name",
);
}
}
let l4 = {
let _t = actl_core::trace::scope("locate.l4");
locate_virtualized(&walker, &root, target)?
};
if let Some(hit) = l4 {
return located_from(hit, window_title, "item-container");
}
return Err(CtlError::new(
ErrorCode::NotFound,
format!(
"no element matches {} (exact, fuzzy and virtualized-container levels)",
target.describe()
),
));
}
matches.sort_by_key(|c: &Candidate| c.ref_no);
select(
matches,
target,
near,
&walker,
&root,
window_title,
"primary",
)
}
fn select(
matches: Vec<Candidate>,
target: &Target,
near: Option<&str>,
walker: &UITreeWalker,
root: &UIElement,
window_title: String,
level: &'static str,
) -> Result<Located, CtlError> {
if let Target::RoleAt(_, n) | Target::IdAt(_, n) = target {
return match matches.get((*n as usize).saturating_sub(1)) {
Some(c) => located_from(
c.element.clone(),
window_title,
if matches!(target, Target::IdAt(..)) {
"id-ordinal"
} else {
"role-ordinal"
},
),
None => Err(CtlError::new(
ErrorCode::NotFound,
format!(
"{}: only {} match(es) in the window",
target.describe(),
matches.len()
),
)),
};
}
if matches.len() == 1 {
return located_from(matches[0].element.clone(), window_title, level);
}
if let Some(anchor_pat) = near {
let mut counter = 0u32;
let mut anchors = Vec::new();
let anchor_target =
actl_core::parse_target(anchor_pat).unwrap_or(Target::Name(anchor_pat.to_string()));
collect_matches(
walker,
root,
0,
&anchor_target,
false,
&mut counter,
&mut anchors,
)?;
if anchors.len() != 1 {
return Err(CtlError::new(
ErrorCode::NotFound,
format!(
"--near anchor {anchor_pat:?} must match exactly one element, got {}",
anchors.len()
),
));
}
{
let ar = anchors[0]
.element
.get_bounding_rectangle()
.map_err(|e| crate::read_channel::failure("anchor.bounds", e))?;
let (ax, ay) = center(&ar);
let mut best: Option<(f64, usize)> = None;
for (i, c) in matches.iter().enumerate() {
{
let r = c
.element
.get_bounding_rectangle()
.map_err(|e| crate::read_channel::failure("candidate.bounds", e))?;
let (cx, cy) = center(&r);
let dx = (cx - ax) as f64;
let dy = (cy - ay) as f64;
let d = dx * dx + dy * dy;
if best.map(|(bd, _)| d < bd).unwrap_or(true) {
best = Some((d, i));
}
}
}
if let Some((_, i)) = best {
return located_from(matches[i].element.clone(), window_title, "anchor");
}
}
}
let evidence: Vec<serde_json::Value> = matches
.iter()
.take(8)
.map(|c| {
serde_json::json!({
"ref": format!("@e{}", c.ref_no),
"role": c.role,
"name": c.name,
"automation_id": c.automation_id,
})
})
.collect();
Err(CtlError::with_evidence(
ErrorCode::Ambiguous,
format!(
"{} matches {} elements in the window; pick one by @eN or role ordinal (--near anchor also applies)",
target.describe(),
matches.len()
),
serde_json::json!({ "candidates": evidence }),
))
}
fn center(r: &uiautomation::types::Rect) -> (i32, i32) {
(
(r.get_left() + r.get_right()) / 2,
(r.get_top() + r.get_bottom()) / 2,
)
}
fn located_from(
elem: UIElement,
window_title: String,
resolved_by: &'static str,
) -> Result<Located, CtlError> {
Ok(Located {
window_title,
role: strict_role(&elem)?,
name: Some(
elem.get_name()
.map_err(|e| crate::read_channel::failure("name", e))?,
),
automation_id: Some(
elem.get_automation_id()
.map_err(|e| crate::read_channel::failure("automation_id", e))?,
),
resolved_by,
element: elem,
})
}
struct Candidate {
element: UIElement,
ref_no: u32,
role: String,
name: Option<String>,
automation_id: Option<String>,
}
fn collect_until_ref(
_walker: &UITreeWalker,
elem: &UIElement,
_depth: u32,
want: u32,
counter: &mut u32,
) -> Result<Option<UIElement>, CtlError> {
for entry in crate::observation::tree(elem)?.require_complete()? {
let role = strict_role(&entry.element)?;
if actl_core::is_interactive_role(&role) {
*counter += 1;
if *counter == want {
return Ok(Some(entry.element));
}
}
}
Ok(None)
}
fn strict_role(elem: &UIElement) -> Result<String, CtlError> {
elem.get_control_type()
.map(|v| format!("{v:?}"))
.map_err(|e| crate::read_channel::failure("control_type", e))
}
fn collect_matches(
_walker: &UITreeWalker,
elem: &UIElement,
_depth: u32,
target: &Target,
fuzzy: bool,
counter: &mut u32,
out: &mut Vec<Candidate>,
) -> Result<(), CtlError> {
*counter = 0;
for entry in crate::observation::tree(elem)?.require_complete()? {
let element = entry.element;
let role = strict_role(&element)?;
let ref_no = if actl_core::is_interactive_role(&role) {
*counter += 1;
*counter
} else {
0
};
let name = element
.get_name()
.map_err(|e| crate::read_channel::failure("name", e))?;
let id = element
.get_automation_id()
.map_err(|e| crate::read_channel::failure("automation_id", e))?;
let hit = match target {
Target::Name(s) if fuzzy => actl_core::target::fuzzy_contains(&name, s),
Target::Name(s) => name.contains(s.as_str()),
Target::Id(s) | Target::IdAt(s, _) => id == *s,
Target::Role(s) | Target::RoleAt(s, _) => role == *s,
_ => false,
};
if hit {
out.push(Candidate {
element,
ref_no,
role,
name: Some(name),
automation_id: Some(id),
});
}
}
Ok(())
}
fn fast_exact_ids(
auto: &UIAutomation,
root: &UIElement,
target: &Target,
) -> Result<Option<Vec<UIElement>>, CtlError> {
use uiautomation::types::{TreeScope, UIProperty};
use uiautomation::variants::Variant;
let Target::Id(s) = target else {
return Ok(None);
};
let cond = auto
.create_property_condition(UIProperty::AutomationId, Variant::from(s.clone()), None)
.map_err(|e| crate::read_channel::failure("id.condition", e))?;
let cache = auto.create_cache_request().map_err(internal)?;
cache
.set_tree_filter(auto.create_true_condition().map_err(internal)?)
.map_err(internal)?;
cache.set_tree_scope(TreeScope::Element).map_err(internal)?;
root.find_all_build_cache(TreeScope::Subtree, &cond, &cache)
.map(Some)
.map_err(|e| crate::read_channel::failure("id.query", e))
}
fn container_query_for(
target: &Target,
) -> Option<(windows::Win32::UI::Accessibility::UIA_PROPERTY_ID, String)> {
use windows::Win32::UI::Accessibility::{UIA_AutomationIdPropertyId, UIA_NamePropertyId};
match target {
Target::Name(s) => Some((UIA_NamePropertyId, s.clone())),
Target::Id(s) => Some((UIA_AutomationIdPropertyId, s.clone())),
_ => None,
}
}
fn locate_virtualized(
_walker: &UITreeWalker,
root: &UIElement,
target: &Target,
) -> Result<Option<UIElement>, CtlError> {
use uiautomation::{types::UIProperty, variants::Variant};
use windows::{
Win32::UI::Accessibility::{
IUIAutomationElement, IUIAutomationItemContainerPattern, UIA_ItemContainerPatternId,
},
core::Interface,
};
let Some((prop, value)) = container_query_for(target) else {
return Ok(None);
};
let value = Variant::from(value);
let entries = crate::observation::tree(root)?.require_complete()?;
let mut hit = None;
for entry in entries {
let c = entry.element;
if !crate::read_channel::available(
&c,
UIProperty::IsItemContainerPatternAvailable,
"item-container",
)? {
continue;
}
unsafe {
let pattern: IUIAutomationItemContainerPattern = c
.as_ref()
.GetCurrentPattern(UIA_ItemContainerPatternId)
.and_then(|p| p.cast())
.map_err(|e| crate::read_channel::failure("item-container.pattern", e.into()))?;
let mut raw = std::ptr::null_mut();
(pattern.vtable().FindItemByProperty)(
pattern.as_raw(),
std::ptr::null_mut(),
prop,
std::mem::transmute_copy(value.as_ref()),
&mut raw,
)
.ok()
.map_err(|e| crate::read_channel::failure("item-container.query", e.into()))?;
if !raw.is_null() {
let element = UIElement::from(IUIAutomationElement::from_raw(raw));
let mut second = std::ptr::null_mut();
(pattern.vtable().FindItemByProperty)(
pattern.as_raw(),
element.as_ref().as_raw(),
prop,
std::mem::transmute_copy(value.as_ref()),
&mut second,
)
.ok()
.map_err(|e| crate::read_channel::failure("item-container.next", e.into()))?;
if !second.is_null() {
let _second = IUIAutomationElement::from_raw(second);
return Err(CtlError::new(
ErrorCode::Ambiguous,
"multiple virtualized items matched",
));
}
if hit.is_some() {
return Err(CtlError::new(
ErrorCode::Ambiguous,
"multiple virtualized containers matched",
));
}
hit = Some(element);
}
}
}
Ok(hit)
}
fn poll(app: Option<&str>, target: &Target) -> Result<Option<Located>, CtlError> {
actl_core::wait_control::check()?;
crate::scoped_locate::observed(locate(app, target, None))
}
pub fn wait_element(app: Option<&str>, target: &Target, timeout_ms: u64) -> Result<(), CtlError> {
let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
loop {
if poll(app, target)?.is_some() {
return Ok(());
}
if std::time::Instant::now() >= deadline {
return Err(CtlError::new(
ErrorCode::Timeout,
format!(
"element {} did not resolve within {timeout_ms}ms",
target.describe()
),
));
}
std::thread::sleep(std::time::Duration::from_millis(timing().poll_ms));
}
}
pub fn wait_gone(app: Option<&str>, target: &Target, timeout_ms: u64) -> Result<(), CtlError> {
let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
loop {
if poll(app, target)?.is_none() {
return Ok(());
}
if std::time::Instant::now() >= deadline {
return Err(CtlError::new(
ErrorCode::Timeout,
format!(
"{} still resolves after {timeout_ms}ms (expected it to disappear)",
target.describe()
),
));
}
std::thread::sleep(std::time::Duration::from_millis(timing().poll_ms));
}
}
#[cfg(test)]
mod tests {
use super::container_query_for;
use actl_core::target::Target;
use windows::Win32::UI::Accessibility::{UIA_AutomationIdPropertyId, UIA_NamePropertyId};
#[test]
fn l4_maps_name_and_id_to_exact_property_queries() {
let (prop, v) = container_query_for(&Target::Name("report.xlsx".into())).expect("name");
assert_eq!(prop, UIA_NamePropertyId);
assert_eq!(v, "report.xlsx");
let (prop, v) = container_query_for(&Target::Id("SystemListItem".into())).expect("id");
assert_eq!(prop, UIA_AutomationIdPropertyId);
assert_eq!(v, "SystemListItem");
}
#[test]
fn l4_excludes_role_and_ref_targets() {
assert!(container_query_for(&Target::Role("ListItem".into())).is_none());
assert!(container_query_for(&Target::RoleAt("ListItem".into(), 2)).is_none());
assert!(container_query_for(&Target::Ref(7)).is_none());
}
}
pub fn wait_property(
app: Option<&str>,
target: &Target,
predicate: &WaitPredicate,
timeout_ms: u64,
) -> Result<String, CtlError> {
let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
let mut last: Option<String> = None;
loop {
if let Some(loc) = poll(app, target)? {
let actual = predicate.read(&loc.element)?;
if predicate.satisfied(actual.as_deref()) {
return Ok(actual.unwrap_or_default());
}
last = actual;
}
if std::time::Instant::now() >= deadline {
return Err(CtlError::with_evidence(
ErrorCode::Timeout,
format!(
"{} did not satisfy {} within {timeout_ms}ms",
target.describe(),
predicate.describe()
),
serde_json::json!({ "last_actual": last, "actual":last, "target":target.describe(), "expected":predicate.expected, "property":predicate.describe().split('=').next(), "channel":match predicate.prop { WaitProp::Value => "value-or-text-pattern", WaitProp::Name => "name", WaitProp::Text => "text-pattern", WaitProp::Checked => "toggle-pattern" }, "comparison":if predicate.contains {"contains"} else {"exact"} }),
));
}
std::thread::sleep(std::time::Duration::from_millis(timing().poll_ms));
}
}
pub struct StableOutcome {
pub samples: usize,
pub changes: usize,
pub last_len: usize,
}
pub fn wait_stable(
app: Option<&str>,
target: &Target,
timeout_ms: u64,
) -> Result<StableOutcome, CtlError> {
const STABLE_SAMPLES: usize = 2;
let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
let mut last: Option<String> = None;
let mut stable = 0usize;
let mut samples = 0usize;
let mut changes = 0usize;
loop {
if let Some(loc) = poll(app, target)? {
let sample = stability_sample(&loc.element)?;
samples += 1;
stable = match &last {
Some(prev) if prev == &sample => stable + 1,
Some(_) => {
changes += 1;
1
}
None => 1,
};
last = Some(sample);
if stable >= STABLE_SAMPLES {
return Ok(StableOutcome {
samples,
changes,
last_len: last.as_deref().map(str::len).unwrap_or(0),
});
}
} else {
stable = 0;
}
if std::time::Instant::now() >= deadline {
return Err(CtlError::with_evidence(
ErrorCode::Timeout,
format!(
"{} did not settle within {timeout_ms}ms (content still changing or element absent)",
target.describe()
),
serde_json::json!({
"samples": samples,
"changes": changes,
"last_len": last.as_deref().map(str::len),
}),
));
}
std::thread::sleep(std::time::Duration::from_millis(timing().settle_ms));
}
}
fn stability_sample(elem: &UIElement) -> Result<String, CtlError> {
if let Some(text) = crate::read::read_text(elem)? {
return Ok(text);
}
if let Some(value) = crate::read::read_value(elem)? {
return Ok(value);
}
elem.get_name()
.map_err(|e| crate::read_channel::failure("name", e))
}
pub struct WaitPredicate {
pub prop: WaitProp,
pub expected: String,
pub contains: bool,
}
pub enum WaitProp {
Text,
Value,
Name,
Checked,
}
impl WaitPredicate {
pub fn parse(raw: &str) -> Result<Self, CtlError> {
let Some((prop, expected)) = raw.split_once('=') else {
return Err(CtlError::protocol(format!(
"invalid predicate {raw:?}: expected <prop>=<expected> with prop in value|name|text|checked"
)));
};
let prop = match prop.trim() {
"value" => WaitProp::Value,
"name" => WaitProp::Name,
"text" => WaitProp::Text,
"checked" => WaitProp::Checked,
other => {
return Err(CtlError::protocol(format!(
"unknown predicate property {other:?}: expected value|name|text|checked"
)));
}
};
let expected = expected.trim().to_string();
if expected.is_empty() {
return Err(CtlError::protocol(format!(
"predicate {raw:?} has an empty expectation"
)));
}
if matches!(prop, WaitProp::Checked) && !matches!(expected.as_str(), "on" | "off") {
return Err(CtlError::protocol(
"checked predicate expects on|off (e.g. checked=on)",
));
}
Ok(Self {
prop,
expected,
contains: false,
})
}
pub fn describe(&self) -> String {
let p = match self.prop {
WaitProp::Value => "value",
WaitProp::Name => "name",
WaitProp::Text => "text",
WaitProp::Checked => "checked",
};
format!("{p}={}", self.expected)
}
pub fn read(&self, elem: &uiautomation::UIElement) -> Result<Option<String>, CtlError> {
let (value, channel) = match self.prop {
WaitProp::Value => (crate::read::read_value(elem)?, "value-or-text-pattern"),
WaitProp::Text => (crate::read::read_text(elem)?, "text-pattern"),
WaitProp::Name => (
Some(
elem.get_name()
.map_err(|e| crate::read_channel::failure("name", e))?,
),
"name",
),
WaitProp::Checked => (
crate::read_channel::toggle(elem)?.map(|v| v.to_lowercase()),
"toggle-pattern",
),
};
Ok(Some(crate::read_channel::require(value, channel)?))
}
pub fn satisfied(&self, actual: Option<&str>) -> bool {
let Some(a) = actual else { return false };
match (&self.prop, self.contains) {
(WaitProp::Checked, _)
| (WaitProp::Value, false)
| (WaitProp::Name | WaitProp::Text, false) => a == self.expected,
(WaitProp::Value, true) | (WaitProp::Name | WaitProp::Text, true) => {
a.contains(&self.expected)
}
}
}
}
#[cfg(test)]
mod wait_tests {
use super::*;
use actl_core::CtlError;
#[test]
fn predicate_parses_and_rejects() {
let p = WaitPredicate::parse("value=OK").unwrap();
assert!(p.satisfied(Some("OK")));
assert!(!p.satisfied(Some("ok"))); let p = WaitPredicate::parse("checked=on").unwrap();
assert!(p.satisfied(Some("on")));
assert!(WaitPredicate::parse("checked=maybe").is_err());
assert!(WaitPredicate::parse("bogus=1").is_err());
assert!(WaitPredicate::parse("noequalsign").is_err());
assert!(WaitPredicate::parse("value=").is_err());
}
#[test]
fn contains_semantics_apply_to_value_and_name_only() {
let mut p = WaitPredicate::parse("value=56,877").unwrap();
p.contains = true;
assert!(p.satisfied(Some("显示为 56,877")));
let mut p = WaitPredicate::parse("name=保存").unwrap();
p.contains = true;
assert!(p.satisfied(Some("另存为 - 保存")));
}
#[test]
fn missing_actual_is_unsatisfied() {
let p = WaitPredicate::parse("name=x").unwrap();
assert!(!p.satisfied(None));
let _ = CtlError::protocol(""); }
}