Tutorials

Integrations

Integrations

Automating a Desktop App: Notepad++

Desktop Application Automation Selectors GPAL Actions Event System Hardware-Level Interaction

Complete Program

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

using System.Collections.Generic;

using System.Diagnostics;

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]");


IApplication application = GPAL.Application

.WithParameter("C:\sdi\ebay.words.txt")

.Open("C:\Program Files\Notepad++\notepad++.exe")

.ToGPALObject();


// Open is not an action, so a WaitFor here would not wait. Wait for the window instead;

// it returns as soon as the window appears.

application

.WithWaitForWindowTimeout(10);


application

.WaitForWindowRegex("Notepad\+\+")

.Maximize

.LeftClick();


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();


void ExceptionEventHandler(object sender, GPAL.GPALEventArgs e)

{

Debug.WriteLine(e.Message);

Debug.WriteLine(e.ExceptionRaised?.Message);

}


CallIfStatus CallIfFound(Application application, List<IGPALAutomationElement> foundElements, List<IGPALAutomationElement> matchedElements, Selector selector, bool matchedAll)

{

CallIfStatus retVal = CallIfStatus.NotHandled;

foreach (IGPALAutomationElement element in foundElements)

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

return retVal;

}


CallIfStatus CallIfNotFound(Application application, List<IGPALAutomationElement> foundElements, List<IGPALAutomationElement> 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++) and Open launches it. Open is not an action, so a WaitFor right after it would not wait; WithWaitForWindowTimeout and WaitForWindowRegex wait for the window instead and return as soon as it appears. Maximize/LeftClick then bring it into a known state. ToGPALObject() returns the live IApplication you'll drive for the rest of the workflow.

IApplication application = GPAL.Application

.WithParameter("C:\sdi\ebay.words.txt")

.Open("C:\Program Files\Notepad++\notepad++.exe")

.ToGPALObject();


// Open is not an action, so a WaitFor here would not wait. Wait for the window instead;

// it returns as soon as the window appears.

application

.WithWaitForWindowTimeout(10);


application

.WaitForWindowRegex("Notepad\+\+")

.Maximize

.LeftClick();

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]");

NOTE

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

Integrations
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
    • 💬 Ask GPAL