Class: Sketchup::Materials

Relationships
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Entity`
Instance Chain: self, Enumerable, `Entity`
Inherits:	Sketchup::Entity Object Sketchup::Entity Sketchup::Materials

Overview

A collection of Materials objects. Each model contains a Materials collection that can be accessed via Model.materials.

Examples:

# Get a handle to all the materials in the current model.
model = Sketchup.active_model
materials = model.materials

Version:

SketchUp 6.0

Instance Attribute Summary

#current ⇒ Sketchup::Material rw

The current method is used to get the current material, i.e.
#current=(material) ⇒ Sketchup::Material rw

The current= method is used to set the current material.

`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

#[](index) ⇒ Sketchup::Material^?

The #[] method is used to retrieve a material by index or name.
#add(name) ⇒ Sketchup::Material

Add a new Material.
#add_observer(observer) ⇒ Boolean

The add_observer method is used to add an observer to the materials collection.
#[](index) ⇒ Sketchup::Material^?

The #[] method is used to retrieve a material by index or name.
#count ⇒ Integer
#each {|material| ... } ⇒ Sketchup::Materials

The #each method is used to iterate through all of the materials.
#length ⇒ Integer

The number of materials in the collection.
#load(filename) ⇒ Sketchup::Material

The #load method is used to load a material from file into the model.
#purge_unused ⇒ Sketchup::Materials

The purge_unused method is used to remove unused materials.
#remove(material) ⇒ Boolean

Remove a given material.
#remove_observer(observer) ⇒ Boolean

The remove_observer method is used to remove an observer from the materials collection.
#size ⇒ Integer

The number of materials in the collection.
#unique_name(name) ⇒ String

The #unique_name method is used to retrieve a unique name from the materials collection that is based on the provided one.

