atspi 0.8.0

data/lib/atspi/accessible/table/cell.rb

@@ -0,0 +1,18 @@
+module ATSPI
+  class Accessible::Table
+    # Represents a cell in a {Table}. It is child accessible of its {Table}.
+    class Cell < Accessible
+      # @return [Rows] the rows it spans
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-row-column-extents-at-index atspi_table_get_row_column_extents_at_index
+      def rows
+        Rows.new(@native)
+      end
+
+      # @return [Columns] the columns it spans
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-row-column-extents-at-index atspi_table_get_row_column_extents_at_index
+      def columns
+        Columns.new(@native)
+      end
+    end
+  end
+end

data/lib/atspi/accessible/table/cells.rb

@@ -0,0 +1,37 @@
+class ATSPI::Accessible
+  class Table
+    # Represents all cells in a {Table}. Cells are also the children of their
+    # {Table}.
+    class Cells < Children
+    # @!group Enumerable interface
+      # @overload at(idx)
+      #   @param (see Children#at)
+      #
+      # @overload at(row:, column:)
+      #   @param (see #at_coords)
+      #
+      # @return [Cell] the cell at +idx+ or at (+row+,+column+)
+      #
+      # @see https://developer.gnome.org/libatspi/stable/AtspiAccessible.html#atspi-accessible-get-child-at-index atspi_accessible_get_child_at_index
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-accessible-at atspi_table_get_accessible_at
+      def at(idx = nil)
+        if idx.is_a? Numeric
+          Cell.new(@native.child_at_index(idx))
+        else
+          at_coords(idx)
+        end
+      end
+
+      # @param row [Integer]
+      # @param colum [Integer]
+      #
+      # @return [Cell] the cell at (+row+,+column+)
+      #
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-accessible-at atspi_table_get_accessible_at
+      def at_coords(row:, column:)
+        Cell.new(@native.accessible_at(row, column))
+      end
+    # @!endgroup
+    end
+  end
+end

data/lib/atspi/accessible/table/column.rb

@@ -0,0 +1,59 @@
+class ATSPI::Accessible::Table
+  # Represents a column in a {Table}
+  class Column
+    # @api private
+    def initialize(native, index)
+      @native = native
+      @index = index
+    end
+
+  # @group State & Attributes
+    # @return [Integer] its index
+    attr_reader :index
+
+    # @return [Cell] its header
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-column-header atspi_table_get_column_header
+    def header
+      header = @native.column_header(@index)
+      Cell.new(header) if header
+    end
+
+    # @return [String] its description
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-column-description atspi_table_get_column_description
+    def description
+      @native.column_description(@index)
+    end
+
+    # Checks if it is selected
+    # @return [true,false]
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-is-column-selected atspi_table_is_column_selected
+    def selected?
+      @native.is_column_selected(@index)
+    end
+  # @endgroup
+
+  # @group Actions
+    # Selects its
+    # @return [true,false]
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-add-column-selection atspi_table_add_column_selection
+    def select
+      @native.add_column_selection(@index)
+    end
+
+    # Deselects its
+    # @return [true,false]
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-remove-column-selection atspi_table_remove_column_selection
+    def deselect
+      @native.remove_column_selection(@index)
+    end
+  # @endgroup
+
+  # @group Representations
+    # @return [String] itself as an inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @index=#{index} @selected?=#{selected?} " <<
+        "@description=#{description.inspect}>"
+    end
+  # @endgroup
+  end
+end

data/lib/atspi/accessible/table/columns/selected.rb

@@ -0,0 +1,42 @@
+module ATSPI
+  class Accessible::Table
+    # Represents all selected columns of a {Table}
+    class Columns::Selected
+      include SelectableCollection::Selected
+
+      # @api private
+      INDEX_METHOD = :index
+
+      # @api private
+      def initialize(native)
+        @native = native
+      end
+
+    # @!group Enumerable interface
+      # Iterates over all selected columns
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-selected-columns atspi_table_get_selected_columns
+      def each
+        @native.selected_columns.each do |idx|
+          yield at(idx)
+        end
+      end
+
+      # @param n [Integer] the index in the collection of selected columns and
+      #   not the index in the collection of all the table's columns.
+      #
+      # @return [Column] the table's n'th selected column
+      def at(n)
+        super do |mapped_idx|
+          Column.new(@native, mapped_idx)
+        end
+      end
+
+      # @return [Integer] the number of selected columns
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-n-selected-columns atspi_table_get_n_selected_columns
+      def count
+        @native.n_selected_columns
+      end
+    # @!endgroup
+    end
+  end
+end

