UIA v2
Posted: 24 Jan 2023, 10:34
This is an UIAutomation library for AHK v2. Credit to thqby's work who's library I based mine on.
The library is available here: https://github.com/Descolada/UIA-v2
Learn more about UIAutomation from the Wiki
Videos: Tutorial Series, Joe the Automator, Axlefublr
Quick Start Guide
1. Run UIA.ahk as a stand-alone script to display UIAViewer. Press the "Start capturing" button to start inspecting elements: then you can see element properties, patterns (ways to interact), the UIA tree (if you hold the mouse still for a bit), and the UIA path for elements.
2. Include UIA.ahk in your script to use it as a library. UIA doesn't have to be initialized in any way.
3. Get a starting point element with UIA.ElementFromHandle(WinTitle), UIA.ElementFromPoint(X, Y), or other methods described in the Wiki.
4. Traverse to the element of interest with the UIA path using Element[path] such as Element[{T:10}, {T0,N:"Save"}], or Element.FindElement(condition). Condition is an object determining what properties need to be filled: for example {Name:"Save"} requires the Name property to be "Save". Read more about Conditions in the Wiki: multiple conditions can be combined with "and" or "or" conditions, for negation there is the "not" condition.
5. Get property values displayed in UIAViewer with Element.PropertyName. Some properties such as Value can sometimes be assigned with Element.Value := "newvalue"
6. Use pattern methods with Element.Method() such as the Toggle method from the TogglePattern: Element.Toggle(); or use it through the pattern object itself: Element.TogglePattern.Toggle. For clicking an element there is the method Element.Click().
7. Some methods require special values (constants, or otherwise known as enumerations), which can be accessed with UIA.EnumerationClass.EnumerationName such as UIA.Type.Button. This you can use whenever a method requires a constant, or a property returns one: Element.Type returns such a value, which you can either compare with Element.Type == UIA.Type.Button or get the enumeration name with UIA.Type[Element.Type] => "Button". If a method requires an enumeration, then it can usually be used only by the name: Element.FindElement(condition, "Children") which uses the value of UIA.TreeScope.Children.
8. Debug with Element.Highlight() which highlights the element, or Element.Dump() or Element.DumpAll() which creates a string containing some properties of the element (display it with MsgBox for example).
Main changes from UIA_Interface.ahk
1) UIA doesn't need to be initialized, just start using it
2) The main Find methods are FindElement and FindElements. Errors are thrown if an element is not found.
3) Conditions have been replaced by condition object notation such as {Name:"Something"}. {} creates and-condition, [] creates or-condition, index, matchmode and casesense keys can be set.
4) Elements can accessed with array notation: Element[2,1,4...] or Element[condition1, condition2...]; alternatively ElementFromPath can be used
5) Arguments have been switched around for many methods, such as for cache-related methods the cacheRequest argument is now the first
6) UIA constants/enumerations are included in the main UIA object. For example UIA.Type.Button == 50000
7) UIAViewer is built into the library: when ran directly the UIAViewer will show, when included in another script then it won't show (but can be opened by calling UIA.Viewer())
8) UIAViewer creates a "UIA path" that can be used with the array notation to get elements
Read from the Wiki about details for all of these, also take a look at the included examples.
If you have any suggestions or comments about what should be changed or improved, please leave a comment. Also feel free to create Pull requests in GitHub.
The library is available here: https://github.com/Descolada/UIA-v2
Learn more about UIAutomation from the Wiki
Videos: Tutorial Series, Joe the Automator, Axlefublr
Quick Start Guide
1. Run UIA.ahk as a stand-alone script to display UIAViewer. Press the "Start capturing" button to start inspecting elements: then you can see element properties, patterns (ways to interact), the UIA tree (if you hold the mouse still for a bit), and the UIA path for elements.
2. Include UIA.ahk in your script to use it as a library. UIA doesn't have to be initialized in any way.
3. Get a starting point element with UIA.ElementFromHandle(WinTitle), UIA.ElementFromPoint(X, Y), or other methods described in the Wiki.
4. Traverse to the element of interest with the UIA path using Element[path] such as Element[{T:10}, {T0,N:"Save"}], or Element.FindElement(condition). Condition is an object determining what properties need to be filled: for example {Name:"Save"} requires the Name property to be "Save". Read more about Conditions in the Wiki: multiple conditions can be combined with "and" or "or" conditions, for negation there is the "not" condition.
5. Get property values displayed in UIAViewer with Element.PropertyName. Some properties such as Value can sometimes be assigned with Element.Value := "newvalue"
6. Use pattern methods with Element.Method() such as the Toggle method from the TogglePattern: Element.Toggle(); or use it through the pattern object itself: Element.TogglePattern.Toggle. For clicking an element there is the method Element.Click().
7. Some methods require special values (constants, or otherwise known as enumerations), which can be accessed with UIA.EnumerationClass.EnumerationName such as UIA.Type.Button. This you can use whenever a method requires a constant, or a property returns one: Element.Type returns such a value, which you can either compare with Element.Type == UIA.Type.Button or get the enumeration name with UIA.Type[Element.Type] => "Button". If a method requires an enumeration, then it can usually be used only by the name: Element.FindElement(condition, "Children") which uses the value of UIA.TreeScope.Children.
8. Debug with Element.Highlight() which highlights the element, or Element.Dump() or Element.DumpAll() which creates a string containing some properties of the element (display it with MsgBox for example).
Main changes from UIA_Interface.ahk
1) UIA doesn't need to be initialized, just start using it
2) The main Find methods are FindElement and FindElements. Errors are thrown if an element is not found.
3) Conditions have been replaced by condition object notation such as {Name:"Something"}. {} creates and-condition, [] creates or-condition, index, matchmode and casesense keys can be set.
4) Elements can accessed with array notation: Element[2,1,4...] or Element[condition1, condition2...]; alternatively ElementFromPath can be used
5) Arguments have been switched around for many methods, such as for cache-related methods the cacheRequest argument is now the first
6) UIA constants/enumerations are included in the main UIA object. For example UIA.Type.Button == 50000
7) UIAViewer is built into the library: when ran directly the UIAViewer will show, when included in another script then it won't show (but can be opened by calling UIA.Viewer())
8) UIAViewer creates a "UIA path" that can be used with the array notation to get elements
Read from the Wiki about details for all of these, also take a look at the included examples.
If you have any suggestions or comments about what should be changed or improved, please leave a comment. Also feel free to create Pull requests in GitHub.