atspi 0.8.0

data/lib/atspi/desktop.rb

@@ -0,0 +1,52 @@
+module ATSPI
+  # Desktops are Accessibles having a few exceptions.
+  class Desktop < Accessible
+  # @!group Identification
+    # It has no parent.
+    # @return [nil]
+    def parent
+      nil
+    end
+
+    # It has no path.
+    # @return [[]]
+    def path
+      []
+    end
+
+    # Its desktop is itself.
+    # @return [self]
+    def desktop
+      self
+    end
+
+    # It belongs to no application.
+    # @return nil
+    def application
+      nil
+    end
+
+    # It has no window.
+    # @return nil
+    def window
+      nil
+    end
+  # @!endgroup
+
+  # @!group Tree & Traversal
+    # Its applications are its children.
+    # @param (see Accessible#children)
+    # @return (see Accessible#children)
+    def applications
+      children
+    end
+  # @!endgroup
+
+  # @!group Representations
+    # @return [String] itself as an inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @index=#{index} @name=#{name.inspect}>"
+    end
+  # @!endgroup
+  end
+end

data/lib/atspi/extents.rb

@@ -0,0 +1,28 @@
+module ATSPI
+  # Wraps libatspi's AtspiRect[https://developer.gnome.org/libatspi/stable/libatspi-atspi-component.html#AtspiRect-struct]
+  class Extents
+    extend Forwardable
+
+    # @api private
+    def initialize(native)
+      @native = native
+    end
+
+    # @return [Integer] its x position
+    delegate :x => :@native
+
+    # @return [Integer] its y position
+    delegate :y => :@native
+
+    # @return [Integer] its width
+    delegate :width => :@native
+
+    # @return [Integer] its height
+    delegate :height => :@native
+
+    # @return [String] itself as an inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @x=#{x} @y=#{y} @width=#{width} @height=#{height}>"
+    end
+  end
+end

data/lib/atspi/libatspi.rb

@@ -0,0 +1,7 @@
+require 'gir_ffi'
+
+GirFFI.setup :Atspi
+
+# Atspi is aliased as Libatspi to better differentiate it from our ATSPI
+# namespace.
+Libatspi = Atspi

data/lib/atspi/requires.rb

@@ -0,0 +1,76 @@
+# FFI
+require 'atspi/libatspi'
+
+require 'forwardable'
+
+# General
+require 'atspi/state_set'
+require 'atspi/extents'
+
+# Collection modules
+require 'atspi/collection'
+require 'atspi/selectable_collection'
+require 'atspi/selectable_collection/selected'
+
+# Accessible
+require 'atspi/accessible/selectable'
+require 'atspi/accessible/extents'
+require 'atspi/accessible'
+
+# Action
+require 'atspi/accessible/action'
+
+# Children
+require 'atspi/accessible/children'
+require 'atspi/accessible/children/selected'
+
+# Descendants
+require 'atspi/accessible/descendants'
+require 'atspi/accessible/descendants/state_filter'
+require 'atspi/accessible/descendants/attribute_filter'
+require 'atspi/accessible/descendants/role_filter'
+require 'atspi/accessible/descendants/interface_filter'
+require 'atspi/accessible/descendants/name_filter'
+require 'atspi/accessible/descendants/options'
+
+# Document
+require 'atspi/accessible/document'
+
+# Hyperlink
+require 'atspi/accessible/hyperlink'
+require 'atspi/accessible/hyperlink/anchor'
+
+# Text
+require 'atspi/accessible/text/editable'
+require 'atspi/accessible/text/hypertext'
+require 'atspi/accessible/text'
+require 'atspi/accessible/text/character'
+require 'atspi/accessible/text/offset'
+require 'atspi/accessible/text/caret'
+require 'atspi/accessible/text/range'
+require 'atspi/accessible/text/selection'
+require 'atspi/accessible/text/hyperlink'
+
+# Table
+require 'atspi/accessible/table'
+require 'atspi/accessible/table/columns'
+require 'atspi/accessible/table/columns/selected'
+require 'atspi/accessible/table/column'
+require 'atspi/accessible/table/rows'
+require 'atspi/accessible/table/rows/selected'
+require 'atspi/accessible/table/row'
+require 'atspi/accessible/table/cells'
+require 'atspi/accessible/table/cell'
+require 'atspi/accessible/table/cell/rows'
+require 'atspi/accessible/table/cell/columns'
+
+# Image
+require 'atspi/accessible/image'
+
+# Value
+require 'atspi/accessible/value'
+
+# Specific accessibles
+require 'atspi/desktop'
+require 'atspi/application'
+require 'atspi/window'

