Class: Sketchup::InstancePath

Inherits:

Object

• Object
• Sketchup::InstancePath

Includes:

Enumerable

Overview

The InstancePath class represent the instance path to a given entity within the model hierarchy.

Version:

• SketchUp 2017

Instance Method Summary

• #==(other) ⇒ Boolean

  `true` if the instances paths represent the same set of entities.

• #[](index) ⇒ Sketchup::Entity

  The elements of an instance path can be accessed similarly to an array.

• #each {|entity| ... } ⇒ nil

  The yielded entities will start with the root and end with the leaf.

• #empty? ⇒ Boolean
• #include?(object) ⇒ Boolean

  Returns `true` if the instance path contain the given object.

• #initialize(path) ⇒ Sketchup::InstancePath constructor
• #leaf ⇒ Sketchup::Entity

  The leaf of an instance path is the last element which can be any entity that can be represented in the model.

• #length ⇒ Integer

  #length is an alias of #size.

• #persistent_id_path ⇒ String

  The serialized version of an instance path is the persistent ids of its entities concatenated with a period.

• #root ⇒ Sketchup::Group, ...

  The root of an instance path is the element located closest to the model root.

• #size ⇒ Integer
• #to_a ⇒ Array

  An array representing the instance path.

• #transformation(*args) ⇒ Object
• #valid? ⇒ Boolean

  An instance path is valid if it has at least one element and consist of groups and instances with exception of the leaf which can be any entity.

Constructor Details

#initialize(path) ⇒ Sketchup::InstancePath

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])

Parameters:

• path (Array<Sketchup::Entity>) —

  The leaf can be any entity, but the rest must be a group or component instance.

Raises:

• (ArgumentError) —

  if the instance path isn't composed of instances and an optional leaf entity.

Version:

• SketchUp 2017

Instance Method Details

#==(other) ⇒ Boolean

Returns `true` if the instances paths represent the same set of entities.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.size > 1
  # do something
end

Returns:

• (Boolean) —

  `true` if the instances paths represent the same set of entities.

Version:

• SketchUp 2017

#[](index) ⇒ Sketchup::Entity

Note:

This method does not accept negative indices. For the exact behavior of an array, use {#to_a}.

The elements of an instance path can be accessed similarly to an array.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path[0] == group # returns true
path[1] == edge # returns true

Parameters:

• index (Integer)

Returns:

• (Sketchup::Entity)

Raises:

• (IndexError) —

  if the given index is out of bounds

• (TypeError) —

  if the index is not of integer type

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#each {|entity| ... } ⇒ nil

The yielded entities will start with the root and end with the leaf.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path.each { |entity|
  # do something
}

Yield Parameters:

• entity (Sketchup::Entity)

Returns:

• (nil)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#empty? ⇒ Boolean

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.empty?
  # do something...
end

Returns:

• (Boolean)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#include?(object) ⇒ Boolean

Returns `true` if the instance path contain the given object.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.include?(edge)
  # do something...
end

Parameters:

• object (Object)

Returns:

• (Boolean)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#leaf ⇒ Sketchup::Entity

The leaf of an instance path is the last element which can be any entity that can be represented in the model. This is normally a Drawingelement, but could be a Vertex.

An instance can also be a leaf.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path.leaf == edge # returns true

Returns:

• (Sketchup::Entity)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#length ⇒ Integer

#length is an alias of #size.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.length > 1
  # do something
end

Returns:

• (Integer)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

See Also:

• #size

Version:

• SketchUp 2017

#persistent_id_path ⇒ String

The serialized version of an instance path is the persistent ids of its entities concatenated with a period.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
pid_path = path.persistent_id_path # something like "342.345"

Returns:

• (String)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

See Also:

• Model#instance_path_from_pid_path

Version:

• SketchUp 2017

#root ⇒ Sketchup::Group, ...

The root of an instance path is the element located closest to the model root. This will be a group or component instance. If you have a non-instance as a leaf with no other parent component this will return `nil`.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path.root == group # returns true

Returns:

• (Sketchup::Group, Sketchup::ComponentInstance, nil)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#size ⇒ Integer

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.size > 1
  # do something
end

Returns:

• (Integer)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

See Also:

• #length

Version:

• SketchUp 2017

#to_a ⇒ Array

Returns an array representing the instance path.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
pid_string = path.to_a.join('.')

Returns:

• (Array) —

  an array representing the instance path.

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#transformation ⇒ Geom::Transformation #transformation(index) ⇒ Geom::Transformation

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
tr = path.transformation

Overloads:

• #transformation ⇒ Geom::Transformation

  Returns the combined transformation up to the the leaf entity.

  Returns:

  • (Geom::Transformation) —

    the combined transformation up to the the leaf entity.

• #transformation(index) ⇒ Geom::Transformation

  Returns the combined transformation up to the the given index.

  Parameters:

  • index (Integer)

  Returns:

  • (Geom::Transformation) —

    the combined transformation up to the the given index.

Raises:

• (IndexError) —

  if the given index is out of bounds

• (TypeError) —

  if the index is not of integer type

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#valid? ⇒ Boolean

An instance path is valid if it has at least one element and consist of groups and instances with exception of the leaf which can be any entity.

This method doesn't check if the path can actually be looked up in the model.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.valid?
  # do something...
end

Returns:

• (Boolean)

Version:

• SketchUp 2017