Class: Sketchup::ComponentInstance

Inherits:
Drawingelement show all
Defined in:
lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb

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 Method Summary collapse

Methods inherited from Drawingelement

#bounds, #casts_shadows=, #casts_shadows?, #erase!, #hidden=, #hidden?, #layer, #layer=, #material, #material=, #receives_shadows=, #receives_shadows?, #visible=, #visible?

Methods inherited from Entity

#attribute_dictionaries, #attribute_dictionary, #delete_attribute, #deleted?, #entityID, #get_attribute, #inspect, #model, #parent, #persistent_id, #set_attribute, #to_s, #typename, #valid?

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



38
39
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 38

def add_observer(observer)
end

#definition ⇒ Sketchup::ComponentDefinition

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



58
59
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 58

def definition
end

#definition=(definition) ⇒ Sketchup::ComponentDefinition

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



86
87
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 86

def definition=(definition)
end

#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:

Returns:

  • (Boolean)

Version:

  • SketchUp 8.0



104
105
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 104

def equals?(instance)
end

#explode ⇒ Array<Sketchup:Entity>

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:

  • (Array<Sketchup:Entity>) —

    An array of entity objects if successful, false if unsuccessful

Version:

  • SketchUp 6.0



123
124
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 123

def explode
end

#glued_to ⇒ Sketchup::Face?

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

Returns nil if it is not glued to anything.

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

Returns:

  • (Sketchup::Face, nil) —

    the Entity object that the instance is glued to (if successful)

Version:

  • SketchUp 6.0



147
148
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 147

def glued_to
end

#glued_to=(face) ⇒ Sketchup::Face?

The glued_to= method glues this instance to a face.

This method will raise an exception if the instance cannot be glued to the given face. Instances cannot be glued if the definition of the instance doesn’t support gluing or if the alignment is wrong.

Examples:

depth = 100
width = 100
path=Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
point = Geom::Point3d.new 10,10,0
transform = Geom::Transformation.new point
definitions = model.definitions
componentdefinition = definitions.load path
instance = entities.add_instance componentdefinition, transform
begin
  status = instance.glued_to = face
rescue
  UI.messagebox $!.message
end
if (status)
  UI.messagebox status.to_s
else
  UI.messagebox "Failure"
end

Parameters:

Returns:

  • (Sketchup::Face, nil) —

    • the Face object where the component is glued if

    successful

Version:

  • SketchUp 6.0



192
193
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 192

def glued_to=(face)
end

#guid ⇒ String

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



208
209
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 208

def guid
end

#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:

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



231
232
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 231

def intersect(instance)
end

#locked=(lock) ⇒ Boolean

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



249
250
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 249

def locked=(lock)
end

#locked? ⇒ Boolean

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?

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0



264
265
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 264

def locked?
end

#make_unique ⇒ Sketchup::ComponentInstance

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:

Version:

  • SketchUp 6.0



288
289
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 288

def make_unique
end

#manifold? ⇒ Boolean

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?

Returns:

  • (Boolean)

Version:

  • SketchUp 8.0



303
304
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 303

def manifold?
end

#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



329
330
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 329

def move!(transformation)
end

#name ⇒ String

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



344
345
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 344

def name
end

#name=(name) ⇒ Sketchup::ComponentInstance

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:

Version:

  • SketchUp 6.0



362
363
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 362

def name=(name)
end

#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:

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



383
384
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 383

def outer_shell(instance)
end

#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



402
403
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 402

def remove_observer(observer)
end

#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 (Sketchup::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



434
435
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 434

def show_differences(instance, verbose)
end

#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.

Examples:

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

Parameters:

Returns:

  • (Array(Sketchup::Group, Sketchup::Group, Sketchup::Group)) —

    A vector (array) of the three 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.

Version:

  • SketchUp 8.0



461
462
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 461

def split(instance)
end

#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:

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



484
485
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 484

def subtract(instance)
end

#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.

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0



503
504
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 503

def transform!(transform)
end

#transformation ⇒ Geom::Transformation

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



519
520
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 519

def transformation
end

#transformation=(transformation) ⇒ Object

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



536
537
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 536

def transformation=(transformation)
end

#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:

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



560
561
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 560

def trim(instance)
end

#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:

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



583
584
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 583

def union(instance)
end

#volume ⇒ Float

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



601
602
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb', line 601

def volume
end