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.

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.