Merge pull request #416 from Integration-Automation/feat/ax-props-batch

Add ax_props: read rich UIA element properties before acting

Author: JE-Chen

WHATS_NEW.md

@@ -1,5 +1,11 @@
 # What's New — AutoControl
 
+## What's new (2026-06-25) — Rich UIA Element Properties
+
+Know if a control is enabled / off-screen / has a tooltip before you act. Full reference: [`docs/source/Eng/doc/new_features/v196_features_doc.rst`](docs/source/Eng/doc/new_features/v196_features_doc.rst).
+
+- **`get_element_properties` / `is_element_enabled`** (`AC_get_element_properties`): the flat element list carries only name/role/bounds/app/id, but automation needs more before it acts — **is the control enabled** (don't click a disabled button), **is it off-screen**, its **item_status** (field validation/error), **help_text** (tooltip), and **accelerator_key** (drive via hotkey). This reads those high-value UIA properties (`enabled`/`offscreen`/`help_text`/`item_status`/`accelerator_key`/`access_key`/`orientation`); `is_element_enabled` is the common pre-action guard. Dispatched through the injectable accessibility backend seam (headless-testable via a fake backend; real UIA reads in the Windows backend). No `PySide6`.
+
 ## What's new (2026-06-25) — Realize Off-Screen Items in Virtualized Lists / Grids
 
 Reach a row that isn't scrolled into view yet — the "element not found in a long list" fix. Full reference: [`docs/source/Eng/doc/new_features/v195_features_doc.rst`](docs/source/Eng/doc/new_features/v195_features_doc.rst).

docs/source/Eng/doc/new_features/v196_features_doc.rst

@@ -0,0 +1,44 @@
+Rich UIA Element Properties
+===========================
+
+``list_accessibility_elements`` / ``AccessibilityElement`` carry only name / role /
+bounds / app / pid / automation_id. Automation routinely needs more *before it
+acts*: **is the control enabled** (don't click a disabled button), **is it
+off-screen** (is it really visible?), its **item_status** (validation / error text
+on a field), **help_text** (tooltip), and **accelerator_key** (drive it via a
+hotkey instead of a click). ``ax_props`` exposes those high-value UIA properties.
+
+* :func:`get_element_properties` — the full property dict,
+* :func:`is_element_enabled` — the common pre-action guard.
+
+Each function is a thin dispatch onto the injectable
+``accessibility.backends.get_backend()`` seam — headless-testable on any platform
+by injecting a fake backend; the real UIA property reads live in the Windows
+backend. Imports no ``PySide6``.
+
+Headless API
+------------
+
+.. code-block:: python
+
+    from je_auto_control import get_element_properties, is_element_enabled
+
+    get_element_properties(name="Save", role="button")
+    # {"enabled": False, "offscreen": False, "help_text": "Save the file",
+    #  "item_status": "", "accelerator_key": "Ctrl+S", "access_key": "S",
+    #  "orientation": 0}
+
+    if is_element_enabled(name="Submit"):
+        click_text("Submit")          # don't click a disabled button
+
+The control is located by ``name`` / ``role`` / ``app_name`` / ``automation_id``
+(same as the other native-control reads). ``get_element_properties`` returns the
+property dict or ``None`` when the control isn't found; ``is_element_enabled``
+returns the ``enabled`` flag (or ``None`` if not found).
+
+Executor commands
+-----------------
+
+``AC_get_element_properties`` returns ``{found, properties}``. It is exposed as the
+read-only ``ac_get_element_properties`` MCP tool and as a Script Builder command
+under **Native UI**.

docs/source/Zh/doc/new_features/v196_features_doc.rst

@@ -0,0 +1,40 @@
+豐富的 UIA 元素屬性
+===================
+
+``list_accessibility_elements`` / ``AccessibilityElement``只帶有 name / role / bounds /
+app / pid / automation_id。自動化在*動作之前*常需要更多資訊:**控制項是否啟用**(別點停用的
+按鈕)、**是否在畫面外**(是否真的可見)、其 **item_status**(欄位的驗證 / 錯誤文字)、
+**help_text**(工具提示),以及 **accelerator_key**(以快捷鍵而非點擊來驅動它)。``ax_props``
+就提供這些高價值的 UIA 屬性。
+
+* :func:`get_element_properties` ——完整的屬性字典,
+* :func:`is_element_enabled` ——常見的動作前守衛。
+
+每個函式都是對可注入的 ``accessibility.backends.get_backend()`` 接縫的薄分派——可在任何平台透過
+注入 fake backend 進行無頭測試;真正的 UIA 屬性讀取位於 Windows 後端。不匯入 ``PySide6``。
+
+無頭 API
+--------
+
+.. code-block:: python
+
+    from je_auto_control import get_element_properties, is_element_enabled
+
+    get_element_properties(name="Save", role="button")
+    # {"enabled": False, "offscreen": False, "help_text": "Save the file",
+    #  "item_status": "", "accelerator_key": "Ctrl+S", "access_key": "S",
+    #  "orientation": 0}
+
+    if is_element_enabled(name="Submit"):
+        click_text("Submit")          # 別點停用的按鈕
+
+控制項以 ``name`` / ``role`` / ``app_name`` / ``automation_id`` 定位(與其他原生控制讀取相同)。
+``get_element_properties`` 回傳屬性字典,找不到控制項時回傳 ``None``;``is_element_enabled``
+回傳 ``enabled`` 旗標(找不到則為 ``None``)。
+
+執行器指令
+----------
+
+``AC_get_element_properties`` 回傳 ``{found, properties}``。以唯讀
+``ac_get_element_properties`` MCP 工具及 Script Builder 指令(位於 **Native UI** 分類下)
+形式提供。

je_auto_control/__init__.py

@@ -68,6 +68,10 @@
 )
 # Realize off-screen items in virtualized lists / grids (UIA VirtualizedItem)
 from je_auto_control.utils.virtualized import realize_item
+# Rich UIA element properties (enabled / offscreen / help / status / keys)
+from je_auto_control.utils.ax_props import (
+    get_element_properties, is_element_enabled,
+)
 # Rich clipboard formats — RTF + CSV/TSV codecs and Windows get / set
 from je_auto_control.utils.clipboard_rich_formats import (
     build_rtf, csv_to_rows, get_clipboard_csv, get_clipboard_rtf, rows_to_csv,
@@ -1669,6 +1673,7 @@ def start_autocontrol_gui(*args, **kwargs):
     "assign_node_paths", "find_by_path",
     "is_interactive_role", "tab_order", "audit_focus_order", "focus_control",
     "realize_item",
+    "get_element_properties", "is_element_enabled",
     "build_rtf", "rtf_to_text", "rows_to_csv", "csv_to_rows",
     "set_clipboard_rtf", "get_clipboard_rtf",
     "set_clipboard_csv", "get_clipboard_csv",

je_auto_control/gui/script_builder/command_schema.py

@@ -1621,6 +1621,11 @@ def _add_native_control_specs(specs: List[CommandSpec]) -> None:
         ),
         description="Realize an off-screen item in a virtualized list/grid.",
     ))
