Class: Sketchup::ComponentDefinition

Inherits:
DrawingElement
  • Object
show all
Includes:
Comparable
Defined in:
lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb

Overview

The ComponentDefinition class is used to define the contents for a SketchUp component. Components are a collection of entities that can be instanced and reused multiple times throughout a model. For example, you could draw a chair once, turn it into a component, and then use 6 instances of it to surround a table. Edits to the original “definition” will then propagate across all of its instances.

The ComponentDefinition class contains the global entities and settings for each definition. See the ComponentInstance class for how each copy is defined.

Starting from SketchUp 2018+, the ComponentDefinition class contains a new default attribute dictionary named “SU_DefinitionSet” with default keys named named “Price”, “Size”, “Url”. See the Help article for more information. The dictionary cannot be deleted via ruby and an ArgumentError will be raised. The key/value pairs in the dictionary can be deleted safely.

Version:

  • SketchUp 6.0

Instance Method Summary collapse

Instance Method Details

#<=>(compdef2) ⇒ Integer

The <=> method is used to compare two ComponentDefinition objects for sorting. The comparison is done based on the component name.

Examples:

c1=Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
c2=Sketchup.find_support_file "Fence.skp",
  "Components/Components Sampler/"
if c1 <=> c2
  UI.messagebox("c1 sorts before c2")
end

Parameters:

Returns:

  • (Integer) —

    a -1 if component1 is less then component2. A 1 if component1 greater than component2

Version:

  • SketchUp 6.0



50
51
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 50

def <=>(compdef2)
end

#==(compdef2) ⇒ Boolean

The == method is used to test if two ComponentDefinition objects are the same (based on their address in memory).

Examples:

c1=Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
c2=Sketchup.find_support_file "Fence.skp",
  "Components/Components Sampler/"
if c1 == c2
  UI.messagebox("These definitions are the same.")
end

Parameters:

Returns:

  • (Boolean) —

    true if the ComponentDefinition objects are the same object. False if the objects are not the same.

Version:

  • SketchUp 6.0



72
73
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 72

def ==(compdef2)
end

#add_classification(schema_name, schema_type) ⇒ Boolean

The add_classification method is used to add a given classification to the component.

Note that you cannot classify image definitions.

Examples:

definition = Sketchup.active_model.definitions.first
success = definition.add_classification("IFC 2x3", "IfcDoor")

Parameters:

  • schema_name (String) —

    a String - Schema name to add

  • schema_type (String) —

    a String - Schema type to add

Returns:

  • (Boolean) —

    true if the classification succeeds. Otherwise false.

Version:

  • SketchUp 2015



93
94
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 93

def add_classification(schema_name, schema_type)
end

#add_observer(observer) ⇒ Boolean

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

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
status = componentdefinition.add_observer observer

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0



108
109
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 108

def add_observer(observer)
end

#behavior ⇒ Sketchup::Behavior

The behavior method is used to retrieve the Behavior object associated with a component definition.

Examples:

path = Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
model = Sketchup.active_model
definitions = model.definitions
componentdefinition = definitions.load path
behavior = componentdefinition.behavior

Returns:

Version:

  • SketchUp 6.0



125
126
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 125

def behavior
end

#count_instances ⇒ Integer

The count_instances method is used to count the number of unique component instances in a model using this component definition. This does not represent the total number of instances placed in the model as it doesn’t take into account instances inside unused definitions.

Examples:

path = Sketchup.find_support_file('Bed.skp',
  'Components/Components Sampler/')
definitions = Sketchup.active_model.definitions
definition = definitions.load(path)
number = definition.count_instances

Returns:

  • (Integer) —

    the number of component instances of this component definition (if successful)

Version:

  • SketchUp 6.0



144
145
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 144

def count_instances
end

#count_used_instances ⇒ Integer

The count_used_instances method is used to count the total number of component instances in a model using this component definition. This method takes into account the full hierarchy of the model.

Examples:

path = Sketchup.find_support_file('Bed.skp',
  'Components/Components Sampler/')
definitions = Sketchup.active_model.definitions
definition = definitions.load(path)
number = definition.count_used_instances

Returns:

  • (Integer) —

    the number of component instances of this component definition (if successful)

Version:

  • SketchUp 2016



162
163
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 162

def count_used_instances
end

#description ⇒ String

The description method is used to retrieve the description of the component definition.

Component definitions do not have a description, by default.

Examples:

# Get the description
componentdefinition = Sketchup.active_model.definitions[0]
description = componentdefinition.description

Returns:

  • (String) —

    the description of the component definition if successful

Version:

  • SketchUp 6.0