`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

#current ⇒ Sketchup::Material (rw)

The current method is used to get the current material, i.e. the material that the user has selected in the Materials dialog.

Examples:

current = Sketchup.active_model.materials.current

Returns:

(Sketchup::Material) —

a Material object.

Version:

SketchUp 6.0

#current=(material) ⇒ Sketchup::Material (rw)

The current= method is used to set the current material.

Examples:

# Make the first material in the model "current"
materials = Sketchup.active_model.materials
materials.current = materials[0]

Parameters:

material (Sketchup::Material) —

A Material object.

Version:

SketchUp 6.0

Instance Method Details

#[](index) ⇒ Sketchup::Material^? #[](name) ⇒ Sketchup::Material^?

The #[] method is used to retrieve a material by index or name.

The #at method is an alias of #[]

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials[0]

Overloads:

#[](index) ⇒ Sketchup::Material^?

A number representing the material’s index in an array of Material objects.
Parameters:
- index (Integer)
Returns:
- (Sketchup::Material, nil) —
  
  a Material object on success, Nil on failure
#[](name) ⇒ Sketchup::Material^?
Parameters:
- name (String) —
  
  The name of the material.
Returns:
- (Sketchup::Material, nil) —
  
  a Material object on success, Nil on failure

Version:

SketchUp 6.0

#add(name) ⇒ Sketchup::Material

Add a new Material. When called with no arguments, this will generate a new unique name for the new Material. If a name is given, it will check to see if there is already a material with that name. If there is already a material with the given name, then a new unique name is generated using the given name as a base.

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials.add('Joe')

Parameters:

name (String) —

The name of the new material.

Returns:

(Sketchup::Material) —

a Material object

Version:

SketchUp 6.0

#add_observer(observer) ⇒ `Boolean`

The add_observer method is used to add an observer to the materials collection.

Examples:

materials = Sketchup.active_model.materials
status = materials.add_observer(observer)

Parameters:

observer (Object) —

An observer.

Returns:

(Boolean) —

true if successful, false if unsuccessful.

Version:

SketchUp 6.0

#[](index) ⇒ Sketchup::Material^? #[](name) ⇒ Sketchup::Material^?

The #[] method is used to retrieve a material by index or name.

The #at method is an alias of #[]

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials[0]

Overloads:

#[](index) ⇒ Sketchup::Material^?

A number representing the material’s index in an array of Material objects.
Parameters:
- index (Integer)
Returns:
- (Sketchup::Material, nil) —
  
  a Material object on success, Nil on failure
#[](name) ⇒ Sketchup::Material^?
Parameters:
- name (String) —
  
  The name of the material.
Returns:
- (Sketchup::Material, nil) —
  
  a Material object on success, Nil on failure

Version:

SketchUp 6.0

#count ⇒ `Integer`

Note:

Since SketchUp 2014 the count method is inherited from Ruby’s Enumerable mix-in module. Prior to that the #count method is an alias for #length.

Examples:

materials = Sketchup.active_model.materials
count = materials.count

#each {|material| ... } ⇒ `Materials`

Note:

Don’t remove content from this collection while iterating over it with #each. This would change the size of the collection and cause elements to be skipped as the indices change. Instead copy the current collection to an array using to_a and then use each on the array, when removing content.

The #each method is used to iterate through all of the materials.

Examples:

model = Sketchup.active_model
model.materials.each { |material|
  puts material.display_name
}

Yield Parameters:

material (Sketchup::Material)

Version:

SketchUp 6.0

#length ⇒ `Integer`

Note:

The returned number includes Image materials as well. It will not reflect the number of materials yielded by #each. To get the number of non-image materials use #count or materials.to_a.size.

The number of materials in the collection.

Examples:

materials = Sketchup.active_model.materials
number = materials.length

#load(filename) ⇒ Sketchup::Material

The #load method is used to load a material from file into the model.

If a matching material exist in the model it will be returned instead.

Examples:

# Load a material from the shipped SketchUp library.
materials_template = Sketchup.find_support_file('Materials/MaterialTemplate.skp')
if materials_template && File.exist?(materials_template)
  # Newer SketchUp versions.
  materials_path = File.dirname(materials_template)
  files = Dir.glob(File.join(materials_path, '**', '*.skm'))
  path = files.first
else
  # Older SketchUp versions.
  filename = 'Materials/Brick, Cladding and Siding/Cinder Block.skm'
  path = Sketchup.find_support_file(filename)
end
materials = Sketchup.active_model.materials
material = materials.load(path)

Parameters:

filename (String) —

the path to the SKM file to load.

Returns:

(Sketchup::Material) —

the new loaded material, or existing material.

Raises:

(RuntimeError) —

if the material failed to load.

Version:

SketchUp 2017

#purge_unused ⇒ `Materials`

The purge_unused method is used to remove unused materials.

Examples:

materials = Sketchup.active_model.materials
materials.purge_unused

Returns:

(Materials) —

The Materials object.

Version:

SketchUp 6.0

#remove(material) ⇒ `Boolean`

Remove a given material.

Examples:

Logic for removing a given material of an entity:

# @param [Sketchup::Entity] entity
# @param [Sketchup::Material] material_to_remove
def remove_material(entity, material_to_remove)
  if entity.respond_to?(:material) do
    if entity.material.equal?(material_to_remove) do
      entity.material = nil
    end
  end
  # for entities that have a back material
  if entity.respond_to?(:back_material) do
    if entity.back_material.equal?(material_to_remove) do
      entity.back_material = nil
    end
  end
end

model = Sketchup.active_model
materials = model.materials
material = materials.add('Joe')
materials.remove(material)

Parameters:

material (Sketchup::Material) —

The material to remove.

Returns:

(Boolean) —

true if successful, false if unsuccessful.

Version:

SketchUp 8.0 M1

#remove_observer(observer) ⇒ `Boolean`

The remove_observer method is used to remove an observer from the materials collection.

Examples:

materials = Sketchup.active_model.materials
status = materials.remove_observer(observer)

Parameters:

observer (Object) —

An observer.

Returns:

(Boolean) —

true if successful, false if unsuccessful.

Version:

SketchUp 6.0

#size ⇒ `Integer`

Note:

The returned number includes Image materials as well. It will not reflect the number of materials yielded by #each. To get the number of non-image materials use #count or materials.to_a.size.

The number of materials in the collection.

The #size method is an alias for #length.

Examples:

materials = Sketchup.active_model.materials
number = materials.size

#unique_name(name) ⇒ String

The #unique_name method is used to retrieve a unique name from the materials collection that is based on the provided one. If provided name is unique it will be returned, otherwise any trailing indices will be replaced by a new index.

Examples:

materials = Sketchup.active_model.materials
unique_name = materials.unique_name("test_name")

Parameters:

name (String) —

the suggested name.

Returns:

(String) —

a unique name.

Version:

SketchUp 2018

Class: Sketchup::Materials

Overview

Instance Attribute Summary

Entity - Inherited

Instance Method Summary

Entity - Inherited

Instance Attribute Details

#current ⇒ Sketchup::Material (rw)

#current=(material) ⇒ Sketchup::Material (rw)

Instance Method Details

#[](index) ⇒ Sketchup::Material? #[](name) ⇒ Sketchup::Material?

#add(name) ⇒ Sketchup::Material

#add_observer(observer) ⇒ Boolean

#[](index) ⇒ Sketchup::Material? #[](name) ⇒ Sketchup::Material?

#count ⇒ Integer

#each {|material| ... } ⇒ Materials

#length ⇒ Integer

#load(filename) ⇒ Sketchup::Material

#purge_unused ⇒ Materials

#remove(material) ⇒ Boolean

#remove_observer(observer) ⇒ Boolean

#size ⇒ Integer

#unique_name(name) ⇒ String

`Entity` - Inherited

`Entity` - Inherited

#[](index) ⇒ Sketchup::Material^? #[](name) ⇒ Sketchup::Material^?

#add_observer(observer) ⇒ `Boolean`

#[](index) ⇒ Sketchup::Material^? #[](name) ⇒ Sketchup::Material^?

#count ⇒ `Integer`

#each {|material| ... } ⇒ `Materials`

#length ⇒ `Integer`

#purge_unused ⇒ `Materials`

#remove(material) ⇒ `Boolean`

#remove_observer(observer) ⇒ `Boolean`

#size ⇒ `Integer`