+    specs.append(CommandSpec(
+        "AC_get_element_properties", "Native UI", "Get Element Properties",
+        fields=fields,
+        description="Read rich UIA props (enabled/offscreen/help/status/keys).",
+    ))
     specs.append(CommandSpec(
         "AC_get_control_text", "Native UI", "Get Control Text",
         fields=fields,

je_auto_control/utils/accessibility/backends/base.py

@@ -148,6 +148,20 @@ def find_virtual_item(self, item_name: Optional[str] = None, by: str = "name",
         """
         self._unsupported("find_virtual_item")
 
+    # --- rich element properties -------------------------------------------
+
+    def get_properties(self, name: Optional[str] = None,
+                       role: Optional[str] = None, app_name: Optional[str] = None,
+                       automation_id: Optional[str] = None,
+                       ) -> Optional[Dict[str, Any]]:
+        """Return rich UIA properties of the matched control, or None.
+
+        Surfaces the high-value properties the flat element list omits —
+        ``enabled`` / ``offscreen`` / ``help_text`` / ``item_status`` /
+        ``accelerator_key`` / ``access_key`` / ``orientation``.
+        """
+        self._unsupported("get_properties")
+
     def _unsupported(self, operation: str):
         """Raise a clear error for an action this backend can't perform."""
         raise AccessibilityNotAvailableError(

je_auto_control/utils/accessibility/backends/windows_backend.py

@@ -298,6 +298,13 @@ def find_virtual_item(self, item_name=None, by="name", container_name=None,
         self._realize(found)
         return _convert_uia(found)
 
+    def get_properties(self, name=None, role=None, app_name=None,
+                       automation_id=None) -> Optional[Dict[str, Any]]:
+        raw = self._find_raw(name, role, app_name, automation_id)
+        if not raw:
+            return None
+        return _read_properties(raw)
+
     def _text_pattern(self, name, role, app_name, automation_id):
         """Find a control and return its IUIAutomationTextPattern, or None."""
         raw = self._find_raw(name, role, app_name, automation_id)
@@ -366,6 +373,33 @@ def _read_row(pattern, row: int, cols: int):
         return cells
 
 
+def _as_text(value) -> str:
+    return str(value or "")
+
+
+# (key, UIA element attribute, cast) for the rich properties the flat list omits.
+_PROPERTY_READS = (
+    ("enabled", "CurrentIsEnabled", bool),
+    ("offscreen", "CurrentIsOffscreen", bool),
+    ("help_text", "CurrentHelpText", _as_text),
+    ("item_status", "CurrentItemStatus", _as_text),
+    ("accelerator_key", "CurrentAcceleratorKey", _as_text),
+    ("access_key", "CurrentAccessKey", _as_text),
+    ("orientation", "CurrentOrientation", int),
+)
+
+
+def _read_properties(raw) -> Dict[str, Any]:
+    """Read the rich UIA properties of a raw element into a plain dict."""
+    properties: Dict[str, Any] = {}
+    for key, attribute, cast in _PROPERTY_READS:
+        try:
+            properties[key] = cast(getattr(raw, attribute))
+        except (OSError, AttributeError, ValueError, TypeError):
+            properties[key] = None
+    return properties
+
+
 def _convert_uia(raw) -> Optional[AccessibilityElement]:
     try:
         name = str(raw.CurrentName or "")

je_auto_control/utils/ax_props/__init__.py

@@ -0,0 +1,6 @@
+"""Read rich UIA element properties (enabled / offscreen / help / status / keys)."""
+from je_auto_control.utils.ax_props.ax_props import (
+    get_element_properties, is_element_enabled,
+)
+
+__all__ = ["get_element_properties", "is_element_enabled"]

je_auto_control/utils/ax_props/ax_props.py

@@ -0,0 +1,38 @@
+"""Read rich UI Automation properties the flat element list omits.
+
+``list_accessibility_elements`` / ``AccessibilityElement`` carry only name / role /
+bounds / app / pid / automation_id. Automation routinely needs more before it
+acts: **is the control enabled** (don't click a disabled button), **is it
+off-screen** (is it really visible?), its **item_status** (validation / error text
+on a field), **help_text** (tooltip), and **accelerator_key** (drive it via a
+hotkey instead of a click). ``ax_props`` exposes those high-value UIA properties.
+
+Each function is a thin dispatch onto the injectable
+``accessibility.backends.get_backend()`` seam, so the headless core is
+unit-testable on any platform by injecting a fake backend; the real UIA property
+reads live in the Windows backend. Imports no ``PySide6``.
+"""
+from typing import Any, Dict, Optional
+
+
+def get_element_properties(name: Optional[str] = None, role: Optional[str] = None,
+                           app_name: Optional[str] = None,
+                           automation_id: Optional[str] = None,
+                           ) -> Optional[Dict[str, Any]]:
+    """Return ``{enabled, offscreen, help_text, item_status, accelerator_key,
+    access_key, orientation}`` for the matched control, or None if not found."""
+    from je_auto_control.utils.accessibility.backends import get_backend
+    return get_backend().get_properties(name=name, role=role, app_name=app_name,
+                                        automation_id=automation_id)
+
+
+def is_element_enabled(name: Optional[str] = None, role: Optional[str] = None,
+                       app_name: Optional[str] = None,
+                       automation_id: Optional[str] = None) -> Optional[bool]:
+    """Return whether the matched control is enabled (None if not found).
+
+    The common guard before acting — don't click a disabled button.
+    """
+    properties = get_element_properties(name=name, role=role, app_name=app_name,
+                                        automation_id=automation_id)
+    return properties.get("enabled") if properties else None

je_auto_control/utils/executor/action_executor.py

@@ -2476,6 +2476,16 @@ def _realize_item(item_name: str, by: str = "name",
             "element": element.to_dict() if element else None}
 
 
+def _get_element_properties(name: Optional[str] = None, role: Optional[str] = None,
+                            app_name: Optional[str] = None,
+                            automation_id: Optional[str] = None) -> Dict[str, Any]:
+    """Adapter: read rich UIA properties (enabled/offscreen/help/status/keys)."""
+    from je_auto_control.utils.ax_props import get_element_properties
+    props = get_element_properties(name=name, role=role, app_name=app_name,
+                                   automation_id=automation_id)
+    return {"found": props is not None, "properties": props}
+
+
 def _get_control_text(name: Optional[str] = None, role: Optional[str] = None,
                       app_name: Optional[str] = None,
                       automation_id: Optional[str] = None) -> Dict[str, Any]:
@@ -6420,6 +6430,7 @@ def __init__(self):
             "AC_set_control_range": _set_control_range,
             "AC_scroll_control_into_view": _scroll_control_into_view,
             "AC_realize_item": _realize_item,
+            "AC_get_element_properties": _get_element_properties,
             "AC_get_control_text": _get_control_text,
             "AC_get_selected_text": _get_selected_text,
             "AC_get_visible_text": _get_visible_text,