Class: ATSPI::Accessible::Children

Inherits:
Object
  • Object
show all
Includes:
SelectableCollection
Defined in:
lib/atspi/accessible/children.rb

Overview

Wraps the children part of libatspi’s AtspiAccessible and parts of AtspiSelection.

Instance are enumerables supporting item access and can be treated more or less like an array.

Direct Known Subclasses

Table::Cells

Defined Under Namespace

Classes: Selected

Enumerable interface collapse

Selection collapse

Filter collapse

Options collapse

Representation collapse

Instance Method Details

#[](idx) ⇒ Object Originally defined in module Collection

alias for #at

#at(idx) ⇒ Accessible

Returns its child at index idx.

Parameters:

  • idx (Integer)

Returns:

See Also:



21
22
23
24
25
 
# File 'lib/atspi/accessible/children.rb', line 21

def at(idx)
  super do |mapped_idx|
    Accessible.new(@native.child_at_index(mapped_idx))
  end
end

#count ⇒ Integer

Returns its number of children.

Returns:

  • (Integer) —

    its number of children

See Also:



30
31
32
 
# File 'lib/atspi/accessible/children.rb', line 30

def count
  @native.child_count
end

#deselect_all ⇒ true, false

Tries to deselect all children

Returns:

  • (true, false) —

    indicates success

See Also:



70
71
72
 
# File 'lib/atspi/accessible/children.rb', line 70

def deselect_all
  selectable? and @native.clear_selection
end

#each ⇒ Object Originally defined in module Collection

prerequisite for Enumerable

#inspect ⇒ String Originally defined in module SelectableCollection

Returns instance as inspectable string.

Returns:

  • (String) —

    instance as inspectable string

#last(n = 1) ⇒ Object+ Originally defined in module Collection

Returns item(s) from the end.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of items to return

Returns:

  • (Object, Array<Object>) —

    item(s) from the end

#length ⇒ Object Originally defined in module Collection

alias for #count

#limit_to(limit) ⇒ Descendants

Returns the children collection as limited descendants collection.

Parameters:

  • limit (Integer) —

    A value of 0 disables the limit.

Returns:

  • (Descendants) —

    the children collection as limited descendants collection.

See Also:



100
101
102
 
# File 'lib/atspi/accessible/children.rb', line 100

def limit_to(limit)
  Accessible::Descendants.new(@native).recursive(false).limit_to(limit)
end

#recursive(recursive = true) ⇒ Descendants, self

Returns self if recursive is set to false. A collection of all descendants if recursive is set to true.

Parameters:

  • recursive (true, false) (defaults to: true) —

    To limit the descendants to the direct children of the accessible only, set recursive to false. By setting recursive to true, all descendants in the tree below the accessible the descendants are considered.

Returns:

  • (Descendants, self) —

    self if recursive is set to false. A collection of all descendants if recursive is set to true

See Also:



108
109
110
111
112
113
114
 
# File 'lib/atspi/accessible/children.rb', line 108

def recursive(recursive = true)
  if recursive
    Accessible::Descendants.new(@native)
  else
    self
  end
end

#select_all ⇒ true, false

Tries to select all children

Returns:

  • (true, false) —

    indicates success

See Also:



61
62
63
 
# File 'lib/atspi/accessible/children.rb', line 61

def select_all
  selectable? and @native.select_all
end

#selectable? ⇒ true, false

Checks if the accessible the children belong to implements the selection interface.

Returns:

  • (true, false)

See Also:



42
43
44
 
# File 'lib/atspi/accessible/children.rb', line 42

def selectable?
  not @native.selection_iface.nil?
end

#selected ⇒ Selected, []

Returns its selected subset. It will be an empty array if children are not selectable.

Returns:

  • (Selected, []) —

    its selected subset. It will be an empty array if children are not selectable.



48
49
50
51
52
53
54
 
# File 'lib/atspi/accessible/children.rb', line 48

def selected
  if selectable?
    Selected.new(@native)
  else
    []
  end
end

#size ⇒ Object Originally defined in module Collection

alias for #count

#sort_by(order) ⇒ Descendants

Returns the children collection as sorted descendants collection.

Examples:

descendants.sort_by(:flow) # => #<ATSPI::Accessible::Descendants:0x101c51014 … >

Parameters:

  • order (Symbol) —

    derived from libatspi’s AtspiCollectionSortOrder enum by removing the prefix ATSPI_Collection_SORT_ORDER_ and making it lowercase.

Returns:

  • (Descendants) —

    the children collection as sorted descendants collection.

See Also:



92
93
94
 
# File 'lib/atspi/accessible/children.rb', line 92

def sort_by(order)
  Accessible::Descendants.new(@native).recursive(false).sort_by(order)
end

#where(state: ) ⇒ Descendants #where(attributes: ) ⇒ Descendants #where(role: ) ⇒ Descendants #where(interface: ) ⇒ Descendants #where(name: ) ⇒ Descendants #where(filters) ⇒ Descendants

Note:

Filtering sometimes felt rocky on libatspi’s side during testing. See the notes in the following sections for details.