data/lib/atspi/selectable_collection/selected.rb

@@ -0,0 +1,23 @@
+module ATSPI
+  # Included in classes representing the selected subset of a selectable collection
+  module SelectableCollection::Selected
+    include Collection
+
+    # @api private
+    INDEX_METHOD = :index_in_parent
+
+    def indices(limit: count)
+      [*first(limit)].map(&self.class::INDEX_METHOD)
+    end
+    private :indices
+
+  # @!group Representation
+    # @return [String] instance as inspectable string
+    def inspect
+      indices = self.indices(limit: 5).inspect
+      indices[-1] = ", …]" if count > 5
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @count=#{count} @indices=#{indices}>"
+    end
+  # @!endgroup
+  end
+end

data/lib/atspi/selectable_collection.rb

@@ -0,0 +1,32 @@
+module ATSPI
+  # Included in classes representing a collection having selectable items
+  module SelectableCollection
+    include Collection
+
+  # @!group Selection
+    # @return [Selected] its selected subset
+    def selected
+      self.class::Selected.new(@native)
+    end
+
+    # Selects all items
+    # @return [true,false] indicating success
+    def select_all
+      map(&:select).all?
+    end
+
+    # Deselects all items
+    # @return [true,false] indicating success
+    def deselect_all
+      selected.map(&:deselect).all?
+    end
+  # @!endgroup
+
+  # @!group Representation
+    # @return [String] instance as inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @count=#{count} @selected=#{selected.inspect}>"
+    end
+  # @!endgroup
+  end
+end

data/lib/atspi/state_set.rb

@@ -0,0 +1,141 @@
+Libatspi.load_class :StateSet
+
+module ATSPI
+  # ATSPI::StateSet wraps libatspi's AtspiStateSet[https://developer.gnome.org/libatspi/stable/AtspiStateSet.html]
+  class StateSet
+    extend Forwardable
+
+    # @api private
+    def self.new_from_native(native)
+      new(*native.states)
+    end
+
+  # @!group Lifecycle
+    # @param states [Symbols] zero, one or more symbols derived from
+    #   libatspi's {AtspiStateType enum}[https://developer.gnome.org/libatspi/stable/libatspi-atspi-constants.html#AtspiStateType]
+    #   by removing the prefix +ATSPI_STATE_+ and making it lowercase.
+    #
+    # @return [StateSet]
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiStateSet.html#atspi-state-set-new atspi_state_set_new
+    def initialize(*states)
+      @native = Libatspi::StateSet.new(states)
+    end
+  # @!endgroup
+
+    attr_reader :native
+    private :native
+
+  # @!group Modification
+    # Adds states to the set
+    #
+    # @param states [Symbols] zero, one or more symbols derived from
+    #   libatspi's {AtspiStateType enum}[https://developer.gnome.org/libatspi/stable/libatspi-atspi-constants.html#AtspiStateType]
+    #   by removing the prefix +ATSPI_STATE_+ and making it lowercase.
+    #
+    # @return [self]
+    #
+    # @example
+    #   s = ATSPI::StateSet.new   # => #<ATSPI::StateSet:0x15ae28014 @states=[]>
+    #   s.add(:active, :enabled)  # => #<ATSPI::StateSet:0x15ae28014 @states=[:active, :enabled]>
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiStateSet.html#atspi-state-set-add atspi_state_set_add
+    def add(*states)
+      states.each{ |state| @native.add(state) }
+      self
+    end
+
+    # Removes states from the set
+    #
+    # @param states [Symbols] zero, one or more symbols derived from
+    #   libatspi's {AtspiStateType enum}[https://developer.gnome.org/libatspi/stable/libatspi-atspi-constants.html#AtspiStateType]
+    #   by removing the prefix +ATSPI_STATE_+ and making it lowercase.
+    #
+    # @return [self]
+    #
+    # @example
+    #   s = ATSPI::StateSet.new(:active, :enabled)  # => #<ATSPI::StateSet:0x15ae28014 @states=[:active, :enabled]>
+    #   s.remove(:active)                           # => #<ATSPI::StateSet:0x15ae28014 @states=[:enabled]>
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiStateSet.html#atspi-state-set-remove atspi_state_set_remove
+    def remove(*states)
+      states.each{ |state| @native.remove(state) }
+      self
+    end
+  # @!endgroup
+
+  # @!group Queries
+    # Checks if it contains the given state
+    #
+    # @param state [Symbol] the state as symbol derived from libatspi's
+    #   {AtspiStateType enum}[https://developer.gnome.org/libatspi/stable/libatspi-atspi-constants.html#AtspiStateType]
+    #   by removing the prefix +ATSPI_STATE_+ and making it lowercase.
+    #
+    # @return [true,false]
+    #
+    # @example
+    #   ATSPI::StateSet.new(:active, :editable).contains?(:active) # => true
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiStateSet.html#atspi-state-set-contains atspi_state_set_contains
+    def contains?(state)
+      @native.contains(state)
+    end
+
+    # Checks if it is empty
+    #
+    # @return [true,false]
+    #
+    # @example
+    #   ATSPI::StateSet.new(:active, :editable).empty? # => false
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiStateSet.html#atspi-state-set-is-empty atspi_state_set_is_empty
+    def empty?
+      @native.is_empty
+    end
+
+    # Returns the difference between it and another set
+    #
+    # @return [StateSet] the difference to the given set
+    #
+    # @example
+    #   s1 = ATSPI::StateSet.new(:active, :editable)  # => #<ATSPI::StateSet:0x15ae28014 @states=[:active, :editable]>
+    #   s2 = ATSPI::StateSet.new(:active, :enabled)   # => #<ATSPI::StateSet:0x119ea8c14 @states=[:active, :enabled]>
+    #   s1.difference_to(s2)                          # => #<ATSPI::StateSet:0x110b2b414 @states=[:editable, :enabled]>
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiStateSet.html#atspi-state-set-compare atspi_state_set_compare
+    def difference_to(state_set)
+      StateSet.new_from_native @native.compare(state_set.__send__(:native))
+    end
+    alias_method :^, :difference_to
+
+    # Checks if it equals another set
+    #
+    # @return [true, false]
+    #
+    # @example
+    #   s1 = ATSPI::StateSet.new(:active, :editable)  # => #<ATSPI::StateSet:0x15ae28014 @states=[:active, :editable]>
+    #   s2 = ATSPI::StateSet.new(:active, :enabled)   # => #<ATSPI::StateSet:0x119ea8c14 @states=[:active, :enabled]>
+    #   s1.equals?(s2)                                # => false
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiStateSet.html#atspi-state-set-equals atspi_state_set_equals
+    def equals?(state_set)
+      @native.equals state_set.__send__(:native)
+    end
+    alias_method :==, :equals?
+  # @!endgroup
+
+  # @!group Representations
+    # @return [Array<Symbol>] the states it contains
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiStateSet.html#atspi-state-set-get-states atspi_state_set_get_states
+    def to_a
+      @native.states.to_a
+    end
+
+    # @return [String] itself as an inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @states=#{to_a.inspect}>"
+    end
+  # @!endgroup
+  end
+end

