Class: Sketchup::ComponentDefinition

Relationships
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Drawingelement`, `Entity`
Instance Chain: self, Comparable, `Drawingelement`, `Entity`
Inherits:	Sketchup::Drawingelement Object Sketchup::Entity Sketchup::Drawingelement Sketchup::ComponentDefinition

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 Attribute Summary

#description ⇒ String rw

The description method is used to retrieve the description of the component definition.
#description=(description) ⇒ String rw

The description= method is used to set the description for the component definition.
#group? ⇒ Boolean readonly

The group? method is used to determine if this component definition is used to hold the elements of a group.
#hidden? ⇒ Boolean readonly

The #hidden? method is used to determine if this component definition is hidden in the component browser.
#image? ⇒ Boolean readonly

The image? method is used to determine if this component definition is used to define an image.
#insertion_point ⇒ Geom::Point3d rw deprecated Deprecated.
SketchUp 2020.0 removed the insertion point feature. The getter will always return the origin point and the setter becomes a no-op.
#insertion_point=(point) ⇒ Geom::Point3d rw deprecated Deprecated.
SketchUp 2020.0 removed the insertion point feature. The getter will always return the origin point and the setter becomes a no-op.
#internal? ⇒ Boolean readonly

The internal? method is used to determine if the component definition is internal to the Component Browser.
#live_component? ⇒ Boolean readonly

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

The manifold? method is used to determine if a component definition is manifold.
#name ⇒ String rw

The name method retrieves the name of the component definition.
#name=(name) ⇒ String rw

The #name= method is used to set the name of the component definition.
#procedural? ⇒ Boolean readonly

Returns whether this component definition is procedural.
#thumbnail_camera ⇒ Sketchup::Camera rw

The #thumbnail_camera method is used to retrieve a camera representing the thumbnail associated with the component definition.
#thumbnail_camera=(camera) rw

The #thumbnail_camera= method is used to set the camera for the thumbnail associated with the component definition.

`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 checks if a `Drawingelement` object is not explicitly hidden (i.e. its hidden property is false).

`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

#<=>(compdef2) ⇒ Integer

The <=> method is used to compare two ComponentDefinition objects for sorting.
#==(compdef2) ⇒ Boolean

The == method is used to test if two ComponentDefinition objects are the same (based on their address in memory).
#add_classification(schema_name, schema_type) ⇒ Boolean

The add_classification method is used to add a given classification to the component.
#add_observer(observer) ⇒ Boolean

The add_observer method is used to add an observer to the current object.
#attach_procedure(procedure, parameters) ⇒ nil

Attaches a procedure to this component definition, making it a procedural component if the procedure is valid for the component's input geometry.
#behavior ⇒ Sketchup::Behavior

The behavior method is used to retrieve the Behavior object associated with a component definition.
#control_entities ⇒ Sketchup::Entities

For a Procedural Component, retrieves a collection of control (input) elements.
#count_instances ⇒ Integer

The count_instances method is used to count the number of unique component instances in a model using this component definition.
#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.
#entities ⇒ Sketchup::Entities

The entities method retrieves a collection of all the entities in the component definition.
#get_classification_value(path) ⇒ Object^?

The get_classification_value method is used to retrieve the value from a classification attribute given a key path.
#get_procedure_parameters ⇒ Hash{Symbol => Integer, Float, String, Boolean}

Returns the parameters of the procedure attached to this procedural component definition.
#guid ⇒ String

The guid method is used to retrieve the unique identifier of this component definition.
#instances ⇒ Array<Sketchup::ComponentInstance>

The instances method is used to return any array of ComponentInstancesfor this ComponentDefinition.
#invalidate_bounds ⇒ Boolean

Invalidates the bounding box of your definition.
#load_time ⇒ Time

The #load_time method gets the load time of the component definition.
#make_non_procedural(retained_geometry) ⇒ nil

Makes this procedural component definition a regular, non-procedural definition.
#path ⇒ String

The path method is used to retrieve the path where the component was loaded.
#refresh_thumbnail ⇒ nil

The refresh_thumbnail method is used to force SketchUp to regenerate the thumbnail image that appears in the component browser.
#remove_classification(schema_name, schema_type) ⇒ Boolean

The remove_classification method is used to remove a given classification from the component.
#remove_observer(observer) ⇒ Boolean

The remove_observer method is used to remove an observer from the current object.
#run_procedures(mode) ⇒ Object

Runs the procedures attached to this procedural component definition, regenerating its output geometry.
#save_as(file_path) ⇒ Boolean

The #save_as method is used to save your definition as a SketchUp file at the specified file destination.
#save_copy(file_path) ⇒ Boolean

The #save_copy method is used to save your definition as a SketchUp file without changing the file path it is already associated with.
#save_thumbnail(filename) ⇒ Boolean

Saves a component thumbnail image.
#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.
#set_procedure_parameters(parameters)

Sets the parameters for the procedure attached to this procedural component definition.

`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

#description ⇒ String (rw)

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

#description=(description) ⇒ String (rw)

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:

description (String)

Returns:

(String) —
the description if successful, false if unsuccessful

Version:

SketchUp 6.0

#group? ⇒ `Boolean` (readonly)

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?

Version:

SketchUp 6.0

#hidden? ⇒ `Boolean` (readonly)

The #hidden? method is used to determine if this component definition is hidden in the component browser.

This is based on how its instances are placed in the model hierarchy. For more details, see this article.

In addition, component definitions used by Groups and Images are always hidden in the Component Browser. See #group? and #image?.

Examples:

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

Version:

SketchUp 6.0

#image? ⇒ `Boolean` (readonly)

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?

Version:

SketchUp 6.0

#insertion_point ⇒ Geom::Point3d (rw)

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

#insertion_point=(point) ⇒ Geom::Point3d (rw)

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

#internal? ⇒ `Boolean` (readonly)

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?

Version:

SketchUp 6.0

#live_component? ⇒ `Boolean` (readonly)

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
}

Version:

SketchUp 2021.0

#manifold? ⇒ `Boolean` (readonly)

The manifold? method is used to determine if a component definition is manifold.

A manifold definition is one where all edges are shared by exactly two faces, and there are no holes or singularities. This allows checking if a definition represents a closed solid without needing to create an instance.

Examples:

definition = Sketchup.active_model.definitions.add("Box")
face = definition.entities.add_face([0,0,0], [10,0,0], [10,10,0], [0,10,0])
face.pushpull(-10)
status = definition.manifold?

Version:

SketchUp 2026.2

#name ⇒ String (rw)

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

#name=(name) ⇒ String (rw)

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

The name should be unique to the model, if it's not the name will automatically be made unique.

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:

name (String)

Version:

SketchUp 6.0

#procedural? ⇒ `Boolean` (readonly)

Returns whether this component definition is procedural.

Examples:

definition = Sketchup.active_model.definitions[0]
is_procedural = definition.procedural?

Version:

SketchUp 2027.0

#thumbnail_camera ⇒ Sketchup::Camera (rw)

The #thumbnail_camera method is used to retrieve a camera representing the thumbnail associated with the component definition.

Examples:

# Get the thumbnail camera
componentdefinition = Sketchup.active_model.definitions[0]
thumbnail_camera = componentdefinition.thumbnail_camera

Returns:

(Sketchup::Camera) —
the camera associated with the thumbnail.

Version:

SketchUp 2023.0

#thumbnail_camera=(camera) (rw)

The #thumbnail_camera= method is used to set the camera for the thumbnail associated with the component definition.

Examples:

componentdefinition = Sketchup.active_model.definitions[0]
eye = Geom::Point3d.new(20, 5, 30)
target = Geom::Point3d.new(20, 60, 25)
up = Z_AXIS
camera = Sketchup::Camera.new(eye, target, up)
# Assign camera to the thumbnail's camera and refresh.
componentdefinition.thumbnail_camera = camera
componentdefinition.refresh_thumbnail

Parameters:

camera (Sketchup::Camera)

Raises:

(TypeError) —
if the passed argument is not of #Sketchup::Camera type.

Version:

SketchUp 2023.0

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:

definitions = Sketchup.active_model.definitions
# Sort the definitions by name using the <=> operator.
sorted_list = definitions.sort { |a, b| a <=> b }
# This is the same as using sort_by:
sorted_list = definitions.sort_by(&:name)
sorted_list.each { |definition| puts definition.name }

Parameters:

compdef2 (ComponentDefinition) —
The second component definition in the comparison.

Returns:

(Integer) —
a -1 if component1 is less then component2. A 1 if component1 greater than component2

Version:

SketchUp 6.0

#==(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/"
c1 == c2

Parameters:

compdef2 (ComponentDefinition) —
The second component definition in the comparison.

Returns:

(Boolean) —
true if the ComponentDefinition objects are the same object. False if the objects are not the same.

Version:

SketchUp 6.0

#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

#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

#attach_procedure(procedure, parameters) ⇒ `nil` #attach_procedure(procedure_id, parameters) ⇒ `nil`

Attaches a procedure to this component definition, making it a procedural component if the procedure is valid for the component's input geometry.

The definition must not already be procedural. Make it non-procedural with #make_non_procedural before attaching a different procedure.

Examples:

definition = Sketchup.active_model.definitions[0]
my_proc = MyModule::MyProcedure.new
Sketchup.register_procedure(my_proc)
definition.attach_procedure(my_proc, { count: 5, spacing: 10.0 })

Attaching a native procedure by ID

definition = Sketchup.active_model.definitions[0]
definition.attach_procedure(Sketchup::PROCEDURE_ID_FOLLOW_ME, {})

Overloads:

#attach_procedure(procedure, parameters) ⇒ nil
Parameters:
- procedure (Sketchup::Procedure) —
  Procedure to be attached.
- parameters (Hash{Symbol, String => Integer, Float, String, Boolean}) —
  A hash of parameter identifier symbols/strings to values. Pass in an empty hash if the procedure does not need any parameters. The parameter identifiers (hash keys) must match those declared in the procedure's Procedure#declare_params_and_ui method.
#attach_procedure(procedure_id, parameters) ⇒ nil
Parameters:
- procedure_id (String) —
  The ID of a registered procedure. Use one of the Sketchup::PROCEDURE_ID_* constants to target a native procedure (for example PROCEDURE_ID_FOLLOW_ME).
- parameters (Hash{Symbol, String => Integer, Float, String, Boolean})

Raises:

(TypeError) —
If this is a group or image definition.
(TypeError) —
If this definition is already procedural.
(TypeError) —
If parameters is not a Hash.
(TypeError) —
If a parameter value has an unsupported type.
(TypeError) —
If the first argument is neither a Procedure nor a ::String.
(ArgumentError) —
If a ::String procedure ID is given but no procedure with that ID is registered.
(ArgumentError) —
If the procedure cannot be attached to this definition most likely due to input geometry being invalid for the procedure.

See Also:

Version:

SketchUp 2027.0

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

(Sketchup::Behavior) —
a Behavior object if successful

Version:

SketchUp 6.0

#control_entities ⇒ Sketchup::Entities

For a Procedural Component, retrieves a collection of control (input) elements.

Examples:

definition = Sketchup.active_model.definitions[0]
entities = definition.control_entities if definition.procedural?

Raises:

(TypeError) —
if this definition is not procedural.

Version:

SketchUp 2027.0

#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

#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

#entities ⇒ Sketchup::Entities

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

SketchUp 2027.0 and later: For a Procedural Component, this will return the output entities. Extension code should not directly modify these entities as they are managed by the procedure. Use #control_entities to access the control (input) entities of a Procedural Component.

Examples:

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

Returns:

(Sketchup::Entities) —
an Entities object if successful

Version:

SketchUp 6.0

#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

#get_procedure_parameters ⇒ `Hash`{`Symbol` => `Integer`, `Float`, String, `Boolean`}

Returns the parameters of the procedure attached to this procedural component definition.

Examples:

definition = Sketchup.active_model.definitions[0]
# Assuming the definition is procedural and has a procedure attached
parameters = definition.get_procedure_parameters
# => { count: 5, spacing: 10.0 }

Returns:

(Hash{Symbol => Integer, Float, String, Boolean}) —
A hash of parameter identifier symbols to their current values. Returns an empty hash if the procedure declares no parameters or is not registered in the current session.

Raises:

(TypeError) —
If this definition is not procedural.

See Also:

Version:

SketchUp 2027.0

#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

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

(Array<Sketchup::ComponentInstance>) —
an array of ComponentInstances (if successful)

Version:

SketchUp 6.0

#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

#load_time ⇒ `Time`

The #load_time method gets the load time of the component definition. For an internal component definition, this is the time that it was created. For an external component definition, this is the time that it was added to the model.

Examples:

model = Sketchup.active_model
definition = model.definitions.first
definition.load_time

Version:

SketchUp 2025.0

#make_non_procedural(retained_geometry) ⇒ `nil`

Makes this procedural component definition a regular, non-procedural definition. The procedure is detached and the definition keeps either the procedural output geometry or the control (input) geometry, as specified by retained_geometry.

If :keep_output is requested but the procedural output is empty (for example because the procedure errored), the control (input) geometry is retained instead.

Examples:

Detach a component whose procedure's extension is not installed

definition = Sketchup.active_model.definitions[0]
definition.make_non_procedural(:keep_output) if definition.procedural?

Keep the control (input) geometry

definition.make_non_procedural(:keep_input)

Parameters:

retained_geometry (Symbol) —
Either :keep_output to keep the procedural output geometry, or :keep_input to keep the control (input) geometry.

Raises:

(TypeError) —
If this definition is not procedural.
(TypeError) —
If retained_geometry is not a Symbol.
(ArgumentError) —
If retained_geometry is not :keep_output or :keep_input.

See Also:

#attach_procedure

Version:

SketchUp 2027.0

#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

#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

Version:

SketchUp 7.0

#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

#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

#run_procedures(mode) ⇒ `Object`

Runs the procedures attached to this procedural component definition, regenerating its output geometry.

By default, procedures run only if the component has been marked as modified (its control geometry changed or its procedures/parameters were updated). Pass :force to run the procedures unconditionally.

Examples:

definition = Sketchup.active_model.definitions[0]
definition.run_procedures           # run only if needed
definition.run_procedures(:force)   # always run

Parameters:

mode (Symbol) —
Either :if_modified (default) or :force.

Returns:

Raises:

(TypeError) —
If this definition is not procedural.
(ArgumentError) —
If mode is not :if_modified or :force.

Version:

SketchUp 2027.0

#save_as(file_path) ⇒ `Boolean` #save_as(file_path, version) ⇒ `Boolean`

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

Use this method when the user has chosen a path. If you want to "silently" save out the definition, without changing the path it is associated with, use #save_copy instead.

Examples:

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

Overloads:

#save_as(file_path) ⇒ Boolean

Save as the current SketchUp version.
Parameters:
- file_path (String)
Version:
- SketchUp 7.0
#save_as(file_path, version) ⇒ Boolean

Save as a specific SketchUp version.
Parameters:
- file_path (String)
- version (Integer) —
  See Model#save for supported values.
Version:
- SketchUp 2022.0

Returns:

(Boolean) —
true if successful, false otherwise

#save_copy(file_path) ⇒ `Boolean` #save_copy(file_path, version) ⇒ `Boolean`

The #save_copy method is used to save your definition as a SketchUp file without changing the file path it is already associated with.

This can be used to save out to a temporary file used by some other process, without having the temporary path permanentely written to the SketchUp model.

Examples:

my_definition = Sketchup.active_model.definitions[0]
my_definition.save_copy("c:\\myComponent.skp")

Overloads:

#save_copy(file_path) ⇒ Boolean

Save as the current SketchUp version.
Parameters:
- file_path (String)
#save_copy(file_path, version) ⇒ Boolean

Save as a specific SketchUp version.
Parameters:
- file_path (String)
- version (Integer) —
  See Model#save for supported values.

Returns:

(Boolean) —
true if successful

Version:

SketchUp 2022.0

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

filename (String)

Returns:

(Boolean) —
true if successful, false otherwise.

Version:

SketchUp 7.0

#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

#set_procedure_parameters(parameters)

Sets the parameters for the procedure attached to this procedural component definition. The component's output geometry will be regenerated with the new parameters.

Examples:

definition = Sketchup.active_model.definitions[0]
# Assuming the definition is procedural and has a procedure attached
definition.set_procedure_parameters(count: 5, spacing: 10.0)

Parameters:

parameters (Hash{Symbol, String => Integer, Float, String, Boolean}) —
A hash of parameter identifier symbols/strings to values. The parameter identifiers (hash keys) must match those declared in the procedure's Procedure#declare_params_and_ui method.

Raises:

(TypeError) —
If this definition is not procedural.
(ArgumentError) —
If the parameters are invalid for the attached procedure.

See Also:

Version:

SketchUp 2027.0

Class: Sketchup::ComponentDefinition

