Tutorials

Tutorials

Automating a Desktop App: Notepad++

GPAL.Application drives Windows desktop applications the same way GPAL.Browser drives a browser: open the app, define selectors against its UI Automation tree, and chain actions like InsertFrom, AppendFrom, FillInFrom, and key combinations. This tutorial opens Notepad++, types and edits text, then hovers over a toolbar button and a menu item.

Complete Program

Here's the whole workflow, start to finish. Each piece is broken down and explained below.

using GenerallyPositive;

using GenerallyPositive.Application;

using static GenerallyPositive.Application.Application;

using static GenerallyPositive.Enums;

GPAL.WithExceptionHandler(ExceptionEventHandler)

.WithInformationHandler(ExceptionEventHandler);

Selector notepadPane = (Selector)GPAL.Selector

.WithSelectorName("NotepadPane")

.WithXPath("/Window/Pane[1]")

.WithOffsetX(10)

.WithOffsetY(10);

Selector indentGuideButton = (Selector)GPAL.Selector

.WithSelectorName("IndentButton")

.WithXPath("/Window/Pane[2]/ToolBar/Button[21]");

Selector cSharpMenuItem = (Selector)GPAL.Selector

.WithSelectorName("C#MenuItem")

.WithXPath("/Window/MenuBar/MenuItem[6]/Menu/MenuItem[4]/Menu/MenuItem[2]");

Application application = GPAL.Application

.WithParameter(@"C:sdiebay.words.txt")

.Open(@"C:Program FilesNotepad++

otepad++.exe")

.WaitFor(5000)

.Maximize

.LeftClick()

.ToGPALObject();

application

.WithSelector(notepadPane)

.CallIfFound(CallIfFound)

.CallIfNotFound(CallIfNotFound)

.Hover()

.InsertFrom("Insert text")

.AppendFrom("Append Text")

.WaitFor(5000);

application.Minimize

.WaitFor(5000);

application

.Restore

.FillInFrom("Overwrite Text");

application

.PressModifierKey(ModifierKeys.Control)

.SendString("z")

.SendString("z")

.ReleaseModifierKey(ModifierKeys.Control);

application

.WithSelector(indentGuideButton)

.CallIfFound(CallIfFound)

.Hover()

.WaitFor(5000);

application

.WithSelector(cSharpMenuItem)

.CallIfFound(CallIfFound)

.Hover()

.WaitFor(5000);

application.Close();

public static CallIfStatus CallIfFound(IApplication application, List<GPALAutomationElement> foundElements, List<GPALAutomationElement> matchedElements, Selector selector, bool matchedAll)

{

CallIfStatus retVal = CallIfStatus.NotHandled;

foreach (GPALAutomationElement element in foundElements)

Debug.WriteLine($"<{element.Ae.Current.Name}> : {element.Ae.Current.LocalizedControlType}");

return retVal;

}

public static CallIfStatus CallIfNotFound(IApplication application, List<GPALAutomationElement> foundElements, List<GPALAutomationElement> matchedElements, Selector selector, bool matchedAll)

{

Debug.WriteLine($"{selector.Name} <{selector.SelectorPaths[0].SelectorPath}> : Not Found.");

return CallIfStatus.NotHandled;

}

Open the Application

GPAL.Application is a fluent factory just like GPAL.Browser. WithParameter passes a command-line argument to the executable (here, a file to open in Notepad++), Open launches it, WaitFor gives it time to start, and Maximize/LeftClick bring it into a known state. ToGPALObject() returns the live IApplication you'll drive for the rest of the workflow.

Application application = GPAL.Application

.WithParameter(@"C:sdiebay.words.txt")

.Open(@"C:Program FilesNotepad++

otepad++.exe")

.WaitFor(5000)

.Maximize

.LeftClick()

.ToGPALObject();

Selectors Use UI Automation XPath

Desktop selectors target the Windows UI Automation tree rather than the DOM. An XPath like /Window/Pane[2]/ToolBar/Button[21] walks down from the application's main window to a specific toolbar button. WithOffsetX/WithOffsetY shift the click point within the matched element - useful when the element's bounding box is larger than the clickable area.

Selector notepadPane = (Selector)GPAL.Selector

.WithSelectorName("NotepadPane")

.WithXPath("/Window/Pane[1]")

.WithOffsetX(10)

.WithOffsetY(10);

Selector indentGuideButton = (Selector)GPAL.Selector

.WithSelectorName("IndentButton")

.WithXPath("/Window/Pane[2]/ToolBar/Button[21]");

TIP

Unlike a browser's DOM, there's no devtools inspector built into the OS - tools like Visual Studio's UI Automation inspector help map out a desktop app's UI Automation tree to discover these XPaths.

Insert, Append, and Overwrite Text

WithSelector targets the editor pane, CallIfFound/CallIfNotFound react to whether the element was located, and Hover moves focus there. InsertFrom and AppendFrom add text at the cursor and at the end respectively; later, FillInFrom replaces the content entirely after the window has been minimized and restored.

application

.WithSelector(notepadPane)

.CallIfFound(CallIfFound)

.CallIfNotFound(CallIfNotFound)

.Hover()

.InsertFrom("Insert text")

.AppendFrom("Append Text")

.WaitFor(5000);

application.Minimize

.WaitFor(5000);

application

.Restore

.FillInFrom("Overwrite Text");

Modifier Keys and Hovering UI Elements

PressModifierKey/ReleaseModifierKey wrap a key combination like Ctrl+Z for undo, sending SendString calls in between. Hovering over a toolbar button or menu item is a simple way to verify a selector resolves to the right element before wiring up a click.

application

.PressModifierKey(ModifierKeys.Control)

.SendString("z")

.SendString("z")

.ReleaseModifierKey(ModifierKeys.Control);

application

.WithSelector(indentGuideButton)

.CallIfFound(CallIfFound)

.Hover()

.WaitFor(5000);

application.Close();

WARNING

Hardware-level interaction (mouse moves, key sends) operates on whatever window has OS focus. If the target application loses focus between actions, hardware clicks and key presses will go to the wrong window. Use Hover or LeftClick to re-establish focus before hardware-level steps.

On this page

Tutorials
Automating a Desktop App: Notepad++
  • Complete Program
  • Open the Application
  • Selectors Use UI Automation XPath
  • Insert, Append, and Overwrite Text
  • Modifier Keys and Hovering UI Elements