Common Options
This module is available in versions after 20260507
Several ui_element APIs accept an options table for target app, result count, child depth, hit checks, and action steps.
Query Options
local options = {
pid = app.front_pid(),
max_level = 2,
max_elements = 200,
include_hit_state = true,
}
- pid
Integer. Target app process identifier. When omitted, the foreground app is usually used. - max_level
Integer. Child expansion depth. Use1or2to keep returned data small. - max_elements
Integer. Maximum number of top-level elements to return. - fallback_children
Boolean. Try reading child elements when the regular list is empty. Default depends on the API. - include_hit_state
Boolean. Include hit state fields. - hit_test
Boolean. Enable screen-sampling hit lookup. Normal scripts usually do not need it. - fallback_hit_test
Boolean. Try screen-sampling hit lookup when the regular list is empty. - hit_test_spacing
Number. Screen-sampling spacing in logical coordinates. Default40.
Attribute Exclusion Options
Available from 20261115. Only for snapshot() and list_text_elements(). All are booleans, default to false, and also apply to child elements. When these states are not needed, enabling the exclusion options can reduce query overhead and speed up snapshot capture.
- exclude_visibility
Whentrue, skip visibility queries and omitisVisible. - exclude_map
Whentrue, skip map-state checks and omitisMap; map elements are retained. - exclude_hit_state
Whentrue, skip center-point hit checks and omitcanHit,hitVerified,hitTestPoint, andhitTestPointLogical. Cannot be combined withinclude_hit_state = true.
The element scope, text, coordinates, and supplementary element discovery rules for hit_test / fallback_hit_test are unchanged. Do not exclude a state field if you need to filter by it.
Action Options
- point
Table. Coordinate point used for scroll or hit lookup, for example{ x = 200, y = 700 }, in physical pixels. - x / y
Integer. Same aspoint, placed directly in the options table. - steps
Number. Step parameter for scroll, increase, or decrease. The actual effect depends on the target control.
Description
list_text_elements()keeps conservative defaults for old scripts.find(),find_all(),snapshot(), and action APIs are usually better for new scripts.hit_testmay return elements closer to the current top layer, but it costs more. Use it only when regular queries cannot find the target.