atspi 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4d510b8f8cca6a7d67df7c04e3c485adb0af0866
+  data.tar.gz: a34a34c0cfd97aba0cb4c5b6bacfdee70cf0d9da
+SHA512:
+  metadata.gz: 337d97b940e17119a553111369a2719ec1e6770d2b3d2b1ca4c6d6c8f716a6a1b746d5b55879e162f48870dfcc2975d8a43d7a641a01c3a4e29415630032fd42
+  data.tar.gz: 7f1e9c0f2192d285d74685b00348ded4e5caff5ddb8e8dbaa428e50a09d7fa344efc61c1ea4ee464a71e8898ff9cdc020f17711d8f4593cb371b7c6b9aa87cf4

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.yardopts

@@ -0,0 +1,2 @@
+--embed-mixins
+--hide-api private

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Christopher Aue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,69 @@
+# Atspi
+
+This is a ruby gem that lets you comfortably call the
+[Assistive Technology Service Provider Interface](https://en.wikipedia.org/wiki/Assistive_Technology_Service_Provider_Interface)
+on Linux.
+
+It wraps Gnome's [libatspi](https://developer.gnome.org/libatspi/stable/) and
+exposes it as high level ruby objects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'atspi'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install atspi
+
+## Getting Started
+
+```ruby
+# Get the desktop
+desktop = ATSPI.desktops.first
+
+# Get an application on the desktop (here Gnome Terminal)
+application = desktop.applications.last
+
+# Get the first window of the application
+window = application.windows.first
+
+# Get the window's tabs
+tabs = window.descendants.where(role: :page_tab)
+tabs.count # => 3
+
+# Get the selected tab
+selected_tab = tabs.where(state: :selected).first
+selected_tab.index # => 0
+
+# Select the first tab
+tabs.last.select
+
+# Get the selected tab
+selected_tab = tabs.where(state: :selected).first
+selected_tab.index # => 2
+```
+
+## Documentation
+
+Detailed documentation can be found at [http://www.rubydoc.info/gems/atspi](http://www.rubydoc.info/gems/atspi).
+
+Especially:
+
+* Everything starts with the [ATSPI module](http://www.rubydoc.info/gems/atspi/ATSPI.html).
+* Accessibles are represented by the [ATSPI::Accessible class](http://www.rubydoc.info/gems/atspi/ATSPI/Accessible.html).
++ An accessible's descendants can be searched using the interface of the [ATSPI::Accessible::Descendants class](http://www.rubydoc.info/gems/atspi/ATSPI/Accessible/Descendants.html)
+
+## Todo
+
+Not supported yet are:
+
+* Event listeners
+* (Editable) text attributes

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/atspi.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'atspi/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "atspi"
+  spec.version       = ATSPI::VERSION
+  spec.authors       = ["Christopher Aue"]
+  spec.email         = ["mail@christopheraue.net"]
+
+  spec.summary       = %q{The atspi gem lets you comfortably call the Assistive Technology Service Provider Interface on Linux.}
+  spec.description   = %q{It is a high level wrapper around libatspi.}
+  spec.homepage      = "https://github.com/christopheraue/ruby-atspi"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "gir_ffi", "~> 0.10.0"
+  spec.add_development_dependency "bundler", "~> 1.8"
+end

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "irb"
+require "atspi"
+
+IRB.start

data/lib/atspi/accessible/action.rb

@@ -0,0 +1,45 @@
+class ATSPI::Accessible
+  # Wraps libatspi's AtspiAction[https://developer.gnome.org/libatspi/stable/libatspi-atspi-action.html]
+  class Action
+    # @api private
+    def initialize(native, idx)
+      @native = native
+      @idx = idx
+    end
+
+    # @return [String] its name
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-action.html#atspi-action-get-name atspi_action_get_name
+    def name
+      @native.action_name(@idx)
+    end
+
+    # @return [String] its description
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-action.html#atspi-action-get-description atspi_action_get_description
+    def description
+      @native.action_description(@idx)
+    end
+
+    # @return [String] its key binding
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-action.html#atspi-action-get-key-binding atspi_action_get_key_binding
+    def key_binding
+      @native.key_binding(@idx)
+    end
+
+    # Tries to execute the action
+    #
+    # @return [true,false] indicating success
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-action.html#atspi-action-do-action atspi_action_do_action
+    def do_it!
+      @native.do_action(@idx)
+    end
+
+    # @return [String] itself as an inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @name=#{name.inspect} @description=#{description.inspect}>"
+    end
+  end
+end

data/lib/atspi/accessible/children/selected.rb

@@ -0,0 +1,32 @@
+module ATSPI
+  # Wraps libatspi's AtspiSelection[https://developer.gnome.org/libatspi/stable/libatspi-atspi-selection.html]
+  # together with parts of {Selectable} and {Children}
+  class Accessible::Children::Selected
+    include SelectableCollection::Selected
+
+  # @api private
+    def initialize(native)
+      @native = native
+    end
+
+  # @!group Enumerable interface
+    # @param idx [Integer]
+    #
+    # @return [Accessible] its child at index +idx+
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-selection.html#atspi-selection-get-selected-child atspi_selection_get_selected_child
+    def at(idx)
+      super do |mapped_idx|
+        Accessible.new(@native.selected_child(mapped_idx))
+      end
+    end
+
+    # @return [Integer] its number of children
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-selection.html#atspi-selection-get-n-selected-children atspi_selection_get_n_selected_children
+    def count
+      @native.n_selected_children
+    end
+  # @!endgroup
+  end
+end

data/lib/atspi/accessible/children.rb

@@ -0,0 +1,72 @@
+module ATSPI
+  # Wraps the children part of libatspi's AtspiAccessible[https://developer.gnome.org/libatspi/stable/AtspiAccessible.html]
+  # and parts of AtspiSelection[https://developer.gnome.org/libatspi/stable/libatspi-atspi-selection.html].
+  class Accessible::Children
+    include SelectableCollection
+
+    # @api private
+    def initialize(native)
+      @native = native
+    end
+
+  # @!group Enumerable interface
+    # @param idx [Integer]
+    #
+    # @return [Accessible] its child at index +idx+
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiAccessible.html#atspi-accessible-get-child-at-index atspi_accessible_get_child_at_index
+    def at(idx)
+      super do |mapped_idx|
+        Accessible.new(@native.child_at_index(mapped_idx))
+      end
+    end
+
+    # @return [Integer] its number of children
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiAccessible.html#atspi-accessible-get-child-count atspi_accessible_get_child_count
+    def count
+      @native.child_count
+    end
+  # @!endgroup
+
+  # @!group Selection
+    # Checks if the accessible the children belong to implements the selection
+    # interface.
+    #
+    # @return [true,false]
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiAccessible.html#atspi-accessible-get-selection atspi_accessible_get_selection
+    def selectable?
+      not @native.selection_iface.nil?
+    end
+
+    # @return [Selected,[]] its selected subset. It will be an empty array if
+    #   children are not selectable.
+    def selected
+      if selectable?
+        Selected.new(@native)
+      else
+        []
+      end
+    end
+
+    # Tries to select all children
+    #
+    # @return [true,false] indicates success
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-selection.html#atspi-selection-select-all atspi_selection_select_all
+    def select_all
+      selectable? and @native.select_all
+    end
+
+    # Tries to deselect all children
+    #
+    # @return [true,false] indicates success
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-selection.html#atspi-selection-clear-selection atspi_selection_clear_selection
+    def deselect_all
+      selectable? and @native.clear_selection
+    end
+  # @!endgroup
+  end
+end

data/lib/atspi/accessible/descendants/attribute_filter.rb

@@ -0,0 +1,32 @@
+module ATSPI
+  class Accessible::Descendants
+    # @api private
+    class AttributeFilter
+      def initialize(mode: :any, attributes: {})
+        @mode = mode
+        @attributes = attributes
+      end
+
+      def extend(*attributes)
+        attributes = attributes.to_h
+        mode = attributes.delete(:mode) || @mode
+        attributes = attributes.inject(@attributes) do |memo, (key, values)|
+          memo.merge(key => [*memo[key], *values].uniq)
+        end
+        self.class.new(mode: mode, attributes: attributes)
+      end
+
+      def to_a
+        attributes = @attributes.map do |key, values|
+          escaped_values = values.map{ |value| value.gsub(':', '\:') }
+          [key, escaped_values.join('::')]
+        end.to_h
+        [attributes, @mode]
+      end
+
+      def inspect
+        "#{@mode}:#{@attributes.inspect}"
+      end
+    end
+  end
+end

data/lib/atspi/accessible/descendants/interface_filter.rb

@@ -0,0 +1,24 @@
+module ATSPI
+  class Accessible::Descendants
+    # @api private
+    class InterfaceFilter
+      def initialize(mode: :all, interfaces: [])
+        @mode = mode
+        @interfaces = interfaces
+      end
+
+      def extend(*interfaces, mode: @mode)
+        interfaces = @interfaces + interfaces.map(&:to_s)
+        self.class.new(mode: mode, interfaces: interfaces.uniq)
+      end
+
+      def to_a
+        [@interfaces.dup, @mode]
+      end
+
+      def inspect
+        "#{@mode}:#{@interfaces.inspect}"
+      end
+    end
+  end
+end

data/lib/atspi/accessible/descendants/name_filter.rb

@@ -0,0 +1,18 @@
+class ATSPI::Accessible::Descendants
+  # @api private
+  class NameFilter
+    def initialize(match = nil)
+      @match = match
+    end
+
+    attr_reader :match
+
+    def extend(match)
+      self.class.new(match.is_a?(Regexp) ? match : /^#{Regexp.quote(match)}$/)
+    end
+
+    def inspect
+      @match.inspect
+    end
+  end
+end

data/lib/atspi/accessible/descendants/options.rb

@@ -0,0 +1,49 @@
+class ATSPI::Accessible::Descendants
+  # @api private
+  class Options
+    def initialize(prototype = nil, extensions = {})
+      @prototype = prototype
+      @extensions = extensions
+    end
+
+    def invert(invert = true)
+      self.class.new(self, inverted?: invert)
+    end
+
+    def order_by(order)
+      self.class.new(self, order: order)
+    end
+
+    def limit_to(limit)
+      self.class.new(self, limit: limit)
+    end
+
+    def recursive(recursive = true)
+      self.class.new(self, recursive?: recursive)
+    end
+
+    def inverted?
+      @extensions.key?(:inverted?) ? @extensions[:inverted?] : @prototype.inverted?
+    end
+
+    def order
+      @extensions.key?(:order) ? @extensions[:order] : @prototype.order
+    end
+
+    def limit
+      @extensions.key?(:limit) ? @extensions[:limit] : @prototype.limit
+    end
+
+    def recursive?
+      @extensions.key?(:recursive?) ? @extensions[:recursive?] : @prototype.recursive?
+    end
+
+    def to_a
+      [order, limit, recursive?]
+    end
+
+    def inspect
+      "@inverted?=#{inverted?} @order=#{order} @limit=#{limit} @recursive?=#{recursive?}"
+    end
+  end
+end

data/lib/atspi/accessible/descendants/role_filter.rb

@@ -0,0 +1,23 @@
+module ATSPI
+  class Accessible::Descendants
+    # @api private
+    class RoleFilter
+      def initialize(mode: :any, roles: [])
+        @mode = mode
+        @roles = roles
+      end
+
+      def extend(*roles, mode: @mode)
+        self.class.new(mode: mode, roles: (@roles + roles).uniq)
+      end
+
+      def to_a
+        [@roles.dup, @mode]
+      end
+
+      def inspect
+        "#{@mode}:#{@roles.inspect}"
+      end
+    end
+  end
+end

data/lib/atspi/accessible/descendants/state_filter.rb

@@ -0,0 +1,23 @@
+module ATSPI
+  class Accessible::Descendants
+    # @api private
+    class StateFilter
+      def initialize(mode: :all, states: [])
+        @mode = mode
+        @states = states
+      end
+
+      def extend(*states, mode: @mode)
+        self.class.new(mode: mode, states: (@states + states).uniq)
+      end
+
+      def to_a
+        [StateSet.new(*@states).__send__(:native), @mode]
+      end
+
+      def inspect
+        "#{@mode}:#{@states.inspect}"
+      end
+    end
+  end
+end