Skip to main content

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. Use 1 or 2 to 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. Default 40.

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
    When true, skip visibility queries and omit isVisible.
  • exclude_map
    When true, skip map-state checks and omit isMap; map elements are retained.
  • exclude_hit_state
    When true, skip center-point hit checks and omit canHit, hitVerified, hitTestPoint, and hitTestPointLogical. Cannot be combined with include_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 as point, 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_test may return elements closer to the current top layer, but it costs more. Use it only when regular queries cannot find the target.