178
179
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 178

def description
end

#description=(description) ⇒ String

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

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
componentdefinition.description = "This is a traditional bed"
description = componentdefinition.description

Parameters:

Returns:

  • (String) —

    the description if successful, false if unsuccessful

Version:

  • SketchUp 6.0



195
196
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 195

def description=(description)
end

#entities ⇒ Sketchup::Entities

The entities method retrieves a collection of all the entities in the component definition

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
entities = componentdefinition.entities

Returns:

Version:

  • SketchUp 6.0



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

def entities
end

#get_classification_value(path) ⇒ Object?

The get_classification_value method is used to retrieve the value from a classification attribute given a key path.

Examples:

definition = Sketchup.active_model.definitions.first
definition.add_classification("IFC 2x3", "IfcDoor")

path = ["IFC 2x3", "IfcDoor", "ObjectType", "IfcLabel"]
value = definition.get_classification_value(path)

Parameters:

  • path (Array<String>) —

    An array composed of the key path to the value.

Returns:

  • (Object, nil) —

    a Ruby object if successful, nil otherwise.

Version:

  • SketchUp 2015



227
228
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 227

def get_classification_value(path)
end

#group? ⇒ Boolean

The group? method is used to determine if this component definition is used to hold the elements of a group.

Examples:

path = Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
model = Sketchup.active_model
definitions = model.definitions
componentdefinition = definitions.load path
status = componentdefinition.group?

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0



244
245
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 244

def group?
end

#guid ⇒ String

The guid method is used to retrieve the unique identifier of this component definition. The guid changes after the component definition is modified and the component edit is exited.

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
guid = componentdefinition.guid

Returns:

  • (String) —

    a string guid if successful

Version:

  • SketchUp 6.0



258
259
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 258

def guid
end

#hidden? ⇒ Boolean

The hidden method is used to determine if this component definition should be hidden on the component browser.

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
status = componentdefinition.hidden?

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0



271
272
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 271

def hidden?
end

#image? ⇒ Boolean

The image? method is used to determine if this component definition is used to define an image.

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
status = componentdefinition.image?
if (status)
  UI.messagebox "Component definition defines an image"
else
  UI.messagebox status.to_s
  UI.messagebox "Component definition does not define an image"
end

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0



290
291
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 290

def image?
end

#insertion_point ⇒ Geom::Point3d

Deprecated.

SketchUp 2020.0 removed the insertion point feature. The getter will always return the origin point and the setter becomes a no-op.

The insertion_point method is used to retrieve the Point3d object where the component was inserted.

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
point = componentdefinition.insertion_point

Returns:

  • (Geom::Point3d) —

    the Point3d where the component was inserted if successful. False if unsuccessful.

Version:

  • SketchUp 6.0



316
317
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 316

def insertion_point
end

#insertion_point=(point) ⇒ Geom::Point3d

Deprecated.

SketchUp 2020.0 removed the insertion point feature. The getter will always return the origin point and the setter becomes a no-op.

Sets the insertion point of your definition.

Examples:

point = Geom::Point3d.new(10, 20, 0)
componentdefinition = Sketchup.active_model.definitions[0]
componentdefinition.insertion_point = point

Parameters:

  • point (Geom::Point3d) —

    The Point3d object to use as the insertion point.

Returns:

  • (Geom::Point3d) —

    The Point3d object used as the insertion point.

Version:

  • SketchUp 6.0



337
338
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 337

def insertion_point=(point)
end

#instances ⇒ Array<Sketchup::ComponentInstance>

The instances method is used to return any array of ComponentInstancesfor this ComponentDefinition.

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
instances = componentdefinition.instances

Returns:

Version:

  • SketchUp 6.0



351
352
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 351

def instances
end

#internal? ⇒ Boolean

The internal? method is used to determine if the component definition is internal to the Component Browser

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
status = componentdefinition.internal?

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0



371
372
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 371

def internal?
end

#invalidate_bounds ⇒ Boolean

Invalidates the bounding box of your definition. This command forces the update of the bounding box of definition while inside an operation. See Model.start_operation for how to start an operation.

This method is useful if you make changes to your geometry using the Ruby API and then need to know your bounding box size. This method forces SketchUp to recalculate the definition’s bounding box when you choose.

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
componentdefinition.invalidate_bounds

Returns:

  • (Boolean) —

    true if successful

Version:

  • SketchUp 6.0



389
390
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 389

def invalidate_bounds
end

#live_component? ⇒ Boolean

Note:

These components are parametrically generated and API users should not modify them.

The #live_component? method is used to identify Live Components and sub-definitions of Live Components.

