Project

uia

0.01
Low commit activity in last 3 years
No release in over a year
A low-level wrapper around Microsoft UI Automation for ruby
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

>= 1.3
~> 13.0
~> 3.9

Runtime

~> 1.14
 Project Readme

Uia

The Uia gem is a low-level driver for interacting with Microsoft UIA elements in a Windows environment.

Installation

Add this line to your application's Gemfile:

gem 'uia'

And then execute:

$ bundle

Or install it yourself as:

$ gem install uia

Usage

Getting started with uia is easy. Simply require uia and then include the Uia module wherever you would like to use it.

require 'uia'

main_window = Uia.find_element id: 'MainFormWindow'

# returns all elements under main_window that are of control type button
main_window.find_all(control_type: :button)

# returns the values of every element that implements the ValuePattern
main_window.find_all(pattern: :value).map {|e| e.as :value}.map &:value

Finding Elements

You can locate elements based on the following criteria:

  • :id - find by their AutomationId (String and Regexp)
  • :pid - find an element by their process id (String and Regexp)
  • :handle - find an element by their native window handle (Fixnum)
  • :runtime_id - find an element by their RuntimeId (i.e. [42, 12345])

Element

The Element class is a representation of the AutomationElement class in Microsoft UIA. It is the object that is returned from the root Uia#find_element as well as the Element#find and Element#select methods.

Properties

  • id - returns the automation id of th element
  • name - returns the name of the element
  • handle - returns the native window handle of the element
  • class_name - returns the class name of the element
  • patterns - returns the patterns that element implements (i.e. [:window, :transform])

Methods

#as

The #as method will decorate the Element with the specific pattern that you would like to interact with.

button = Uia.find_element(id: /MainForm/).find(id: 'aboutButton').as :invoke
button.invoke

Patterns

Window

Decorates your Element with the following methods:

  • visual_state - :minimized, :maximized, :normal
  • visual_state= - sets the visual state
  • can_minimize? / can_maximize?
  • modal?
  • topmost?
  • interaction_state - :blocked_by_modalwindow, :closing, :not_responding, :ready_for_user_interaction, :running

Value

  • value - returns the value
  • value= - sets the value
  • read_only?

Invoke

  • invoke - invokes the control

ExpandCollapse

  • expand - expands the element
  • collapse - collapses the element
  • expand_collapse_state - :collapsed, :expanded, :leaf_node, :partially_expanded

Toggle

  • toggle - toggles the element
  • toggle_state - :on, :off, :indeterminate
  • toggle_state= - sets the toggle state

Table

  • row_count
  • column_count
  • headers - returns the Element objects that make up the headers
  • rows - returns all Element objects that are of control type data_item
  • extends each Element with Table::Row

Table::Row

  • items - returns all descendants of the row that implement the :table_item pattern

TableItem

  • column
  • row

Selection

  • selection_items - return all descendants of the Selection that implement the :selection_item pattern
  • multi_select?
  • selection_required?

SelectionItem

  • select - selects the item
  • add_to_selection - adds the element to the selection
  • remove_from_selection - removes the element from the selection
  • selected? - whether or not it is selected
  • container - the Selection container

Known bug

Crash with [BUG] Segmentation fault. Cause of this is ffi gem bug. Periodically the ffi team releases bad gem ffi/ffi#649 ffi/ffi#302. The conditional solution is described here

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request