bewildr 0.1.9 → 0.1.10

data/README.rdoc

@@ -9,7 +9,7 @@ Documentation is on the way; until then, take a look at the tests or read the AP
 ==Getting started
 ===Dependencies
 1. Install .net 3 and 4 (http://www.microsoft.com/downloads/details.aspx?FamilyID=10cc340b-f857-4a14-83f5-25634c3bf043&displaylang=en & http://msdn.microsoft.com/en-us/netframework/aa569263.aspx)
-2. Install the latest ironruby (http://www.ironruby.net/), and for your own sanity install it in c:\\\\ironruby instead of the default location.
+2. Install the latest ironruby (http://ironruby.codeplex.com/), and for your own sanity install it in c:\\\\ironruby instead of the default location.
 3. You'll need at least rubygems version 1.3.6:
   gem update --system
 

data/Rakefile

@@ -10,7 +10,7 @@ require 'cucumber/rake/task'
 
 spec = Gem::Specification.new do |s|
   s.name = 'bewildr'
-  s.version = '0.1.9'
+  s.version = '0.1.10'
   s.has_rdoc = true
   s.extra_rdoc_files = ['README.rdoc', 'LICENSE']
   s.summary = 'Test WPF UI apps with IronRuby'

data/lib/bewildr/control_patterns/expand_collapse_pattern.rb

@@ -3,14 +3,21 @@
 module Bewildr
   module ControlPatterns
     module ExpandCollapsePattern
+      #Expands the element - use to open combo boxes
       def expand
         @automation_element.get_current_pattern(System::Windows::Automation::ExpandCollapsePattern.pattern).expand unless expand_state == :expanded or expand_state == :leaf
       end
 
+      #Collapses the element - use to close combo boxes
       def collapse
         @automation_element.get_current_pattern(System::Windows::Automation::ExpandCollapsePattern.pattern).collapse unless expand_state == :collapsed or expand_state == :leaf
       end
 
+      #Returns the expand-state of the element. The available states are:
+      #  :collapsed
+      #  :expanded
+      #  :partially_expanded
+      #  :leaf
       def expand_state
         case @automation_element.get_current_pattern(System::Windows::Automation::ExpandCollapsePattern.pattern).current.expand_collapse_state
         when System::Windows::Automation::ExpandCollapseState.collapsed           then return :collapsed

data/lib/bewildr/control_patterns/grid_pattern.rb

@@ -3,14 +3,17 @@
 module Bewildr
   module ControlPatterns
     module GridPattern
+      #Returns the number of rows in the grid
       def row_count
         @automation_element.get_current_pattern(System::Windows::Automation::GridPattern.pattern).current.row_count.to_i
       end
 
+      #Returns the number of columns in the grid
       def column_count
         @automation_element.get_current_pattern(System::Windows::Automation::GridPattern.pattern).current.column_count.to_i
       end
 
+      #Returns an item from the grid
       def get_item(row, column)
         item = @automation_element.get_current_pattern(System::Windows::Automation::GridPattern.pattern).get_item(row, column)
         Bewildr::Element.new(item)

data/lib/bewildr/control_patterns/range_value_pattern.rb

@@ -3,18 +3,22 @@
 module Bewildr
   module ControlPatterns
     module RangeValuePattern
+      #Returns the current value of the element
       def value
         @automation_element.get_current_pattern(System::Windows::Automation::RangeValuePattern.pattern).current.value.to_f
       end
 
+      #Sets the value of the element
       def value=(input)
         @automation_element.get_current_pattern(System::Windows::Automation::RangeValuePattern.pattern).set_value(input.to_f)
       end
 
+      #Returns the maximum value of the element
       def maximum
         @automation_element.get_current_pattern(System::Windows::Automation::RangeValuePattern.pattern).current.maximum.to_f
       end
 
+      #Returns the minimum value of the element
       def minimum
         @automation_element.get_current_pattern(System::Windows::Automation::RangeValuePattern.pattern).current.minimum.to_f
       end

data/lib/bewildr/control_patterns/scroll_pattern.rb

@@ -3,35 +3,36 @@
 module Bewildr
   module ControlPatterns
     module ScrollPattern
-      def self.extended(base)
-        
-        base.instance_eval do
-          def vertically_scrollable
-            @automation_element.get_current_pattern(System::Windows::Automation::ScrollPattern.pattern).current.vertically_scrollable
-          end
+      #Returns true if the element is vertically scrollable, false if it's not
+      def vertically_scrollable
+        @automation_element.get_current_pattern(System::Windows::Automation::ScrollPattern.pattern).current.vertically_scrollable
+      end
+
+      #Returns the current vertical scroll percent
+      def vertical_scroll_percent
+        @automation_element.get_current_pattern(System::Windows::Automation::ScrollPattern.pattern).current.vertical_scroll_percent.to_f
+      end
+      alias :scroll_percent :vertical_scroll_percent
 
-          def vertical_scroll_percent
-            @automation_element.get_current_pattern(System::Windows::Automation::ScrollPattern.pattern).current.vertical_scroll_percent.to_f
-          end
-          alias :scroll_percent :vertical_scroll_percent
+      #Set the scroll percent of the element
+      def set_scroll_percent(percent_horizontal, percent_vertical)
+        @automation_element.get_current_pattern(System::Windows::Automation::ScrollPattern.pattern).set_scroll_percent(percent_horizontal, percent_vertical)
+      end
 
-          def set_scroll_percent(percent_horizontal, percent_vertical)
-            @automation_element.get_current_pattern(System::Windows::Automation::ScrollPattern.pattern).set_scroll_percent(percent_horizontal, percent_vertical)
-          end
-      
-          def scroll_vertically_to(target_percentage)
-            set_scroll_percent(System::Windows::Automation::ScrollPattern.NoScroll, target_percentage)
-          end
-          alias :scroll_to :scroll_vertically_to
+      #Set the vertical scroll percent of the element
+      def scroll_vertically_to(target_percentage)
+        set_scroll_percent(System::Windows::Automation::ScrollPattern.NoScroll, target_percentage)
+      end
+      alias :scroll_to :scroll_vertically_to
 
-          def scroll_horizontally_to(target_percentage)
-            set_scroll_percent(target_percentage, System::Windows::Automation::ScrollPattern.NoScroll)
-          end
+      #Set the horizontal scroll percent of the element
+      def scroll_horizontally_to(target_percentage)
+        set_scroll_percent(target_percentage, System::Windows::Automation::ScrollPattern.NoScroll)
+      end
 
-          def scroll_down_one_page
-            @automation_element.get_current_pattern(System::Windows::Automation::ScrollPattern.pattern).scroll_vertical(System::Windows::Automation::ScrollAmount.LargeIncrement)
-          end
-        end
+      #Scrolls vertically down by one 'page'
+      def scroll_down_one_page
+        @automation_element.get_current_pattern(System::Windows::Automation::ScrollPattern.pattern).scroll_vertical(System::Windows::Automation::ScrollAmount.LargeIncrement)
       end
     end
   end

data/lib/bewildr/control_patterns/selection_item_pattern.rb

@@ -4,14 +4,17 @@
 module Bewildr
   module ControlPatterns
     module SelectionItemPattern
+      #Selects the element
       def select
         @automation_element.get_current_pattern(System::Windows::Automation::SelectionItemPattern.pattern).select
       end
 
+      #Returns true if the element is selected, false if it's not
       def selected?
         @automation_element.get_current_pattern(System::Windows::Automation::SelectionItemPattern.pattern).current.is_selected
       end
 
+      #Returns false if the element is selected, true if it's not
       def unselected?
         !selected?
       end

data/lib/bewildr/control_patterns/selection_pattern.rb

@@ -3,6 +3,7 @@
 module Bewildr
   module ControlPatterns
     module SelectionPattern
+      #Returns the elements that are selected
       def get_selection
         my_selected_items = @automation_element.get_current_pattern(System::Windows::Automation::SelectionPattern.pattern).current.get_selection
 
@@ -13,11 +14,13 @@ module Bewildr
         item_array.to_a.collect {|item| Bewildr::Element.new(item)}
       end
 
+      #Returns true if more than one selection is possible, false if it's not
       def multi_selectable?
         @automation_element.get_current_pattern(System::Windows::Automation::SelectionPattern.pattern).current.can_select_multiple
       end
       alias :can_select_multiple? :multi_selectable?
 
+      #Returns the (first - if relevant) selected item
       def selected
         multi_selectable? ? get_selection : get_selection.first
       end

data/lib/bewildr/control_patterns/table_item_pattern.rb

@@ -3,10 +3,12 @@
 module Bewildr
   module ControlPatterns
     module TableItemPattern
+      #Returns the number of rows the element spans
       def row_span
         @automation_element.get_current_pattern(System::Windows::Automation::TableItemPattern.pattern).current.row_span.to_i
       end
 
+      #Returns the number of columns the element spans
       def column_span
         @automation_element.get_current_pattern(System::Windows::Automation::TableItemPattern.pattern).current.column_span.to_i
       end

data/lib/bewildr/control_patterns/table_pattern.rb

@@ -3,6 +3,7 @@
 module Bewildr
   module ControlPatterns
     module TablePattern
+      #Returns an array of elements containing the column headers
       def column_headers
         #the following line seems to prompt the table pattern into giving up the column header
         #information that's called on the line that follows it. Weird? tell me about it...
@@ -12,6 +13,7 @@ module Bewildr
         end
       end
 
+      #Returns a string array containing the column header names
       def column_header_names
         column_headers.collect {|header| header.name }
       end

data/lib/bewildr/control_patterns/text_pattern.rb

@@ -3,10 +3,12 @@
 module Bewildr
   module ControlPatterns
     module TextPattern
+      #Selects all of the text in the element
       def select_all
         @automation_element.get_current_pattern(System::Windows::Automation::TextPattern.pattern).document_range.select
       end
 
+      #Returns all the element's text
       def get_text
         @automation_element.get_current_pattern(System::Windows::Automation::TextPattern.pattern).document_range.get_text(-1).to_s
       end

data/lib/bewildr/control_patterns/toggle_pattern.rb

@@ -2,51 +2,76 @@
 
 module Bewildr
   module ControlPatterns
-    module TogglePattern
+    module TogglePatternForButton
+      #Toggle on the element
+      def toggle_on
+        set_state_to(:on)
+      end
 
-      def self.extended(base)
-        base.instance_eval do
-          case @control_type
-          when :check_box
-            def check
-              set_state_to :on
-            end
+      #Toggle off the element
+      def toggle_off
+        set_state_to(:off)
+      end
 
-            def uncheck
-              set_state_to :off
-            end
+      #Return the toggle state. The available states are:
+      #  :on
+      #  :off
+      #  :indeterminate
+      def toggle_state
+        state
+      end
 
-            def checked?
-              state == :on
-            end
+      #Toggle the element
+      def toggle
+        flip_state
+      end
+    end
 
-            def unchecked?
-              state == :off
-            end
+    module TogglePatternForCheckBox
+      #Check the element
+      def check
+        set_state_to :on
+      end
 
-            def indeterminate?
-              state == :indeterminate
-            end
+      #Uncheck the element
+      def uncheck
+        set_state_to :off
+      end
 
-            def checked_state
-              state
-            end
-          when :button
-            def toggle_on
-               set_state_to(:on)
-            end
+      #Return true if the element is checked, false if it's not
+      def checked?
+        state == :on
+      end
+
+      #Return true if the element is unchecked, false if it's not
+      def unchecked?
+        state == :off
+      end
 
-            def toggle_off
-               set_state_to(:off)
-            end
+      #Return true if the element is indeterminate, false if it's not
+      def indeterminate?
+        state == :indeterminate
+      end
 
-            def toggle_state
-              state
-            end
+      #Returns the checked state. The available states are:
+      #  :on
+      #  :off
+      #  :indeterminate
+      def checked_state
+        state
+      end
+    end
 
-            def toggle
-              flip_state
-            end
+    #These are not the toggle patterns you are looking for [wave of the hand/]. If you are dealing with a button, look for Bewildr::ControlPatterns::TogglePatternForButton.
+    #If you're dealing with a checkbox, take a look at Bewildr::ControlPatterns::TogglePatternForCheckBox
+    module TogglePattern
+      def self.extended(base)
+        base.instance_eval do
+          case @control_type
+          when :check_box
+            base.extend(Bewildr::ControlPatterns::TogglePatternForCheckBox)
+          when :button
+            base.extend(Bewildr::ControlPatterns::TogglePatternForButton)
           end
         end
       end

data/lib/bewildr/control_patterns/value_pattern.rb

@@ -3,15 +3,18 @@
 module Bewildr
   module ControlPatterns
     module ValuePattern
+      #Returns true if the element is a password field, false if it's not
       def password_field?
         @automation_element.current.class_name.to_s == "PasswordBox" ? true : false
       end
 
+      #Returns the element's text
       def text
         raise Bewildr::PasswordFieldReadAttempt, "You can't get the text of a password field" if password_field?
         @automation_element.get_current_pattern(System::Windows::Automation::ValuePattern.pattern).current.value.to_s
       end
 
+      #Sets the element's text
       def text=(input)
         raise Bewildr::ElementNotEnabled unless enabled?
         @automation_element.get_current_pattern(System::Windows::Automation::ValuePattern.pattern).set_value(input)

data/lib/bewildr/control_patterns/window_pattern.rb

@@ -3,22 +3,30 @@
 module Bewildr
   module ControlPatterns
     module WindowPattern
+      #Closes the window
       def close
         @automation_element.get_current_pattern(System::Windows::Automation::WindowPattern.pattern).close
       end
 
+      #Minimizes the window
       def minimize
         @automation_element.get_current_pattern(System::Windows::Automation::WindowPattern.pattern).set_window_visual_state(System::Windows::Automation::WindowVisualState.minimized)
       end
 
+      #Maximizes the window
       def maximize
         @automation_element.get_current_pattern(System::Windows::Automation::WindowPattern.pattern).set_window_visual_state(System::Windows::Automation::WindowVisualState.maximized)
       end
 
+      #Restores the window
       def restore
         @automation_element.get_current_pattern(System::Windows::Automation::WindowPattern.pattern).set_window_visual_state(System::Windows::Automation::WindowVisualState.normal)
       end
 
+      #Returns the visual state of the window. Available states are:
+      #  :maximized
+      #  :minimized
+      #  :normal
       def visual_state
         case @automation_element.get_current_pattern(System::Windows::Automation::WindowPattern.pattern).current.window_visual_state
         when System::Windows::Automation::WindowVisualState.maximized then return :maximized

data/lib/bewildr/control_type_additions/combo_box_additions.rb

@@ -3,79 +3,84 @@
 module Bewildr
   module ControlTypeAdditions
     module ComboBoxAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def items
-            my_list_items = list_items
-            return nil if my_list_items.nil?
-            my_list_items.collect {|item| item.name}
-          end
+      #Returns a string array containing the element's item names
+      def items
+        my_list_items = list_items
+        return nil if my_list_items.nil?
+        my_list_items.collect {|item| item.name}
+      end
 
-          def list_items
-            begin
-              expand_combo
-              bewildr_list_items = get(:type => :list_item, :scope => :children, :how_many => :all)
-              bewildr_list_items.nil? ? nil : bewildr_list_items
-            ensure
-              collapse_combo
-            end
-          end
+      #Returns an array containing the combobox items
+      def list_items
+        begin
+          expand_combo
+          bewildr_list_items = get(:type => :list_item, :scope => :children, :how_many => :all)
+          bewildr_list_items.nil? ? nil : bewildr_list_items
+        ensure
+          collapse_combo
+        end
+      end
 
-          def count
-            my_items = items
-            my_items.nil? ? 0 : my_items.size
-          end
+      #Returns the number of items in the combobox
+      def count
+        my_items = items
+        my_items.nil? ? 0 : my_items.size
+      end
 
-          def select(input)
-            case input
-            when String then select_by_name(input)
-            when Integer then select_by_index(input)
-            else raise ArgumentError, "Select by name or by index"
-            end
-          end
+      #Selects a combobox item. Takes a string (and selects the first item whose name matches) or an integer and selects the respective element
+      def select(input)
+        case input
+        when String then select_by_name(input)
+        when Integer then select_by_index(input)
+        else raise ArgumentError, "Select by name or by index"
+        end
+      end
 
-          def select_by_name(input)
-            begin
-              expand_combo
-              my_item = list_items.find {|item| item.name == input}
-              raise Bewildr::NoSuchItemInComboBox if my_item.nil?
-              my_item.select
-            ensure
-              collapse_combo
-            end
-          end
+      #Selects the first item whose name matches the input
+      def select_by_name(input)
+        begin
+          expand_combo
+          my_item = list_items.find {|item| item.name == input}
+          raise Bewildr::NoSuchItemInComboBox if my_item.nil?
+          my_item.select
+        ensure
+          collapse_combo
+        end
+      end
 
-          def select_by_index(input)
-            raise "Index must be 0 or greater" if input < 0
-            begin
-              expand_combo
-              list_items[input].select
-            ensure
-              collapse_combo
-            end
-          end
+      #Selects the item at the supplied position
+      def select_by_index(input)
+        raise "Index must be 0 or greater" if input < 0
+        begin
+          expand_combo
+          list_items[input].select
+        ensure
+          collapse_combo
+        end
+      end
 
-          def selected
-            #TODO: find a way to not need to expand and collapse before getting the selected item
-            expand_combo
-            collapse_combo
-            #get_selection.first
-            get_selection.first.name
-          end
+      #Returns the selected combobox item
+      def selected
+        #TODO: find a way to not need to expand and collapse before getting the selected item
+        expand_combo
+        collapse_combo
+        #get_selection.first
+        get_selection.first.name
+      end
 
-          def expand_combo
-            expand
-            Timeout.timeout(30) do
-              sleep 0.2 until expand_state == :expanded
-            end
-          end
+      #Expands the combobox
+      def expand_combo
+        expand
+        Timeout.timeout(30) do
+          sleep 0.2 until expand_state == :expanded
+        end
+      end
 
-          def collapse_combo
-            collapse
-            Timeout.timeout(30) do
-              sleep 0.2 until expand_state == :collapsed
-            end
-          end
+      #Collapses the combobox
+      def collapse_combo
+        collapse
+        Timeout.timeout(30) do
+          sleep 0.2 until expand_state == :collapsed
         end
       end
     end

data/lib/bewildr/control_type_additions/data_grid_additions.rb

@@ -3,12 +3,9 @@
 module Bewildr
   module ControlTypeAdditions
     module DataGridAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def cell(row, column)
-            get_item(row, column)
-          end
-        end
+      #Returns the cell at the supplied row and column
+      def cell(row, column)
+        get_item(row, column)
       end
     end
   end

data/lib/bewildr/control_type_additions/document_additions.rb

@@ -3,31 +3,30 @@
 module Bewildr
   module ControlTypeAdditions
     module DocumentAdditions
-      def self.extended(base)
-        base.instance_eval do
+      #Returns the document text
+      def text
+        get_text
+      end
 
-          def clean_string(input)
-            #add special chars as necessary. Ref: http://msdn.microsoft.com/en-us/library/system.windows.forms.sendkeys.send.aspx
-            replacements = {
-              /\n/ => "{ENTER}"
-            }
-            cleaned_string = input
-            replacements.keys.each {|key| cleaned_string.gsub!(key, replacements[key])}
-            cleaned_string
-          end
+      #Sets the document text to the supplied input
+      def text=(input)
+        cleaned_string = clean_string(input)
+        focus
+        select_all
+        System::Windows::Forms::SendKeys.send_wait("{DEL}")
+        System::Windows::Forms::SendKeys.send_wait(cleaned_string)
+      end
 
-          def text
-            get_text
-          end
+      private
 
-          def text=(input)
-            cleaned_string = clean_string(input)
-            focus
-            select_all
-            System::Windows::Forms::SendKeys.send_wait("{DEL}")
-            System::Windows::Forms::SendKeys.send_wait(cleaned_string)
-          end
-        end
+      def clean_string(input)
+        #add special chars as necessary. Ref: http://msdn.microsoft.com/en-us/library/system.windows.forms.sendkeys.send.aspx
+        replacements = {
+          /\n/ => "{ENTER}"
+        }
+        cleaned_string = input
+        replacements.keys.each {|key| cleaned_string.gsub!(key, replacements[key])}
+        cleaned_string
       end
     end
   end

data/lib/bewildr/control_type_additions/list_additions.rb

@@ -3,55 +3,59 @@
 module Bewildr
   module ControlTypeAdditions
     module ListAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def select(input)
-            selectable_elements = get(:type => :list_item, :scope => :children, :how_many => :all)
-            selectable_elements.find {|selectable_element| selectable_element.name == input}.select
-          end
-
-          def items
-            my_list_items = list_items
-            return nil if my_list_items.nil?
-            my_list_items.collect {|item| item.name}
-          end
-
-          def list_items
-            prepare_element
-            bewildr_list_items = get(:type => :list_item, :scope => :children, :how_many => :all)
-            bewildr_list_items.nil? ? nil : bewildr_list_items
-          end
-
-          def count
-            my_items = items
-            my_items.nil? ? 0 : my_items.size
-          end
-
-          def select(input)
-            case input
-            when String then select_by_name(input)
-            when Integer then select_by_index(input)
-            else raise ArgumentError, "Select by name or by index"
-            end
-          end
-
-          def select_by_name(input)
-            my_item = list_items.find {|item| item.name == input}
-            raise Bewildr::NoSuchItemInListBox if my_item.nil?
-            my_item.select
-          end
-
-          def select_by_index(input)
-            raise "Index must be 0 or greater" if input < 0
-            list_items[input].select
-          end
-
-          def selected
-            return nil if get_selection.empty?
-            get_selection.first.name
-          end
+      #Select the list item whose name matches the supplied input
+      def select(input)
+        selectable_elements = get(:type => :list_item, :scope => :children, :how_many => :all)
+        selectable_elements.find {|selectable_element| selectable_element.name == input}.select
+      end
+
+      #Returns a string array containing the list item names
+      def items
+        my_list_items = list_items
+        return nil if my_list_items.nil?
+        my_list_items.collect {|item| item.name}
+      end
+
+      #Returns an array containing the list items
+      def list_items
+        prepare_element
+        bewildr_list_items = get(:type => :list_item, :scope => :children, :how_many => :all)
+        bewildr_list_items.nil? ? nil : bewildr_list_items
+      end
+
+      #Returns the number of items in the list
+      def count
+        my_items = items
+        my_items.nil? ? 0 : my_items.size
+      end
+
+      #Selects a list item. Takes a string (and selects the first item whose name matches) or an integer and selects the respective element
+      def select(input)
+        case input
+        when String then select_by_name(input)
+        when Integer then select_by_index(input)
+        else raise ArgumentError, "Select by name or by index"
         end
       end
+
+      #Selects the first item whose name matches the input
+      def select_by_name(input)
+        my_item = list_items.find {|item| item.name == input}
+        raise Bewildr::NoSuchItemInListBox if my_item.nil?
+        my_item.select
+      end
+
+      #Selects the item at the supplied position
+      def select_by_index(input)
+        raise "Index must be 0 or greater" if input < 0
+        list_items[input].select
+      end
+
+      #Returns the selected list item
+      def selected
+        return nil if get_selection.empty?
+        get_selection.first.name
+      end
     end
   end
 end

data/lib/bewildr/control_type_additions/menu_additions.rb

@@ -3,56 +3,61 @@
 module Bewildr
   module ControlTypeAdditions
     module MenuAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def root_menu_items
-            get(:type => :menu_item, :scope => :children, :how_many => :all)
-          end
+      #Returns an array containing the menu's root items
+      def root_menu_items
+        get(:type => :menu_item, :scope => :children, :how_many => :all)
+      end
 
-          def root_menu_item_names
-            root_menu_items.collect {|menu_item| menu_item.name}
-          end
-          
-          def select_menu(path)
-             menu_item(path).click
-          end
+      #Returns a string array containing the root items' names
+      def root_menu_item_names
+        root_menu_items.collect {|menu_item| menu_item.name}
+      end
 
-          def select_node(path)
-            node(path).select
-          end
+      #Clicks the menu described by the input, eg:
+      #  select_menu(["File", "Close"])
+      def select_menu(path)
+        menu_item(path).click
+      end
 
-          def menu_item(path)
-            current_menu_items = root_menu_items
-            matching_menu_item = nil
-            path.each_with_index do |target_menu_item, index|
-              case current_menu_items
-              when Array
-                matching_menu_item = current_menu_items.find {|node| node.name == target_menu_item} #TODO: make this work with regexes as well as strings...
-                raise Bewildr::ElementDoesntExist if matching_menu_item.nil?
-              when Bewildr::Element
-                if current_menu_items.name == target_menu_item #TODO: make this work with regexes as well as strings...
-                  matching_menu_item = current_menu_items
-                else
-                  raise Bewildr::ElementDoesntExist
-                end
-              end
-              raise Bewildr::ElementDoesntExist if matching_menu_item.nil?
-              if path.size != index + 1
-                matching_menu_item.expand
-                current_menu_items = matching_menu_item.sub_menus
-              end
-            end
-            return matching_menu_item
-          end
+      #Selects the menu described by the input, eg:
+      #  select_node(["File", "Close"])
+      def select_node(path)
+        node(path).select
+      end
 
-          def contains_menu_item?(path)
-            begin
-              menu_item(path)
-              return true
-            rescue ElementDoesntExist => e
-              return false
+      #Returns the menu item described by the input, eg:
+      #  menu_item(["File", "Close"])
+      def menu_item(path)
+        current_menu_items = root_menu_items
+        matching_menu_item = nil
+        path.each_with_index do |target_menu_item, index|
+          case current_menu_items
+          when Array
+            matching_menu_item = current_menu_items.find {|node| node.name == target_menu_item} #TODO: make this work with regexes as well as strings...
+            raise Bewildr::ElementDoesntExist if matching_menu_item.nil?
+          when Bewildr::Element
+            if current_menu_items.name == target_menu_item #TODO: make this work with regexes as well as strings...
+              matching_menu_item = current_menu_items
+            else
+              raise Bewildr::ElementDoesntExist
             end
           end
+          raise Bewildr::ElementDoesntExist if matching_menu_item.nil?
+          if path.size != index + 1
+            matching_menu_item.expand
+            current_menu_items = matching_menu_item.sub_menus
+          end
+        end
+        return matching_menu_item
+      end
+
+      #Returns true if the menu contains the item described by the input, false if it doesn't
+      def contains_menu_item?(path)
+        begin
+          menu_item(path)
+          return true
+        rescue ElementDoesntExist => e
+          return false
         end
       end
     end

data/lib/bewildr/control_type_additions/menu_item_additions.rb

@@ -3,17 +3,13 @@
 module Bewildr
   module ControlTypeAdditions
     module MenuItemAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def sub_menus
-            get(:type => :menu_item, :scope => :children, :how_many => :all)
-          end
+      def sub_menus
+        get(:type => :menu_item, :scope => :children, :how_many => :all)
+      end
 
-          #menu items like 'invoke', not a proper mouse click
-          def click
-            @automation_element.get_current_pattern(System::Windows::Automation::InvokePattern.pattern).invoke
-          end
-        end
+      #menu items like 'invoke', not a proper mouse click
+      def click
+        @automation_element.get_current_pattern(System::Windows::Automation::InvokePattern.pattern).invoke
       end
     end
   end

data/lib/bewildr/control_type_additions/scroll_additions.rb

@@ -3,29 +3,25 @@
 module Bewildr
   module ControlTypeAdditions
     module ScrollAdditions
-      def self.extended(base)
-        base.instance_eval do
-          
-          #required because when a list is displayed, UI Automation only knows
-          #about the visible items. This method stores where the scroll value is,
-          #then moves the scroller to the top of the scroll bar and proceeds to
-          #page-down until the bottom of the scroll bar is reached. At this point,
-          #UI Automation knows about all the items in the list and we can put
-          #the scroll back where it was before we started this nonsense.
-          def load_all_items_hack
-            return unless scrollable?
+      #required because when a list is displayed, UI Automation only knows
+      #about the visible items. This method stores where the scroll value is,
+      #then moves the scroller to the top of the scroll bar and proceeds to
+      #page-down until the bottom of the scroll bar is reached. At this point,
+      #UI Automation knows about all the items in the list and we can put
+      #the scroll back where it was before we started this nonsense.
+      def load_all_items_hack
+        return unless scrollable?
 
-            initial_scroll_value = vertical_scroll_percent
+        initial_scroll_value = vertical_scroll_percent
 
-            scroll_to 0.0
-            page_down_to_bottom_of_scroll_bar
-            scroll_to initial_scroll_value
-          end
+        scroll_to 0.0
+        page_down_to_bottom_of_scroll_bar
+        scroll_to initial_scroll_value
+      end
 
-          def page_down_to_bottom_of_scroll_bar
-            scroll_down_one_page while vertical_scroll_percent < 99.99
-          end
-        end
+      #Scrolls down to the bottom, page by page
+      def page_down_to_bottom_of_scroll_bar
+        scroll_down_one_page while vertical_scroll_percent < 99.99
       end
     end
   end

data/lib/bewildr/control_type_additions/tab_additions.rb

@@ -3,26 +3,26 @@
 module Bewildr
   module ControlTypeAdditions
     module TabAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def select(input)
-            raise Bewildr::NoSuchTab unless tab_names.include?(input)
-            selectable_elements = tabs
-            selectable_elements.find {|selectable_element| selectable_element.name == input}.select
-          end
+      #Selects the tab whose name matches the input
+      def select(input)
+        raise Bewildr::NoSuchTab unless tab_names.include?(input)
+        selectable_elements = tabs
+        selectable_elements.find {|selectable_element| selectable_element.name == input}.select
+      end
 
-          def tabs
-            get(:type => :tab_item, :scope => :children, :how_many => :all)
-          end
+      #Returns an array containing the tab items belonging to the tab control
+      def tabs
+        get(:type => :tab_item, :scope => :children, :how_many => :all)
+      end
 
-          def tab_names
-            tabs.collect {|tab| tab.name}
-          end
+      #Returns a string array containing the names of all the tabs in the tab control
+      def tab_names
+        tabs.collect {|tab| tab.name}
+      end
 
-          def selected
-            tabs.find {|tab| tab.selected?}
-          end
-        end
+      #Returns the selected tab
+      def selected
+        tabs.find {|tab| tab.selected?}
       end
     end
   end

data/lib/bewildr/control_type_additions/text_additions.rb

@@ -3,13 +3,10 @@
 module Bewildr
   module ControlTypeAdditions
     module TextAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def text
-            existence_check
-            name
-          end
-        end
+      #Returns the element's text
+      def text
+        existence_check
+        name
       end
     end
   end

data/lib/bewildr/control_type_additions/tree_additions.rb

@@ -3,54 +3,58 @@
 module Bewildr
   module ControlTypeAdditions
     module TreeAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def root_nodes
-            prepare_element
-            get(:type => :tree_item, :scope => :children)
-          end
+      #Returns an array containing the tree's root nodes
+      def root_nodes
+        prepare_element
+        get(:type => :tree_item, :scope => :children)
+      end
 
-          def root_node
-            root_nodes.first
-          end
+      #Returns the root node
+      def root_node
+        root_nodes.first
+      end
 
-          def select_node(path)
-            node(path).select
-          end
+      #Selects the tree node described by the input, eg:
+      #  select_node(["parent node", "child node"])
+      def select_node(path)
+        node(path).select
+      end
 
-          def node(path)
-            current_nodes = root_nodes
-            matching_node = nil
-            path.each_with_index do |target_node, index|
-              case current_nodes
-              when Array
-                matching_node = current_nodes.find {|node| node.name == target_node} #TODO: make this work with regexes as well as strings...
-                raise Bewildr::ElementDoesntExist if matching_node.nil?
-              when Bewildr::Element
-                if current_nodes.name == target_node #TODO: make this work with regexes as well as strings...
-                  matching_node = current_nodes
-                else
-                  raise Bewildr::ElementDoesntExist
-                end
-              end
-              raise Bewildr::ElementDoesntExist if matching_node.nil?
-              if path.size != index + 1
-                matching_node.expand
-                current_nodes = matching_node.child_nodes
-              end
+      #Returns the tree node described by the input, eg:
+      #  node(["parent node", "child node"])
+      def node(path)
+        current_nodes = root_nodes
+        matching_node = nil
+        path.each_with_index do |target_node, index|
+          case current_nodes
+          when Array
+            matching_node = current_nodes.find {|node| node.name == target_node} #TODO: make this work with regexes as well as strings...
+            raise Bewildr::ElementDoesntExist if matching_node.nil?
+          when Bewildr::Element
+            if current_nodes.name == target_node #TODO: make this work with regexes as well as strings...
+              matching_node = current_nodes
+            else
+              raise Bewildr::ElementDoesntExist
             end
-            return matching_node
           end
-
-          def contains_node?(path)
-            begin
-              node(path)
-              return true
-            rescue ElementDoesntExist => e
-              return false
-            end
+          raise Bewildr::ElementDoesntExist if matching_node.nil?
+          if path.size != index + 1
+            matching_node.expand
+            load_all_items_hack
+            current_nodes = matching_node.child_nodes
           end
         end
+        return matching_node
+      end
+
+      #Returns true if the tree contains the item described by the input, false if it doesn't
+      def contains_node?(path)
+        begin
+          node(path)
+          return true
+        rescue ElementDoesntExist => e
+          return false
+        end
       end
     end
   end

data/lib/bewildr/control_type_additions/tree_item_additions.rb

@@ -3,24 +3,21 @@
 module Bewildr
   module ControlTypeAdditions
     module TreeItemAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def child_nodes
-            get(:type => :tree_item, :scope => :children)
-          end
+      #Returns the tree item's child nodes
+      def child_nodes
+        get(:type => :tree_item, :scope => :children)
+      end
 
-          #horrible, but necessary - clickable point for tree items doesn't work like you think it would...
-          #I've added 7 to y and 22 to x... that's working for now... this is hardly the ideal solution...
-          #To see what's going on with the following code, take a look at a tree node under uispy - you'll
-          #understand - a picture paints a thousand words and all that.
-          def clickable_point
-            existence_check
-            ae_top_left_point = @automation_element.current.bounding_rectangle.top_left
-            ae_top_left_point.x += 22
-            ae_top_left_point.y += 7
-            ae_top_left_point
-          end
-        end
+      #horrible, but necessary - clickable point for tree items doesn't work like you think it would...
+      #I've added 7 to y and 22 to x... that's working for now... this is hardly the ideal solution...
+      #To see what's going on with the following code, take a look at a tree node under uispy - you'll
+      #understand - a picture paints a thousand words and all that.
+      def clickable_point
+        existence_check
+        ae_top_left_point = @automation_element.current.bounding_rectangle.top_left
+        ae_top_left_point.x += 22
+        ae_top_left_point.y += 7
+        ae_top_left_point
       end
     end
   end

data/lib/bewildr/control_type_additions/window_additions.rb

@@ -3,17 +3,15 @@
 module Bewildr
   module ControlTypeAdditions
     module WindowAdditions
-      def self.extended(base)
-        base.instance_eval do
-          def open?
-            exists?
-          end
+      #Returns true if the window is open, false if it's not
+      def open?
+        exists?
+      end
 
-          def wait_for_close
-            Timeout::timeout(30) do
-              sleep 0.2 while open?
-            end
-          end
+      #Waits up to 30 seconds for the window to close
+      def wait_for_close
+        Timeout::timeout(30) do
+          sleep 0.2 while open?
         end
       end
     end

data/lib/bewildr/element.rb

@@ -177,6 +177,16 @@ module Bewildr
       end
     end
 
+    #Returns the height of the element in pixels
+    def height
+      @automation_element.current.bounding_rectangle.height.to_i
+    end
+
+    #Returns the width of the element in pixels
+    def width
+      @automation_element.current.bounding_rectangle.width.to_i
+    end
+
     private
 
     #Raises an exception if this element no longer exists

data/lib/bewildr/windows.rb

@@ -2,6 +2,7 @@
 
 module Bewildr
   class Windows
+    #Returns an array of windows belonging to a process id
     def self.windows_by_process_id(process_id)
       #find top level windows
       window_scope = System::Windows::Automation::TreeScope.Children

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: bewildr
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 15
   prerelease: false
   segments: 
   - 0
   - 1
-  - 9
-  version: 0.1.9
+  - 10
+  version: 0.1.10
 platform: ruby
 authors: 
 - Nat Ritmeyer
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-20 00:00:00 +00:00
+date: 2011-02-08 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency