123456789_123456789_123456789_123456789_123456789_

Class: Sketchup::ComponentInstance

Relationships
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
Instance Chain:
Inherits: Sketchup::Drawingelement

Overview

The ComponentInstance class is used to represent component instances of a component definition or components that have been dragged from the Component Browser and placed (thus, instanced) within the Model. Therefore, the ComponentInstance class contains a reference to a corresponding ComponentDefinition object and a Transformation object (which contains the location of the component in the Drawing Window).

Starting from SketchUp 2018+, the ComponentInstance class contains default attributes when created or imported. The attributes are: “Owner”, “Status”. See the Help article for more information. The dictionary cannot be deleted via ruby and an @raise ArgumentError will be raised. The key/value pairs in the dictionary can be deleted safely.

Version:

  • SketchUp 6.0

Instance Attribute Summary

Drawingelement - Inherited

#casts_shadows=

The casts_shadows= method is used to set the Drawingelement to cast shadows.

#casts_shadows?

The casts_shadows? method is used to determine if the Drawingelement is casting shadows.

#hidden=

The hidden= method is used to set the hidden status for an element.

#hidden?

The hidden? method is used to determine if the element is hidden.

#layer

The layer method is used to retrieve the Layer object of the drawing element.

#layer=

The layer= method is used to set the layer for the drawing element.

#material

The material method is used to retrieve the material for the drawing element.

#material=

The material= method is used to set the material for the drawing element.

#receives_shadows=

The receive_shadows= method is used to set the Drawingelement to receive shadows.

#receives_shadows?

The receive_shadows? method is used to determine if the Drawingelement is receiving shadows.

#visible=

The visible= method is used to set the visible status for an element.

#visible?

The visible? method is used to get the visible status for an element.

Entity - Inherited

#deleted?

The deleted? method is used to determine if your entity is still valid (not deleted by another script, for example.).

#valid?

The #valid? method is used to determine if your entity is still valid (not deleted by another script, for example).

Instance Method Summary

Drawingelement - Inherited

#bounds

The #bounds method is used to retrieve the ::Geom::BoundingBox bounding a Drawingelement.

#erase!

The #erase! method is used to erase an element from the model.

Entity - Inherited

#add_observer

The add_observer method is used to add an observer to the current object.

#attribute_dictionaries

The attribute_dictionaries method is used to retrieve the AttributeDictionaries collection attached to the entity.

#attribute_dictionary

The attribute_dictionary method is used to retrieve an attribute dictionary with a given name that is attached to an Entity.

#delete_attribute

The #delete_attribute method is used to delete an attribute from an entity.

#entityID

The entityID method is used to retrieve a unique ID assigned to an entity.

#get_attribute

The #get_attribute method is used to retrieve the value of an attribute in the entity’s attribute dictionary.

#inspect

The #inspect method is used to retrieve the string representation of the entity.

#model

The model method is used to retrieve the model for the entity.

#parent

The parent method is used to retrieve the parent of the entity.

#persistent_id

The #persistent_id method is used to retrieve a unique persistent id assigned to an entity.

#remove_observer

The remove_observer method is used to remove an observer from the current object.

#set_attribute

The set attribute is used to set the value of an attribute in an attribute dictionary with the given name.

#to_s

The #to_s method is used to retrieve the string representation of the entity.

#typename

The typename method retrieves the type of the entity, which will be a string such as “Face”, “Edge”, or “Group”.

Instance Attribute Details

#definitionSketchup::ComponentDefinition (rw)

The definition method is used to retrieve the component definition for this component instance.

Examples:

# First create an instance for us to look at.
entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)

# You can get an instance's definition with this method.
definition = componentinstance.definition

Returns:

Version:

  • SketchUp 6.0

#definition=(definition) ⇒ Sketchup::ComponentDefinition (rw)

The definition= method is used to set the component definition for this component.

This method causes the instance to use a different definition, but it will use the same transformation to position it in the Model.

Examples:

# Assumes that the active model contains two different components.
instance1 = Sketchup.active_model.entities[0]
instance2 = Sketchup.active_model.entities[1]

# Grab handles to our two definitions.
definition1 = instance1.definition
definition2 = instance2.definition

# Replace 2nd instance with the 1st definition.
instance2.definition = definition1

Parameters:

Returns:

Version:

  • SketchUp 6.0

#glued_toSketchup::Face, ... (rw)

The #glued_to method is used to retrieve the entity that this instance is glued to.

Examples:

point = Geom::Point3d.new(10, 20, 30)
transform = Geom::Transformation.new(point)
model = Sketchup.active_model
entities = model.active_entities
path = Sketchup.find_support_file("Bed.skp", "Components/Components Sampler/")
definitions = model.definitions
componentdefinition = definitions.load(path)
instance = entities.add_instance(componentdefinition, transform)
status = instance.glued_to