Overview

Instance Attribute Summary

Drawingelement - Inherited

Entity - Inherited

Instance Method Summary

Drawingelement - Inherited

Entity - Inherited

Instance Attribute Details

#description ⇒ String (rw)

#description=(description) ⇒ String (rw)

#group? ⇒ Boolean (readonly)

#hidden? ⇒ Boolean (readonly)

#image? ⇒ Boolean (readonly)

#insertion_point ⇒ Geom::Point3d (rw)

#insertion_point=(point) ⇒ Geom::Point3d (rw)

#internal? ⇒ Boolean (readonly)

#live_component? ⇒ Boolean (readonly)

#manifold? ⇒ Boolean (readonly)

#name ⇒ String (rw)

#name=(name) ⇒ String (rw)

#procedural? ⇒ Boolean (readonly)

#thumbnail_camera ⇒ Sketchup::Camera (rw)

#thumbnail_camera=(camera) (rw)

Instance Method Details

#<=>(compdef2) ⇒ Integer

#==(compdef2) ⇒ Boolean

#add_classification(schema_name, schema_type) ⇒ Boolean

#add_observer(observer) ⇒ Boolean

#attach_procedure(procedure, parameters) ⇒ nil #attach_procedure(procedure_id, parameters) ⇒ nil

#behavior ⇒ Sketchup::Behavior

#control_entities ⇒ Sketchup::Entities

#count_instances ⇒ Integer

#count_used_instances ⇒ Integer

#entities ⇒ Sketchup::Entities

#get_classification_value(path) ⇒ Object?

#get_procedure_parameters ⇒ Hash{Symbol => Integer, Float, String, Boolean}

#guid ⇒ String

#instances ⇒ Array<Sketchup::ComponentInstance>

#invalidate_bounds ⇒ Boolean

#load_time ⇒ Time

#make_non_procedural(retained_geometry) ⇒ nil

#path ⇒ String

#refresh_thumbnail ⇒ nil

#remove_classification(schema_name, schema_type) ⇒ Boolean

#remove_observer(observer) ⇒ Boolean

#run_procedures(mode) ⇒ Object

#save_as(file_path) ⇒ Boolean #save_as(file_path, version) ⇒ Boolean

#save_copy(file_path) ⇒ Boolean #save_copy(file_path, version) ⇒ Boolean

#save_thumbnail(filename) ⇒ Boolean

#set_classification_value(path, value) ⇒ Boolean

#set_procedure_parameters(parameters)

`Drawingelement` - Inherited

`Entity` - Inherited

`Drawingelement` - Inherited

`Entity` - Inherited

#group? ⇒ `Boolean` (readonly)

#hidden? ⇒ `Boolean` (readonly)

#image? ⇒ `Boolean` (readonly)

#internal? ⇒ `Boolean` (readonly)

#live_component? ⇒ `Boolean` (readonly)

#manifold? ⇒ `Boolean` (readonly)

#procedural? ⇒ `Boolean` (readonly)

#<=>(compdef2) ⇒ `Integer`

#==(compdef2) ⇒ `Boolean`

#add_classification(schema_name, schema_type) ⇒ `Boolean`

#add_observer(observer) ⇒ `Boolean`

#attach_procedure(procedure, parameters) ⇒ `nil` #attach_procedure(procedure_id, parameters) ⇒ `nil`

#count_instances ⇒ `Integer`

#count_used_instances ⇒ `Integer`

#get_classification_value(path) ⇒ `Object`^?

#get_procedure_parameters ⇒ `Hash`{`Symbol` => `Integer`, `Float`, String, `Boolean`}

#invalidate_bounds ⇒ `Boolean`

#load_time ⇒ `Time`

#make_non_procedural(retained_geometry) ⇒ `nil`

#refresh_thumbnail ⇒ `nil`

#remove_classification(schema_name, schema_type) ⇒ `Boolean`

#remove_observer(observer) ⇒ `Boolean`

#run_procedures(mode) ⇒ `Object`

#save_as(file_path) ⇒ `Boolean` #save_as(file_path, version) ⇒ `Boolean`

#save_copy(file_path) ⇒ `Boolean` #save_copy(file_path, version) ⇒ `Boolean`

#save_thumbnail(filename) ⇒ `Boolean`

#set_classification_value(path, value) ⇒ `Boolean`