data/lib/atspi/version.rb

@@ -0,0 +1,4 @@
+module ATSPI
+  # this library's version
+  VERSION = "0.8.0"
+end

data/lib/atspi/window.rb

@@ -0,0 +1,33 @@
+module ATSPI
+  # Windows are Accessibles having a few exceptions.
+  class Window < Accessible
+  # @!group Identification
+    # It has no path.
+    # @return [[]]
+    def path
+      []
+    end
+
+    # Its parent is its application
+    # @return [Application]
+    def parent
+      application
+    end
+
+    # Its window is itself
+    # @return [self]
+    def window
+      self
+    end
+  # @!endgroup
+
+  # @!group Representations
+  # @return [String] itself as an inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @desktop=#{desktop.index} " <<
+        "@application=#{application.name} @name=#{name.inspect} " <<
+        "@extents=#{extents(relative_to: :screen).inspect}>"
+    end
+  # @!endgroup
+  end
+end

data/lib/atspi.rb

@@ -0,0 +1,58 @@
+require 'atspi/requires'
+
+# ATSPI is the entry point to access accessible objects.
+module ATSPI
+  class << self
+    extend Forwardable
+
+    # Returns all desktops known to AT-SPI.
+    #
+    # @return [Array<Desktop>]
+    #
+    # @example
+    #   ATSPI.desktops # => [#<ATSPI::Desktop:0xd4e81014 @index=0 @name="main">]
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-registry.html#atspi-get-desktop atspi_get_desktop
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-registry.html#atspi-get-desktop-count atspi_get_desktop_count
+    def desktops
+      @desktops ||= Libatspi.get_desktop_count.times.map do |idx|
+        Desktop.new(Libatspi.get_desktop(idx))
+      end
+    end
+
+    # Returns all applications for the given desktop.
+    #
+    # @param desktop [Desktop]
+    #
+    # @return [Array<Application>]
+    #
+    # @example
+    #   ATSPI.applications # => [#<ATSPI::Application:0x71d18014 @desktop=0 @name="gnome-terminal-server">, …]
+    def applications(desktop = desktops.first)
+      desktop.applications
+    end
+
+    #@!method generate_keyboard_event(keyval, keystring, synth_type)
+    #   Generates a custom keyboard event.
+    #
+    #   Delegates directly to libatspi's generate_keyboard_event[https://developer.gnome.org/libatspi/stable/libatspi-atspi-registry.html#atspi-generate-keyboard-event]
+    #
+    #   @param keyval [Integer]
+    #   @param keystring [String]
+    #   @param synth_type [Symbol] one of :sym, :string, :press, :release or :pressrelease
+    #
+    #   @return [true, false]
+    #
+    #@!method generate_mouse_event(x, y, name)
+    #   Generates a custom mouse event.
+    #
+    #   Delegates directly to libatspi's generate_mouse_event[https://developer.gnome.org/libatspi/stable/libatspi-atspi-registry.html#atspi-generate-mouse-event]
+    #
+    #   @param x [Integer]
+    #   @param y [Integer]
+    #   @param name [String]
+    #
+    #   @return [true, false]
+    delegate %i(generate_keyboard_event generate_mouse_event) => :Libatspi
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: atspi
+version: !ruby/object:Gem::Version
+  version: 0.8.0
+platform: ruby
+authors:
+- Christopher Aue
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gir_ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: It is a high level wrapper around libatspi.
+email:
+- mail@christopheraue.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".yardopts"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- atspi.gemspec
+- bin/console
+- lib/atspi.rb
+- lib/atspi/accessible.rb
+- lib/atspi/accessible/action.rb
+- lib/atspi/accessible/children.rb
+- lib/atspi/accessible/children/selected.rb
+- lib/atspi/accessible/descendants.rb
+- lib/atspi/accessible/descendants/attribute_filter.rb
+- lib/atspi/accessible/descendants/interface_filter.rb
+- lib/atspi/accessible/descendants/name_filter.rb
+- lib/atspi/accessible/descendants/options.rb
+- lib/atspi/accessible/descendants/role_filter.rb
+- lib/atspi/accessible/descendants/state_filter.rb
+- lib/atspi/accessible/document.rb
+- lib/atspi/accessible/extents.rb
+- lib/atspi/accessible/hyperlink.rb
+- lib/atspi/accessible/hyperlink/anchor.rb
+- lib/atspi/accessible/image.rb
+- lib/atspi/accessible/selectable.rb
+- lib/atspi/accessible/table.rb
+- lib/atspi/accessible/table/cell.rb
+- lib/atspi/accessible/table/cell/columns.rb
+- lib/atspi/accessible/table/cell/rows.rb
+- lib/atspi/accessible/table/cells.rb
+- lib/atspi/accessible/table/column.rb
+- lib/atspi/accessible/table/columns.rb
+- lib/atspi/accessible/table/columns/selected.rb
+- lib/atspi/accessible/table/row.rb
+- lib/atspi/accessible/table/rows.rb
+- lib/atspi/accessible/table/rows/selected.rb
+- lib/atspi/accessible/text.rb
+- lib/atspi/accessible/text/caret.rb
+- lib/atspi/accessible/text/character.rb
+- lib/atspi/accessible/text/editable.rb
+- lib/atspi/accessible/text/hyperlink.rb
+- lib/atspi/accessible/text/hypertext.rb
+- lib/atspi/accessible/text/offset.rb
+- lib/atspi/accessible/text/range.rb
+- lib/atspi/accessible/text/selection.rb
+- lib/atspi/accessible/value.rb
+- lib/atspi/application.rb
+- lib/atspi/collection.rb
+- lib/atspi/desktop.rb
+- lib/atspi/extents.rb
+- lib/atspi/libatspi.rb
+- lib/atspi/requires.rb
+- lib/atspi/selectable_collection.rb
+- lib/atspi/selectable_collection/selected.rb
+- lib/atspi/state_set.rb
+- lib/atspi/version.rb
+- lib/atspi/window.rb
+homepage: https://github.com/christopheraue/ruby-atspi
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: The atspi gem lets you comfortably call the Assistive Technology Service
+  Provider Interface on Linux.
+test_files: []
+has_rdoc: