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| ... } ⇒ nil

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| ... } ⇒ `nil`

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. (SketchUp 2016)
filename = 'Materials/Brick, Cladding and Siding/Cinder Block.skm'
path = Sketchup.find_support_file(filename)
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.

NOTE: On SketchUp versions prior to 2014 there is a bug in this method that could potentially lead to file corruption. If you call Materials.remove on a material that is painted onto any entity in the active model (e.g. faces, edges, groups, …), then calling this method will not successfully unpaint the entity and remove the material from the model. You must first unpaint all of the entities that respond to .material and .back_material before calling Materials.remove.

Examples:

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

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| ... } ⇒ nil

#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| ... } ⇒ `nil`

#length ⇒ `Integer`

#purge_unused ⇒ `Materials`

#remove(material) ⇒ `Boolean`

#remove_observer(observer) ⇒ `Boolean`

#size ⇒ `Integer`