data/lib/atspi/accessible/table/columns.rb

@@ -0,0 +1,34 @@
+module ATSPI
+  class Accessible::Table
+    # Represents all columns in a {Table}
+    class Columns
+      include SelectableCollection
+
+      # @api private
+      INDEX_METHOD = :index
+
+      # @api private
+      def initialize(native)
+        @native = native
+      end
+
+    # @!group Enumerable interface
+      # @param idx [Integer]
+      #
+      # @return [Column] the column at index +idx+
+      def at(idx)
+        super do |mapped_idx|
+          Column.new(@native, mapped_idx)
+        end
+      end
+
+      # @return [Integer] its number of columns
+      #
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-n-columns atspi_table_get_n_columns
+      def count
+        @native.n_columns
+      end
+    # @!endgroup
+    end
+  end
+end

data/lib/atspi/accessible/table/row.rb

@@ -0,0 +1,59 @@
+class ATSPI::Accessible::Table
+  # Represents a row in a {Table}
+  class Row
+    # @api private
+    def initialize(native, index)
+      @native = native
+      @index = index
+    end
+
+  # @group State & Attributes
+    # @return [Integer] its index
+    attr_reader :index
+
+    # @return [Cell] its header
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-row-header atspi_table_get_row_header
+    def header
+      header = @native.row_header(@index)
+      Cell.new(header) if header
+    end
+
+    # @return [String] its description
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-row-description atspi_table_get_row_description
+    def description
+      @native.row_description(@index)
+    end
+
+    # Checks if it is selected
+    # @return [true,false]
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-is-row-selected atspi_table_is_row_selected
+    def selected?
+      @native.is_row_selected(@index)
+    end
+  # @endgroup
+
+  # @group Actions
+    # Selects its
+    # @return [true,false]
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-add-row-selection atspi_table_add_row_selection
+    def select
+      @native.add_row_selection(@index)
+    end
+
+    # Deselects its
+    # @return [true,false]
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-remove-row-selection atspi_table_remove_row_selection
+    def deselect
+      @native.remove_row_selection(@index)
+    end
+  # @endgroup
+
+  # @group Representations
+    # @return [String] itself as an inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @index=#{index} @selected?=#{selected?} " <<
+        "@description=#{description.inspect}>"
+    end
+  # @endgroup
+  end
+end

data/lib/atspi/accessible/table/rows/selected.rb

@@ -0,0 +1,42 @@
+module ATSPI
+  class Accessible::Table
+    # Represents all selected rows of a {Table}
+    class Rows::Selected
+      include SelectableCollection::Selected
+
+      # @api private
+      INDEX_METHOD = :index
+
+      # @api private
+      def initialize(native)
+        @native = native
+      end
+
+    # @!group Enumerable interface
+      # Iterates over all selected rows
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-selected-rows atspi_table_get_selected_rows
+      def each
+        @native.selected_rows.each do |idx|
+          yield at(idx)
+        end
+      end
+
+      # @param n [Integer] the index in the collection of selected rows and
+      #   not the index in the collection of all the table's rows.
+      #
+      # @return [Row] the table's n'th selected row
+      def at(n)
+        super do |idx|
+          Row.new(@native, idx)
+        end
+      end
+
+      # @return [Integer] the number of selected rows
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-n-selected-rows atspi_table_get_n_selected_rows
+      def count
+        @native.n_selected_rows
+      end
+    # @!endgroup
+    end
+  end
+end

data/lib/atspi/accessible/table/rows.rb