Version:

  • SketchUp 6.0

#glued_to=(drawing_element) ⇒ Sketchup::Face, ... (rw)

The glued_to= method glues this instance to a drawing element. When moving this other drawing elment with the Move tool, the glued instance moves with it.

In SketchUp 2021.1 support for passing Group, ComponentInstance and Image was added.

Examples:

model = Sketchup.active_model
entities = model.active_entities

# Create a face
face = entities.add_face([[0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0]])

# Add component
path = Sketchup.find_support_file("Bed.skp", "Components/Components Sampler/")
point = Geom::Point3d.new(10, 10, 0)
transformation = Geom::Transformation.new(point)
definitions = model.definitions
definition = definitions.load(path)
instance = entities.add_instance(definition, transformation)

# Make component "gluable"
definition.behavior.is2d = true

# Glue the component to the face.
# If you now move the face, the component will follow.
instance.glued_to = face

Parameters:

Returns:

Raises:

  • ArgumentError if the Behavior for this component doesn’t allow gluing, if the alignment is wrong, or if this would lead to cyclic gluing.

Version:

  • SketchUp 6.0

#locked=(lock) ⇒ Boolean (rw)

The locked= method is used to lock a component instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.locked = true

Parameters:

  • lock (Boolean)

Returns:

  • (Boolean)

    true if the component instance is locked. False if the instance is not locked.

Version:

  • SketchUp 6.0

#locked?Boolean (rw)

The locked? method is used to determine if a component instance is locked.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.locked?

Version:

  • SketchUp 6.0

#manifold?Boolean (readonly)

The manifold? method is used to determine if an instance is manifold.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.manifold?

Version:

  • SketchUp 8.0

#nameString (rw)

The name method is used to get the name of this instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
name = componentinstance.name

Returns:

  • (String)

    the string name of the ComponentInstance

Version:

  • SketchUp 6.0

#name=(name) ⇒ ComponentInstance (rw)

The name method is used to set the name of this instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
componentinstance.name = "Sang"

Parameters:

  • name (String)

    the string name to set

Returns:

  • (ComponentInstance)

    the newly named ComponentInstance

Version:

  • SketchUp 6.0

#transformationGeom::Transformation (rw)

The transformation method is used to retrieve the transformation of this instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
t = componentinstance.transformation

Returns:

Version:

  • SketchUp 6.0

#transformation=(transformation) (rw)

The #transformation= method is used to set the transformation of this component instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
new_transformation = Geom::Transformation.new([100,0,0])
componentinstance.transformation = new_transformation

Parameters:

Version:

  • SketchUp 6.0

Instance Method Details

#add_observer(observer) ⇒ Boolean

The add_observer method is used to add an observer to the current object.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.add_observer observer

Parameters:

  • observer (Object)

    An observer.

Returns:

  • (Boolean)

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#equals?(instance) ⇒ Boolean

The equals? method is used to determine if a component instance is geometrically equivalent to another instance.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
status = instance1.equals?(instance2)

Parameters:

  • instance (ComponentInstance)

    The instance to compare this instance with.

Version:

  • SketchUp 8.0

#explodeArray<Sketchup::Entity>, false

The explode method is used to explode the component instance into separate entities.

Examples:

# Assuming 'instance' is a ComponentInstance object
array = instance.explode
if array
  UI.messagebox "Exploded the component instance"
else
  UI.messagebox "Failure"
end

Returns:

Version:

  • SketchUp 6.0

#guidString

The guid method is used to get the base 64 encoded unique id for this SketchUp object.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
guid = componentinstance.guid

Returns:

  • (String)

    a unique 22 character string

Version:

  • SketchUp 2014

#intersect(instance) ⇒ Sketchup::Group?

Note:

This method is not available in SketchUp Make.

