Class: Sketchup::Entity

Inherits:
Object
  • Object
show all
Defined in:
lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb

Overview

This is the base class for all SketchUp entities. Entities are basically anything that can be contained in a model, including Drawingelements such as Edges, SectionPlanes, Groups, etc. and entities that relate to those Drawingelements, such as Loops, Layers, etc.

Keep in mind that the methods below are available on all subclasses. For example, an Edge’s parent class is Drawingelement, and a Drawingelement’s parent class is Entity. Therefore an Edge has all of the methods defined in Drawingelement and Entity.

The Object.is_a? method is the common way of determining what sort of Entity you’re dealing with.

Examples:

# Count how many faces are in the current selection.
selection = Sketchup.active_model.selection
face_count = 0

# Look at all of the entities in the selection.
selection.each { |entity|
  if entity.is_a? Sketchup::Face
    face_count = face_count + 1
  end
}

UI.messagebox("There are " + face_count.to_s + " faces selected.")

Version:

  • SketchUp 6.0

Instance Method Summary collapse

Instance Method Details

#add_observer(observer) ⇒ Boolean

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

Examples:

entity = Sketchup.active_model.entities[0]
if entity.valid?
  status = entity.add_observer observer
end

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0



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

def add_observer(observer)
end

#attribute_dictionaries ⇒ Sketchup::AttributeDictionaries?

Note:

The return value may be either nil or an empty AttributeDictionaries collection if this entity has no AttributeDictionarys.

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

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
status = entity1.set_attribute "testdictionary", "test", 115
attrdicts = entity1.attribute_dictionaries

Returns:

Version:

  • SketchUp 6.0



83
84
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 83

def attribute_dictionaries
end

#attribute_dictionary(name, create = false) ⇒ Sketchup::AttributeDictionary?

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

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
status = entity1.set_attribute "testdictionary", "test", 115
attrdict = entity1.attribute_dictionary "testdictionary"

Parameters:

  • name (String) —

    The name of the attribute dictionary.

  • create (Boolean) (defaults to: false) —

    boolean, if set to true then the attribute dictionary will be created if it does not exist.

Returns:

Version:

  • SketchUp 6.0



120
121
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 120

def attribute_dictionary(name, create = false)
end

#delete_attribute(dictionary_name) ⇒ Boolean #delete_attribute(dictionary_name, key) ⇒ Boolean

Note:

In SketchUp 2018, special attribute dictionaries have been added. The name of these dictionaries are “SU_InstanceSet” and “SU_DefinitionSet”. The dictionaries cannot be deleted via ruby and an ArgumentError will be raised. The key/value pairs in the dictionary can be deleted safely.

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

If only the dictionary_name is given, then it deletes the entire AttributeDictionary. Otherwise, #delete_attribute deletes the attribute with the given key from the given dictionary.

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
status = entity1.set_attribute "testdictionary", "test", 115
status = entity1.delete_attribute "testdictionary"

Overloads:

  • #delete_attribute(dictionary_name) ⇒ Boolean

    Parameters:

    • dictionary_name (String) —

      The name of an attribute dictionary.

    Returns:

    • (Boolean)
  • #delete_attribute(dictionary_name, key) ⇒ Boolean

    Parameters:

    • dictionary_name (String) —

      The name of an attribute dictionary.

    • key (String) —

      An attribute key.

    Returns:

    • (Boolean)

Version:

  • SketchUp 6.0



167
168
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 167

def delete_attribute(*args)
end

#deleted? ⇒ Boolean

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

Examples:

depth = 100
width = 100
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
entity1 = entities[1]
status = entity1.deleted?

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0



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

def deleted?
end

#entityID ⇒ Integer

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

The entityID is not persistent between sessions.

Examples:

depth = 100
width = 100
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
entity1 = entities[1]
id = entity1.entityID

Returns:

  • (Integer) —

    the id for the Entity object

Version:

  • SketchUp 6.0



218
219
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 218

def entityID
end

#get_attribute(dict_name, key, default_value = nil) ⇒ Object

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

If the third parameter, default_value, is not passed and there is no attribute that matches the given name, it returns nil.