@@ -0,0 +1,31 @@
+module ATSPI
+  class Accessible::Table
+    # Represents all rows in a {Table}
+    class Rows
+      include SelectableCollection
+
+      # @api private
+      def initialize(native)
+        @native = native
+      end
+
+    # @!group Enumerable interface
+      # @param idx [Integer]
+      #
+      # @return [Row] the row at index +idx+
+      def at(idx)
+        super do |mapped_idx|
+          Row.new(@native, mapped_idx)
+        end
+      end
+
+      # @return [Integer] its number of rows
+      #
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-n-rows atspi_table_get_n_rows
+      def count
+        @native.n_rows
+      end
+    # @!endgroup
+    end
+  end
+end

data/lib/atspi/accessible/table.rb

@@ -0,0 +1,50 @@
+module ATSPI
+  # Wraps libatspi's AtspiTable[https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html].
+  class Accessible::Table
+    # @api private
+    def initialize(native)
+      @native = native
+    end
+
+  # @group Attributes
+    # @return [Accessible,nil] its caption
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-caption atspi_table_get_caption
+    def caption
+      Accessible.new(@native.caption) if @native.caption
+    end
+
+    # @return [Accessible,nil] its summary
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-table.html#atspi-table-get-summary atspi_table_get_summary
+    def summary
+      Accessible.new(@native.summary) if @native.caption
+    end
+  # @endgroup
+
+  # @group Parts
+    # @return [Rows] its rows
+    def rows
+      Rows.new(@native)
+    end
+
+    # @return [Columns] its columns
+    def columns
+      Columns.new(@native)
+    end
+
+    # @return [Cells] its cells
+    def cells
+      Cells.new(@native)
+    end
+  # @endgroup
+
+  # @group Representations
+    # @return [String] itself as an inspectable string
+    def inspect
+      "#<#{self.class.name}:0x#{'%x14' % __id__} @caption=#{caption.inspect} " <<
+        "@cells=#{cells.inspect} @rows=#{rows.inspect} @columns=#{columns.inspect}>"
+    end
+  # @endgroup
+  end
+end

data/lib/atspi/accessible/text/caret.rb

@@ -0,0 +1,31 @@
+module ATSPI
+  class Accessible::Text
+    # Represents the caret in a {Text}.
+    class Caret < Offset
+      # @api private
+      def initialize(text_native)
+        @text_native = text_native
+      end
+
+    # @!group Actions
+      # @param offset [responds to #to_i]
+      #
+      # @return [true,false] indicating success
+      #
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-text.html#atspi-text-set-caret-offset atspi_text_set_caret_offset
+      def move_to(offset)
+        @text_native.set_caret_offset(offset.to_i)
+      end
+    # @!endgroup
+
+    # @!group Representations
+      # @return [Integer] its integer representation
+      #
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-text.html#atspi-text-get-caret-offset atspi_text_get_caret_offset
+      def to_i
+        @text_native.caret_offset
+      end
+    # @!endgroup
+    end
+  end
+end

data/lib/atspi/accessible/text/character.rb

@@ -0,0 +1,45 @@
+module ATSPI
+  class Accessible::Text
+    # Represents a single character in a {Text}.
+    class Character
+      # @api private
+      def initialize(native, offset)
+        @native = native
+        @offset = offset
+      end
+
+    # @!group Attributes
+      # @return [1] its length
+      def length
+        1
+      end
+
+      # @param relative_to [Symbol] coordinate system derived from
+      #   libatspi's {https://developer.gnome.org/libatspi/stable/libatspi-atspi-constants.html#AtspiCoordType AtspiCoordType enum}
+      #   by removing the prefix +ATSPI_COORD_TYPE+ and making it lowercase
+      #
+      # @return [Extents] its extents
+      #
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-text.html#atspi-text-get-character-extents atspi_text_get_character_extents
+      def extents(relative_to:)
+        Extents.new(@native.character_extents(@offset, relative_to))
+      end
+    # @!endgroup
+
+    # @!group Representations
+      # @return [String] its string representation
+      #
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-text.html#atspi-text-get-character-at-offset atspi_text_get_character_at_offset
+      def to_s
+        [@native.character_at_offset(@offset)].pack("U") # UCS-4 codepoint to readable character
+      end
+
+      # @return [String] itself as an inspectable string
+      def inspect
+        "#<#{self.class.name}:0x#{'%x14' % __id__} @to_s=#{to_s.inspect} @length=#{length} " <<
+          "@offset=#{@offset} @extents=#{extents(relative_to: :screen).inspect}>"
+      end
+    # @!endgroup
+    end
+  end
+end

data/lib/atspi/accessible/text/editable.rb

@@ -0,0 +1,90 @@
+class ATSPI::Accessible::Text
+  # Wraps libatspi's {https://developer.gnome.org/libatspi/stable/libatspi-atspi-editabletext.html#AtspiEditableText editable_text interface}.
+  module Editable
+  # @!group Attributes & States
+    # Checks if it is editable.
+    #
+    # @return [true,false]
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiAccessible.html#atspi-accessible-get-editable-text atspi_accessible_get_editable_text_iface
+    def editable?
+      not @native.editable_text_iface.nil?
+    end
+  # @!endgroup
+
+  # @!group Actions
+    # Replaces its content with the given one. Will succeed only if it's
+    # editable.
+    #
+    # @param text [respond to #to_s] the new text
+    #
+    # @return [true,false] indicating success
+    def set_to(text)
+      delete && insert(text.to_s)
+    end
+
+    # Inserts a string at the given offset. Will succeed only if it's editable.
+    #
+    # @param text [respond to #to_s] the text to insert
+    # @param at [responds to #to_i] the offset to insert the string at
+    #
+    # @return [true,false] indicating success
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-editabletext.html#atspi-editable-text-insert-text atspi_editable_text_insert_text
+    def insert(text, at: caret)
+      editable? and @native.insert_text(at.to_i, text.to_s, text.to_s.length)
+    end
+
+    # Pastes the string in the clipboard at the given offset. Will succeed
+    # only if it's editable.
+    #
+    # @param at [responds to #to_i] the offset to insert the string at
+    #
+    # @return [true,false] indicating success
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-editabletext.html#atspi-editable-text-paste-text atspi_editable_text_paste_text
+    def paste(at: caret)
+      editable? and @native.paste_text(at.to_i)
+    end
+
+    # Copies its content in the given range into the clipboard. Will succeed
+    # only if it's editable.
+    #
+    # @param from [responds to #to_i] the start offset of the range
+    # @param to [responds to #to_i] the end offset of the range
+    #
+    # @return [true,false] indicating success
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-editabletext.html#atspi-editable-text-copy-text atspi_editable_text_copy_text
+    def copy(from: 0, to: length)
+      editable? and @native.copy_text(from.to_i, to.to_i)
+    end
+
+    # Cuts its content in the given range and puts it into the clipboard. Will
+    # succeed only if it's editable.
+    #
+    # @param from [responds to #to_i] the start offset of the range
+    # @param to [responds to #to_i] the end offset of the range
+    #
+    # @return [true,false] indicating success
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-editabletext.html#atspi-editable-text-cut-text atspi_editable_text_cut_text
+    def cut(from: 0, to: length)
+      editable? and @native.cut_text(from.to_i, to.to_i)
+    end
+
+    # Deletes its content in the given range. Will succeed only if it's
+    # editable.
+    #
+    # @param from [responds to #to_i] the start offset of the range
+    # @param to [responds to #to_i] the end offset of the range
+    #
+    # @return [true,false] indicating success
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-editabletext.html#atspi-editable-text-delete-text atspi_editable_text_delete_text
+    def delete(from: 0, to: length)
+      editable? and @native.delete_text(from.to_i, to.to_i)
+    end
+  # @!endgroup
+  end
+end

data/lib/atspi/accessible/text/hyperlink.rb

@@ -0,0 +1,19 @@
+class ATSPI::Accessible
+  class Text
+    # Represents a hyperlink in a {Text}.
+    class Hyperlink < Hyperlink
+      # @api private
+      def initialize(text_native, native)
+        @text_native = text_native
+        super(native)
+      end
+
+      # @return [Range] its range
+      #
+      # @see https://developer.gnome.org/libatspi/stable/AtspiHyperlink.html#atspi-hyperlink-get-index-range atspi_hyperlink_get_index_range
+      def range
+        Range.new(@text_native, @native.index_range)
+      end
+    end
+  end
+end

data/lib/atspi/accessible/text/hypertext.rb

@@ -0,0 +1,29 @@
+class ATSPI::Accessible::Text
+  # Wraps libatspi's {https://developer.gnome.org/libatspi/stable/libatspi-atspi-hypertext.html#AtspiHypertext hypertext interface}.
+  module Hypertext
+  # @!group Attributes & States
+    # Checks if it is a hypertext.
+    #
+    # @return [true,false]
+    #
+    # @see https://developer.gnome.org/libatspi/stable/AtspiAccessible.html#atspi-accessible-get-hypertext atspi_accessible_get_hypertext_iface
+    def hypertext?
+      not @native.hypertext_iface.nil?
+    end
+
+    # @return [Array<Hyperlink>] its hyperlinks. Will be an empty array if it
+    #   is not a hypertext.
+    #
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-hypertext.html#atspi-hypertext-get-n-links atspi_hypertext_get_n_links
+    # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-hypertext.html#atspi-hypertext-get-link atspi_hypertext_get_link
+    def hyperlinks
+      if hypertext?
+        @native.n_links.times.map{ |idx| Hyperlink.new(@native, @native.link(idx)) }
+      else
+        []
+      end
+    end
+    alias_method :links, :hyperlinks
+  # @!endgroup
+  end
+end

data/lib/atspi/accessible/text/offset.rb

@@ -0,0 +1,59 @@
+module ATSPI
+  class Accessible::Text
+    # Represents an offset in a {Text}.
+    class Offset
+      # @api private
+      def initialize(text_native, offset)
+        @text_native = text_native
+        @offset = offset
+      end
+
+    # @!group Attributes
+      # @param boundary [Symbol] the boundary type derived from libatspi's
+      #   {https://github.com/GNOME/at-spi2-core/blob/9439376bc09333e6baf7111d5246a7beff1f7a14/atspi/atspi-constants.h#L348 AtspiTextGranularity enum}
+      #   by removing the prefix +ATSPI_TEXT_GRANULARITY_+ and making it lowercase
+      #
+      # @return [Range] the text between the closest boundary to the left and
+      #   right
+      #
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-text.html#atspi-text-get-text-at-offset atspi_text_get_string_at_offset
+      def text_around(boundary)
+        Range.new(@text_native, @text_native.string_at_offset(to_i, boundary))
+      end
+
+      # @return [Character] its character
+      def character
+        Character.new(@text_native, to_i)
+      end
+
+      # @return [Hyperlink,nil] its hyperlink. Will be +nil+ if its text does
+      #   not implement the {https://developer.gnome.org/libatspi/stable/AtspiAccessible.html#atspi-accessible-get-hypertext hypertext interface}
+      #   or there simply is no hyperlink at the offset.
+      #
+      # @see https://developer.gnome.org/libatspi/stable/AtspiAccessible.html#atspi-accessible-get-hypertext atspi_accessible_get_hypertext
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-hypertext.html#atspi-hypertext-get-link-index atspi_hypertext_get_link_index
+      # @see https://developer.gnome.org/libatspi/stable/libatspi-atspi-hypertext.html#atspi-hypertext-get-link atspi_hypertext_get_link
+      def hyperlink
+        if @text_native.hypertext_iface
+          idx = @text_native.link_index(to_i)
+          Hyperlink.new(@text_native, @text_native.link(idx)) if idx != -1
+        end
+      end
+      alias_method :link, :hyperlink
+    # @!endgroup
+
+    # @!group Representations
+      # @return [Integer] its integer representation
+      def to_i
+        @offset
+      end
+
+      # @return [String] itself as an inspectable string
+      def inspect
+        "#<#{self.class.name}:0x#{'%x14' % __id__} @to_i=#{to_i} " <<
+          "@character=#{character.to_s.inspect} @text_around=#{text_around(:word).to_s.inspect}>"
+      end
+    # @!endgroup
+    end
+  end
+end