Returns the children collection as filtered descendants collection.

Overloads:

  • #where(state: ) ⇒ Descendants

    Filters by state(s)

    Examples:

    # Selects accessibles in state :selected
where(state: :selected)

# Selects accessibles in both states :selectable *and* :selected
where(state: [:selectable, :selected])

# Selects accessibles in either state :selectable *or* :selected (or both)
where(state: [:selectable, :selected, mode: :any])

    Parameters:

    • state (Symbol, Array<Symbol[, mode: :all]>) (defaults to: ) —

      the states filter. States are given as symbol derived from libatspi’s AtspiStateType enum by removing the ATSPI_STATE_ prefix and making it lowercase.

      When given an array, the last item can be set to a hash configuring the filter mode. The mode has to be one of :all, :any, :none, :empty. It corresponds to the match type in atspi_match_rule_new and AtspiCollectionMatchType, accordingly.

  • #where(attributes: ) ⇒ Descendants
    Note:

    Filtering attributes in mode :all effectively disables the filter and returns all descendants. It does not narrow down the result set as one would expect.

    Filters by attribute(s)

    Examples:

    # Selects accessibles with value "button" for attribute "tag"
where(attributes: { "tag" => "button" })

# Selects accessibles with value "button" *or* "input" for attribute "tag"
where(attributes: { "tag" => ["button", "input"] })

# Selects accessibles with value "button" for attribute "tag" *or* value "block" for attribute "display"
where(attributes: { "tag" => "button", "display" => "block" })

    Parameters:

    • attributes (Hash<String => String[, mode: :any]>) (defaults to: ) —

      the attributes filter. Attributes are given as a Hash as returned by ATSPI::Accessible#attributes.

      The :mode key of the hash can be used to configuring the filter mode. The mode has to be one of :all, :any, :none, :empty. It corresponds to the match type in atspi_match_rule_new and AtspiCollectionMatchType, accordingly.

  • #where(role: ) ⇒ Descendants
    Note:

    Setting the mode to a value different from :any for role filters effectively disables the filter and returns all descendants. Since an accessible has only exactly one role, one would expect that it does return an empty set, but it does not.

    Filters by role

    Examples:

    # Selects accessibles with role :frame
where(role: :frame)

# Selects accessibles with role :page_tab_list *or* :page_tab
where(role: [:page_tab_list, :page_tab])

    Parameters:

    • role (Symbol, Array<Symbol[, mode: :any]>) (defaults to: ) —

      the roles filter. Roles are given as symbols derived from libatspi’s AtspiRole enum by removing the ATSPI_ROLE_ prefix and making it lowercase.

      When given an array, the last item can be set to a hash configuring the filter mode. The mode has to be one of :all, :any, :none, :empty. It corresponds to the match type in atspi_match_rule_new and AtspiCollectionMatchType, accordingly.

  • #where(interface: ) ⇒ Descendants
    Note:

    Filtering by multiple interfaces and including :Accessible or :Collection in mode :all does not work. Instead it always returns an empty set.

    Note:

    Filtering interfaces in mode :none effectively disables the filter and returns the entire set of descendants. Since an accessible always has at least the accessible interfaces it implements one would expect that it does return an empty set, but it does not.

    Filters by interface(s)

    Examples:

    # Selects accessibles implementing Action
where(interface: :Action)

# Selects accessibles implementing Action+ *and* Selection
where(interface: [:Action, :Selection])

# Selects accessibles implementing Action *or* +Selection or both
where(interface: [:Action, :Selection, mode: :any])

    Parameters:

    • role (Symbol, Array<Symbol[, mode: :all]>) —

      the role filter. Interfaces are given as symbols derived from their name returned by ATSPI::Accessible#interfaces

      When given an array, the last item can be set to a hash configuring the filter mode. The mode has to be one of :all, :any, :none, :empty. It corresponds to the match type in atspi_match_rule_new and AtspiCollectionMatchType, accordingly.

  • #where(name: ) ⇒ Descendants

    Filters by name

    Examples:

    # Selects accessibles with name exactly "Accessibles Name"
where(name: "Accessible Name")

# Selects accessibles with a name matching /a.{11}y/
where(name: /a.{11}y/)

    Parameters:

    • name (String, RegExp) (defaults to: ) —

      the name filter. When given a string it is matched against the entire name from start to end like /^name$/.

  • #where(filters) ⇒ Descendants

    Combines all or a subset of filters in a single call.

    Examples:

    where(name: /a.{11}y/, state: [:selectable, :selected], role: :page_tab)

    Parameters:

    • filters (Hash)

    Options Hash (filters):

    • :states (Symbol, Array)
    • :role (Symbol, Array)
    • :name (String, RegExp)
    • :attributes (Hash)
    • :interface (Symbol, Array)

Returns:

  • (Descendants) —

    the children collection as filtered descendants collection.

See Also:



81
82
83
 
# File 'lib/atspi/accessible/children.rb', line 81

def where(*args)
  Accessible::Descendants.new(@native).recursive(false).where(*args)
end