If default_value is provided and there is no matching attribute it returns the given value. It does not create an attribute with that name though.

Examples:

# Add an entity to the model:
model = Sketchup.active_model
entities = model.active_entities
edge = entities.add_line([0, 0, 0], [9, 9, 9])

# Read an attribute value from the edge. In this case this will return the
# default value provided; 42.
value = edge.get_attribute("MyExtension", "MyProperty", 42)

Parameters:

  • dict_name (String) —

    The name of an attribute dictionary.

  • key (String) —

    An attribute key.

  • default_value (Object) (defaults to: nil) —

    A default value to return if no attribute is found.

Returns:

  • (Object) —

    the retrieved value

Version:

  • SketchUp 6.0



252
253
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 252

def get_attribute(dict_name, key, default_value = nil)
end

#inspect ⇒ String

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

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
st = entity1.to_s

Returns:

  • (String) —

    the string representation of the entity if successful

Version:

  • SketchUp 6.0



280
281
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 280

def inspect
end

#model ⇒ Sketchup::Model

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

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
m = entity1.model

Returns:

Version:

  • SketchUp 6.0



307
308
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 307

def model
end

#parent ⇒ Sketchup::ComponentDefinition, Sketchup::Model

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

The parent will be a ComponentDefinition, a Group, or a Model, whatever the entity is contained within.

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
parent = entity1.parent

Returns:

Version:

  • SketchUp 6.0



338
339
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 338

def parent
end

#persistent_id ⇒ Integer

Note:

Only a subset of entity types support PIDs. Refer to the table below for which and when support was added. In general it is entities that you can iterate over in a Sketchup::Entities collection.

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

The persistent id persistent between sessions.

SketchUp 2020.1
SketchUp 2020.0
SketchUp 2018
SketchUp 2017

Examples:

model = Sketchup.active_model
entities = model.active_entities
pts = [
  Geom::Point3d.new(0, 0, 0),
  Geom::Point3d.new(9, 0, 0),
  Geom::Point3d.new(9, 9, 0),
  Geom::Point3d.new(0, 9, 0),
]

# Add the face to the entities in the model
group = entities.add_group
face = group.entities.add_face(pts)
pid = face.persistent_id
# Exploding the group will preserve the pid.
pid == face.persistent_id # Should return true

Returns:

Version:

  • SketchUp 2017



396
397
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 396

def persistent_id
end

#remove_observer(observer) ⇒ Boolean

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

Examples:

entity = Sketchup.active_model.entities[0]
if entity.valid?
  status = entity.remove_observer observer
end

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0



414
415
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 414

def remove_observer(observer)
end

#set_attribute(dict_name, key, value) ⇒ Object

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

This method will create a new AttributeDictionary if none exists.

Note, a bug prior to SketchUp 2015 would corrupt the model if the key is an empty string. This also includes values that will evaluate to empty strings, such as nil.

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
status = entity1.set_attribute "testdictionary", "test", 115

Parameters:

  • dict_name (String) —

    The name of an attribute dictionary.

  • key (String) —

    An attribute key.

  • value (Object) —

    The value for the attribute.

Returns:

  • (Object) —

    the newly set value if successful

Version:

  • SketchUp 6.0



457
458
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 457

def set_attribute(dict_name, key, value)
end

#to_s ⇒ String

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

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
st = entity1.to_s

Returns:

  • (String) —

    the string representation of the entity if successful

Version:

  • SketchUp 6.0



485
486
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 485

def to_s
end

#typename ⇒ String

Note:

Prefer is_a? over typename when possible as it is faster.

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

Examples:

depth = 100
width = 100
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

# I just happen to know that the second and third entities in the
# entities objects are edges.
entity1 = entities[1]
type = entity1.typename

Returns:

  • (String) —

    the type of the entity

Version:

  • SketchUp 6.0



515
516
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 515

def typename
end

#valid? ⇒ Boolean

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

This method is functionally the inverse to the #deleted? method.

Examples:

depth = 100
width = 100
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
entity1 = entities[1]
status = entity1.valid?

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0



542
543
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb', line 542

def valid?
end