Library

Application

Application

Selector Targeting

WithSelector sets the active selector for the current unit of work using UI Automation element matching (AutomationID, Name, ClassName, XPath). WithAllThatMatch is used when a selector intentionally matches multiple repeating elements, such as rows in a list view, and it is what decides how many of them an action works on. WithPersistentSelector adds a selector that persists across all units of work for the lifetime of the application session. PersistentCallIfFound and PersistentCallIfNotFound attach persistent handlers to the persistent selector.

NOTE

Application selectors use Windows UI Automation properties. The most reliable approach is WithAutomationID - match the AutomationID property from tools like Inspect.exe or Accessibility Insights. WithXPath is also supported for desktop element trees.

WARNING

A selector can find several elements, and a click, a hover, a focus, a scroll, a drag, a tab switch or a write goes to the first of them. Naming several is usually a path that was not specific enough rather than an instruction to act on all of them, and hovering both of Notepad++'s panes is never what was wanted. WithAllThatMatch is how you ask for more: give it a number for that many, and the action runs once per element up to it. Reading is the exception, because a grid read takes every match it found: see Reading Data.

Examples

GPAL Fluent: High-level fluent C# API

//WithAllThatMatch takes an integer, the maximum number of elements to match and process. Set it high enough to cover the expected element count but not so high that it causes performance issues. Leaving it off is not the same as leaving it unlimited: without it an action works on the first element the selector found, and only a grid read takes them all.

// Target by AutomationID (most reliable for desktop)

var rows = GPAL.Grid.ToGPALObject();

GPAL.Application

.Open("C:\MyApp\app.exe")

.WithSelector((Selector)GPAL.Selector.WithAutomationID("btnSave"))

.LeftClick();


// Target all rows in a list (repeating elements)

GPAL.Application

.Open("C:\MyApp\app.exe")

.WithSelector((Selector)GPAL.Selector.WithClassName("ListViewItem"))

.WithAllThatMatch(100)

.GetGrid(ref rows);

On this page

Application
Selector Targeting
  • Examples
    • 💬 Ask GPAL