Examples:

Skipping Live Components

model = Sketchup.active_model
model.definitions.each { |definition|
  next if definition.live_component?
  puts definition.name
}

Returns:

  • (Boolean)

Version:

  • SketchUp 2021.0



408
409
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 408

def live_component?
end

#name ⇒ String

The name method retrieves the name of the component definition.

Examples:

path = Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
model = Sketchup.active_model
definitions = model.definitions
componentdefinition = definitions.load path
name = componentdefinition.name

Returns:

  • (String) —

    the component definition’s name if successful

Version:

  • SketchUp 6.0



424
425
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 424

def name
end

#name=(name) ⇒ String

The name= method is used to set the name of the component definition.

Examples:

path = Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
model = Sketchup.active_model
definitions = model.definitions
componentdefinition = definitions.load path
name = componentdefinition.name="Bed"

Parameters:

Returns:

  • (String) —

    the name assigned to the component definition if successful

Version:

  • SketchUp 6.0



443
444
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 443

def name=(name)
end

#path ⇒ String

The path method is used to retrieve the path where the component was loaded.

Examples:

path = Sketchup.find_support_file("Bed.skp", "Components/Components Sampler/")
model = Sketchup.active_model
definitions = model.definitions
componentdefinition = definitions.load(path)
path = componentdefinition.path

Returns:

  • (String) —

    Returns empty string if it is an internal component.

Version:

  • SketchUp 6.0



458
459
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 458

def path
end

#refresh_thumbnail ⇒ nil

The refresh_thumbnail method is used to force SketchUp to regenerate the thumbnail image that appears in the component browser. This is useful if you’ve used the API to change the geometry of your component and would like the thumbnail to match.

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
componentdefinition.refresh_thumbnail

Returns:

  • (nil)

Version:

  • SketchUp 7.0



473
474
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 473

def refresh_thumbnail
end

#remove_classification(schema_name, schema_type) ⇒ Boolean

The remove_classification method is used to remove a given classification from the component.

Note that you cannot classify image definitions.

Examples:

definition = Sketchup.active_model.definitions.first
success = definition.remove_classification("IFC 2x3", "IfcDoor")

Parameters:

  • schema_name (String) —

    Schema name to remove

  • schema_type (String) —

    Schema type to remove. If not provided or an empty string, the currently applied schema type for the given schema name will be removed.

Returns:

  • (Boolean) —

    true if the removal succeeds. Otherwise false.

Version:

  • SketchUp 2015



496
497
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 496

def remove_classification(schema_name, schema_type)
end

#remove_observer(observer) ⇒ Boolean

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

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
status = componentdefinition.remove_observer observer

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0



512
513
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 512

def remove_observer(observer)
end

#save_as(file_path) ⇒ Boolean

The save_as method is used to save your definition as a SketchUp file at the specified file destination.

Examples:

my_definition = Sketchup.active_model.definitions[0]
success = my_definition.save_as "c:\\myComponent.skp"

Parameters:

  • file_path (String) —

    Local file path to save the .skp file to.

Returns:

  • (Boolean) —

    true if successful

Version:

  • SketchUp 7.0



528
529
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 528

def save_as(file_path)
end

#save_thumbnail(filename) ⇒ Boolean

Saves a component thumbnail image. The image format is specified by the file extension of filePath. Supported image formats are bmp, jpg, png, tif, pct, and gif.

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
componentdefinition.save_thumbnail "test_thumb.png"

Parameters:

Returns:

  • (Boolean) —

    true if successful, false otherwise.

Version:

  • SketchUp 7.0



544
545
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 544

def save_thumbnail(filename)
end

#set_classification_value(path, value) ⇒ Boolean

The set_classification_value method is used to set the value of a classification attribute given a key path.

Examples:

definition = Sketchup.active_model.definitions.first
definition.add_classification("IFC 2x3", "IfcDoor")

path = ["IFC 2x3", "IfcDoor", "ObjectType", "IfcLabel"]
success = definition.set_classification_value(path, "Room 101")

Parameters:

  • path (Array<String>) —

    An array composed of the key path to the value.

  • value (Object) —

    A value valid for that specific attribute.

Returns:

  • (Boolean) —

    true if the path was valid, false otherwise.

Raises:

  • (NotImplementedError) —

    when trying to set the value of “choice” attributes.

  • (RuntimeError) —

    if the attributes being set are corrupt.

  • (TypeError) —

    when trying to set a value that is not valid for the attribute.

Version:

  • SketchUp 2015



574
575
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb', line 574

def set_classification_value(path, value)
end