uia 0.0.6.1 → 0.0.7

data/ChangeLog

@@ -1,3 +1,17 @@
+=== Version 0.0.7 / 2013-11-01
+*	Enhancements
+	*	added a base implementation for the Window pattern
+	*	added support for WindowPattern, TablePattern and TableItemPattern
+	*	Element#as raises UnsupportedPattern if the element does not implement it
+	*	added an Element#select method to filter descendants by:
+		-	pattern
+		-	name 
+		-	id
+
+*	Bug Fixes
+	*	modified ffi calls that return Element arrays to be individually GC'd.
+	This prevents FFI::ManagedStruct from being taken out from underneath you
+
 === Version 0.0.6.1 / 2013-10-30
 * Bug Fixes
 	*	Fixed issue when finding root children by RegEx initially

data/README.md

@@ -1,46 +1,127 @@
-# 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.
-
-```ruby
-require 'uia'
-
-include Uia
-
-main_window = find_element id: 'MainFormWindow'
-```
-
-### Finding Elements
-
-You can locate elements based on the following criteria:
-
-* `:id`         - find by their `AutomationId`
-* `:pid`        - find an element by their process id
-* `:handle`     - find an element by their native window handle
-* `:runtime_id` - find an element by their `RuntimeId` (i.e. `[42, 12345]`)
-
-## 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
+# 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.
+
+```ruby
+require 'uia'
+
+include Uia
+
+main_window = find_element id: 'MainFormWindow'
+
+# returns all elements under main_window that are of control type button
+main_window.select(control_type: :button)
+
+# returns the values of every element that implements the ValuePattern
+main_window.select(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`](http://msdn.microsoft.com/en-us/library/system.windows.automation.automationelement.aspx) 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.
+
+```ruby
+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
+
+## 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

data/ext/UiaDll/UiaDll/ElementMethods.cpp

@@ -97,33 +97,37 @@ extern "C" {
     return NULL;
   }
 
-  __declspec(dllexport) ElementsPtr Root_Children(char* errorInfo, const int errorInfoLength) {
+  __declspec(dllexport) int Root_Children(ElementInformation** children, char* errorInfo, const int errorInfoLength) {
     try {
-      return new Elements(Element::Windows);
+      auto windows = Element::Windows;
+      *children = ElementInformation::From(windows);
+      return windows->Length;
     } catch(Exception^ e) {
       StringHelper::CopyToUnmanagedString(e->Message, errorInfo, errorInfoLength);
-      return NULL;
+      return 0;
     }
   }
 
-  __declspec(dllexport) ElementsPtr Element_Children(ElementInformationPtr parentElement, char* errorInfo, const int errorLength) {
+  __declspec(dllexport) int Element_Children(ElementInformationPtr parentElement, ElementInformation** children, char* errorInfo, const int errorLength) {
     try {
-      return new Elements(Find(parentElement)->Children);
+      auto elements = Find(parentElement)->Children;
+      *children = ElementInformation::From(elements);
+      return elements->Length;
     } catch(Exception^ error) {
       StringHelper::CopyToUnmanagedString(error->Message, errorInfo, errorLength);
+      return 0;
     }
-
-    return NULL;
   }
 
-  __declspec(dllexport) ElementsPtr Element_Descendants(ElementInformationPtr parentElement, char* errorInfo, const int errorLength) {
+  __declspec(dllexport) int Element_Descendants(ElementInformationPtr parentElement, ElementInformation** descendants, char* errorInfo, const int errorLength) {
     try {
-      return new Elements(Find(parentElement)->Descendants);
+      auto elements = Find(parentElement)->Descendants;
+      *descendants = ElementInformation::From(elements);
+      return elements->Length;
     } catch(Exception^ error) {
       StringHelper::CopyToUnmanagedString(error->Message, errorInfo, errorLength);
+      return 0;
     }
-
-    return NULL;
   }
 
   __declspec(dllexport) void Element_Click(ElementInformationPtr element, char* errorInfo, const int errorLength) {

data/ext/UiaDll/UiaDll/ElementStructures.h

@@ -25,6 +25,18 @@ typedef struct _ElementInformation {
     return nullptr != element ? new _ElementInformation(element) : NULL;
   }
 
+  static _ElementInformation* From(...array<Element^>^ elements) {
+    if( nullptr == elements || elements->Length == 0 ) return NULL;
+
+    auto elementInformation = new _ElementInformation[elements->Length];
+    auto index = 0;
+    for each(auto element in elements) {
+      elementInformation[index++].Refresh(element);
+    }
+
+    return elementInformation;
+  }
+
   void Refresh(Element^ element) {
     Reset();
     id = StringHelper::ToUnmanaged(element->Id);
@@ -58,7 +70,9 @@ typedef struct _Elements {
 
   _Elements() : length(0), elements(NULL) {}
 
-  _Elements(array<Element^>^ elements) : elements(NULL) {
+  _Elements(array<Element^>^ elements) : length(0), elements(NULL) {
+    if( nullptr == elements ) return;
+
     length = elements->Length;
     if( length > 0 ) this->elements = new ElementInformation[length];
 

data/ext/UiaDll/UiaDll/PatternInformationStructures.h

@@ -3,6 +3,8 @@
 #include "StringHelper.h"
 #include "ElementStructures.h"
 
+using namespace System;
+using namespace System::Linq;
 using namespace System::Windows::Automation;
 
 typedef struct _ValuePatternInformation {
@@ -87,4 +89,78 @@ typedef struct _ExpandCollapseInfo {
   ~_ExpandCollapseInfo() {
     delete[] ExpandCollapseState;
   }
-} ExpandCollapseInfo, *ExpandCollapseInfoPtr;
+} ExpandCollapseInfo, *ExpandCollapseInfoPtr;
+
+typedef struct _WindowInformation {
+  char* VisualState;
+  char* InteractionState;
+  bool CanMinimize;
+  bool CanMaximize;
+  bool IsModal;
+  bool IsTopmost;
+
+  _WindowInformation(WindowVisualState visualState, WindowInteractionState interactionState) {
+    init(visualState, interactionState);
+  }
+
+  _WindowInformation(WindowPattern::WindowPatternInformation^ windowInformation) {
+    init(windowInformation->WindowVisualState, windowInformation->WindowInteractionState);
+    CanMinimize = windowInformation->CanMinimize;
+    CanMaximize = windowInformation->CanMaximize;
+    IsModal = windowInformation->IsModal;
+    IsTopmost = windowInformation->IsTopmost;
+  }
+
+  ~_WindowInformation() {
+    delete[] VisualState;
+    delete[] InteractionState;
+  }
+
+private:
+  void init(WindowVisualState visualState, WindowInteractionState interactionState) {
+    VisualState = StringHelper::ToUnmanaged(visualState.ToString());
+    InteractionState = StringHelper::ToUnmanaged(interactionState.ToString());
+  }
+
+} WindowInformation, *WindowInformationPtr;
+
+typedef struct _TableInformation {
+  int RowCount;
+  int ColumnCount;
+  ElementsPtr Headers;
+
+  _TableInformation(int rowCount, int columnCount, ...array<Element^> ^headers) {
+    init(rowCount, columnCount, headers);
+  }
+
+  _TableInformation(TablePattern::TablePatternInformation^ tableInfo) {
+    auto headers = tableInfo->GetColumnHeaders();
+    auto toElementFunc = gcnew Func<AutomationElement^, Element^>(Element::From);
+
+    init(tableInfo->RowCount, tableInfo->ColumnCount, Enumerable::ToArray(Enumerable::Select<AutomationElement^, Element^>(headers, toElementFunc)));
+  }
+
+  ~_TableInformation() {
+    delete Headers;
+  }
+
+private:
+  void init(int rowCount, int columnCount, ...array<Element^> ^headers) {
+    RowCount = rowCount;
+    ColumnCount = columnCount;
+
+    Headers = new Elements(headers);
+  }
+
+} TableInformation, *TableInformationPtr;
+
+typedef struct _TableItemInformation {
+  int Column;
+  int Row;
+
+  _TableItemInformation(TableItemPattern::TableItemPatternInformation^ tableItemInfo) {
+    Column = tableItemInfo->Column;
+    Row = tableItemInfo->Row;
+  }
+
+} TableItemInformation, *TableItemInformationPtr;

data/ext/UiaDll/UiaDll/SelectionItemMethods.cpp

@@ -11,6 +11,7 @@ extern "C" {
       return new SelectionItemInformation(info);
     } catch(Exception^ e) {
       StringHelper::CopyToUnmanagedString(e->Message, errorInfo, errorInfoLength);
+      return NULL;
     }
   }
 

data/ext/UiaDll/UiaDll/TableItemMethods.cpp

@@ -0,0 +1,16 @@
+#include "Stdafx.h"
+
+extern "C" {
+  __declspec(dllexport) void TableItem_Release(TableItemInformationPtr tableItemInfo) {
+    delete tableItemInfo;
+  }
+
+  __declspec(dllexport) TableItemInformationPtr TableItem_Information(ElementInformationPtr element, char* errorInfo, const int errorInfoLength) {
+    try {
+      return new TableItemInformation(Find(element)->As<TableItemPattern^>(TableItemPattern::Pattern)->Current);
+    } catch(Exception^ e) {
+      StringHelper::CopyToUnmanagedString(e->Message, errorInfo, errorInfoLength);
+      return NULL;
+    }
+  }
+}

data/ext/UiaDll/UiaDll/TableMethods.cpp

@@ -0,0 +1,16 @@
+#include "Stdafx.h"
+
+extern "C" {
+  __declspec(dllexport) void Table_Release(TableInformationPtr tableInfo) {
+    delete tableInfo;
+  }
+
+  __declspec(dllexport) TableInformationPtr Table_Information(ElementInformationPtr element, char* errorInfo, const int errorInfoLength) {
+    try {
+      return new TableInformation(Find(element)->As<TablePattern^>(TablePattern::Pattern)->Current);
+    } catch(Exception^ e) {
+      StringHelper::CopyToUnmanagedString(e->Message, errorInfo, errorInfoLength);
+      return NULL;
+    }
+  }
+}

data/ext/UiaDll/UiaDll/UiaDll.vcxproj

@@ -72,6 +72,7 @@
   </ItemDefinitionGroup>
   <ItemGroup>
     <Reference Include="System" />
+    <Reference Include="System.Core" />
     <Reference Include="System.Data" />
     <Reference Include="System.Xml" />
     <Reference Include="UIAutomationClient" />
@@ -97,9 +98,12 @@
       <PrecompiledHeader Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">Create</PrecompiledHeader>
       <PrecompiledHeader Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">Create</PrecompiledHeader>
     </ClCompile>
+    <ClCompile Include="TableItemMethods.cpp" />
+    <ClCompile Include="TableMethods.cpp" />
     <ClCompile Include="ToggleMethods.cpp" />
     <ClCompile Include="UiaDll.cpp" />
     <ClCompile Include="ValuePatternMethods.cpp" />
+    <ClCompile Include="WindowMethods.cpp" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\UIA.Helper\UIA.Helper.csproj">

data/ext/UiaDll/UiaDll/UiaDll.vcxproj.filters

@@ -71,5 +71,14 @@
     <ClCompile Include="ExpandCollapseMethods.cpp">
       <Filter>Source Files\Patterns</Filter>
     </ClCompile>
+    <ClCompile Include="WindowMethods.cpp">
+      <Filter>Source Files\Patterns</Filter>
+    </ClCompile>
+    <ClCompile Include="TableMethods.cpp">
+      <Filter>Source Files\Patterns</Filter>
+    </ClCompile>
+    <ClCompile Include="TableItemMethods.cpp">
+      <Filter>Source Files\Patterns</Filter>
+    </ClCompile>
   </ItemGroup>
 </Project>

data/ext/UiaDll/UiaDll/WindowMethods.cpp

@@ -0,0 +1,24 @@
+#include "Stdafx.h"
+
+extern "C" {
+  __declspec(dllexport) void Window_Release(WindowInformationPtr windowInformation) {
+    delete windowInformation;
+  }
+
+  __declspec(dllexport) WindowInformationPtr Window_Information(ElementInformationPtr element, char* errorInfo, const int errorInfoLength) {
+    try {
+      return new WindowInformation(Find(element)->As<WindowPattern^>(WindowPattern::Pattern)->Current);
+    } catch(Exception^ e) {
+      StringHelper::CopyToUnmanagedString(e->Message, errorInfo, errorInfoLength);
+      return NULL;
+    }
+  }
+
+  __declspec(dllexport) void Window_SetVisualState(ElementInformationPtr element, const char* visualState, char* errorInfo, const int errorInfoLength) {
+    try {
+      Find(element)->As<WindowPattern^>(WindowPattern::Pattern)->SetWindowVisualState((WindowVisualState) Enum::Parse(WindowVisualState::typeid, gcnew String(visualState), false));
+    } catch(Exception^ e) {
+      StringHelper::CopyToUnmanagedString(e->Message, errorInfo, errorInfoLength);
+    }
+  }
+}

data/ext/UiaDll/UiaDll.Test/ElementInformationTest.cpp

@@ -103,3 +103,18 @@ TEST_F(ElementInformationTest, ItCanBeRefreshed)
   ASSERT_STREQ("Refreshed", elementInformation.name);
   ASSERT_EQ(123, elementInformation.nativeWindowHandle);
 }
+
+TEST_F(ElementInformationTest, ItCanBeInitializedFromManyElements) {
+  auto elementInformation = ElementInformation::From(gcnew ElementStub("First Element", 123), gcnew ElementStub("Second Element", 456));
+
+  ASSERT_STREQ("First Element", elementInformation[0].name);
+  ASSERT_STREQ("Second Element", elementInformation[1].name);
+  delete[] elementInformation;
+}
+
+TEST_F(ElementInformationTest, ItIsNullIfThereAreNoElements) {
+  ASSERT_EQ(NULL, ElementInformation::From(gcnew array<Element^>(0)));
+
+  array<Element^>^ nullElements = nullptr;
+  ASSERT_EQ(NULL, ElementInformation::From(nullElements));
+}

data/ext/UiaDll/UiaDll.Test/PatternInformationTest.cpp

@@ -3,6 +3,8 @@
 #include <PatternInformationStructures.h>
 #include "ElementStub.h"
 
+using namespace System::Windows::Automation;
+
 TEST(ValueInformation, CanBeInitialized)
 {
   auto valueInfo = new ValuePatternInformation("Whatever", true);
@@ -32,4 +34,15 @@ TEST(SelectionItemInformation, CanBeInitialized)
 TEST(ExpandCollapseInfo, CanBeInitialized) {
   auto expandCollapseInfo = ExpandCollapseInfo("Collapsed");
   ASSERT_STREQ("Collapsed", expandCollapseInfo.ExpandCollapseState);
-}
+}
+
+TEST(WindowInformation, CanBeInitialized) {
+  auto windowInformation = WindowInformation(WindowVisualState::Minimized, WindowInteractionState::Closing);
+  ASSERT_STREQ("Minimized", windowInformation.VisualState);
+  ASSERT_STREQ("Closing", windowInformation.InteractionState);
+}
+
+TEST(TableInformation, NullHeadersYieldsEmptyElements) {
+  auto tableInformation = TableInformation(0, 0, nullptr);
+  ASSERT_EQ(0, tableInformation.Headers->length);
+}

data/ext/UiaDll/UiaDll.Test/UiaDll.Test.vcxproj

@@ -84,9 +84,11 @@
   </ItemDefinitionGroup>
   <ItemGroup>
     <Reference Include="System" />
+    <Reference Include="System.Core" />
     <Reference Include="System.Data" />
     <Reference Include="System.Xml" />
     <Reference Include="UIAutomationClient" />
+    <Reference Include="UIAutomationTypes" />
   </ItemGroup>
   <ItemGroup>
     <Text Include="ReadMe.txt" />

data/lib/core_ext/string.rb

@@ -0,0 +1,5 @@
+class String
+  def to_snake_case_sym
+    self.gsub(/(.)([A-Z])/, '\1_\2').downcase.to_sym
+  end
+end

data/lib/core_ext/symbol.rb

@@ -0,0 +1,5 @@
+class Symbol
+  def to_camelized_s
+    self.to_s.split('_').map(&:capitalize).join(' ')
+  end
+end

data/lib/uia/element.rb

@@ -1,12 +1,12 @@
-require 'uia/patterns/expand_collapse'
-require 'uia/patterns/invoke'
-require 'uia/patterns/selection'
-require 'uia/patterns/selection_item'
-require 'uia/patterns/toggle'
-require 'uia/patterns/value'
 require 'uia/library/element_attributes'
 
 module Uia
+  class UnsupportedPattern < StandardError
+    def initialize(expected, actual)
+      super "Pattern #{expected} not found in #{actual}"
+    end
+  end
+
   class Element
     extend ElementAttributes
 
@@ -15,7 +15,7 @@ module Uia
       @default = lambda { [:unknown] }
     end
 
-    element_attr :id, :name, :handle, :runtime_id, :enabled?, :class_name
+    element_attr :id, :name, :handle, :runtime_id, :enabled?, :class_name, :children, :descendants
 
     def control_type
       Library::Constants::ControlTypes.find(@default) { |_, v| v == @element.control_type_id }.first
@@ -35,23 +35,32 @@ module Uia
       end
     end
 
-    def as(pattern)
-      which =  "Uia::Patterns::#{pattern.to_s.capitalize}".split('::').reduce(Object) do |m, current|
-        m.const_get current.split('_').map(&:capitalize).join
+    def locators_match?(locator)
+      locator.all? do |locator, value|
+        case locator
+          when :pattern
+            patterns.include? value
+          else
+            send(locator) == value
+        end
       end
-      extend which
     end
 
-    def patterns
-      @element.pattern_ids.map {|id| Library::Constants::Patterns.find(@default) { |_, v| v == id }.first }
+    def select(locator)
+      descendants.select { |e| e.locators_match? locator }
     end
 
-    def children
-      @element.children
+    def as(pattern)
+      raise UnsupportedPattern.new(pattern, patterns) unless patterns.include? pattern
+
+      which = "Uia::Patterns::#{pattern.to_s.capitalize}".split('::').reduce(Object) do |m, current|
+        m.const_get current.split('_').map(&:capitalize).join
+      end
+      extend which
     end
 
-    def descendants
-      @element.descendants
+    def patterns
+      @element.pattern_ids.map { |id| Library::Constants::Patterns.find(@default) { |_, v| v == id }.first }
     end
 
     def click