The intersect method is used to compute the boolean intersection of two instances representing manifold solid volumes (this - arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.intersect(instance2)

Parameters:

  • instance (ComponentInstance)

    The instance to intersect this instance with.

Returns:

  • (Sketchup::Group, nil)

    The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

  • SketchUp 8.0

#make_uniqueComponentInstance

The #make_unique method is used to create a component definition for this instance that is not used by any other instances. If the component is already unique in the model, nothing happens.

Examples:

point = Geom::Point3d.new(10,20,30)
transform = Geom::Transformation.new(point)
model = Sketchup.active_model
entities = model.active_entities

path = Sketchup.find_support_file("Bed.skp",
  "Components/Components Sampler/")
definitions = model.definitions
componentdefinition = definitions.load(path)
instance = entities.add_instance(componentdefinition, transform)
# Returns unique component instance
instance.make_unique

Returns:

  • (ComponentInstance)

    returns itself

Version:

  • SketchUp 6.0

#move!(transformation) ⇒ Boolean

Note:

Despite the name being similar to #transform!, this method closer corresponds to #transformation=.

The #move! method is used to set the transformation of this component instance, similarly to #transformation= but without recording to the undo stack.

This method is useful for moving entities inside of an animation or page transition.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
new_transformation = Geom::Transformation.new([100,0,0])
componentinstance.move!(new_transformation)

Parameters:

Returns:

  • (Boolean)

    true if successful, false if unsuccessful

Version:

  • SketchUp 6.0

#outer_shell(instance) ⇒ Sketchup::Group?

The outer_shell method is used to compute the outer shell of the two instances representing manifold solid volumes (this || arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.outer_shell(instance2)

Parameters:

  • instance (ComponentInstance)

    The instance to outer shell this instance with.

Returns:

  • (Sketchup::Group, nil)

    The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

  • SketchUp 8.0

#remove_observer(observer) ⇒ Boolean

The remove_observer method is used to remove an observer from the current object.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.remove_observer observer

Parameters:

  • observer (Object)

    An observer.

Returns:

  • (Boolean)

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#show_differences(instance, verbose) ⇒ Boolean

The show_differences method is used to determine if a component instance is geometrically equivalent to another instance and in addition move the non- matching and matching geometry to new layers.

This method will move both instances to Layer0. Geometry that is the same in both components will be moved to a new layer named def_name + “_same”. Geometry that is not the same will be moved to a layer named def_name + “_diff”.

If verbose is true, a list of all the geometry that is different from one component to the other is displayed texturally in the Ruby Console.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
status = instance1.show_differences(instance2, true)

Parameters:

  • instance (ComponentInstance)

    The instance to be compared with.

  • verbose (Boolean)

    A boolean flag indicating whether to display a textural report of the found differences to the Ruby console.

Returns:

  • (Boolean)

    true if the instances are geometrically equivalent, otherwise false.

Version:

  • SketchUp 8.0

#split(instance) ⇒ Array(Sketchup::Group, Sketchup::Group, Sketchup::Group)

Note:

This method is not available in SketchUp Make.

The split method is used to compute the boolean split (map overlay)of the two instances representing manifold solid volumes (this - arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

resultant groups if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned. The 3 groups are as follows: The intersection of volume 1 & volume 2, the difference of volume 1 minus volume 2, and the reverse difference of volume 2 minus volume 1.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.split(instance2)

Parameters:

  • instance (ComponentInstance, nil)

    The instance to split this instance with.

Returns:

Version:

  • SketchUp 8.0

#subtract(instance) ⇒ Sketchup::Group?

Note:

This method is not available in SketchUp Make.

The subtract method is used to compute the boolean difference of the two instances representing manifold solid volumes (this - arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.subtract(instance2)

Parameters:

  • instance (ComponentInstance)

    The instance to subtract this instance from.

Returns:

  • (Sketchup::Group, nil)

    The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

  • SketchUp 8.0

#transform!(transform) ⇒ Boolean

Apply a ::Geom::Transformation to a component instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0, 0, 0])
componentinstance = entities.add_instance(definition, transformation)
new_transformation = Geom::Transformation.new([100, 0, 0])
componentinstance.transform! new_transformation

Parameters:

  • transform (Geom::Transformation)

    The transformation object to apply to the component instance.

Version:

  • SketchUp 6.0

#trim(instance) ⇒ Sketchup::Group?

Note:

This method is not available in SketchUp Make.

The trim method is used to compute the (non-destructive) boolean difference of the two instances representing manifold solid volumes (this - arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.trim(instance2)

Parameters:

  • instance (ComponentInstance)

    The instance to trim this instance against.

Returns:

  • (Sketchup::Group, nil)

    The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

  • SketchUp 8.0

#union(instance) ⇒ Sketchup::Group?

Note:

This method is not available in SketchUp Make.

The union method is used to compute the boolean union of the two instances representing manifold solid volumes (this | arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.union(instance2)

Parameters:

  • instance (ComponentInstance)

    The instance to union this instance with.

Returns:

  • (Sketchup::Group, nil)

    The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

  • SketchUp 8.0

#volumeFloat

The volume method is used to compute the volume of this instance if and only if this instance is manifold.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
volume = componentinstance.volume

Returns:

  • (Float)

    If the instance represents a manifold volume, volume will be a positive value. If volume is negative, the instance is not manifold.

Version:

  • SketchUp 8.0