class Sketchup::Materials

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

@example

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

@version SketchUp 6.0

Public Instance Methods

[](arg) click to toggle source

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

The {#at} method is an alias of {#[]}

@example

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

@overload [](index)

@param [Integer] index
 A number representing the material's index in an array of Material
 objects.
@return [Sketchup::Material, nil] a Material object on success, Nil on failure

@overload [](name)

@param [String] name The name of the material.
@return [Sketchup::Material, nil] a Material object on success, Nil on failure

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 43
def [](arg)
end
add(name) click to toggle source

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.

@example

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

@param [String] name

The name of the new material.

@return [Sketchup::Material] a Material object

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 63
def add(name)
end
add_observer(observer) click to toggle source

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

@example

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

@param [Object] observer

An observer.

@return [Boolean] true if successful, false if unsuccessful.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 79
def add_observer(observer)
end
at(arg) click to toggle source

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

The {#at} method is an alias of {#[]}

@example

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

@overload [](index)

@param [Integer] index
 A number representing the material's index in an array of Material
 objects.
@return [Sketchup::Material, nil] a Material object on success, Nil on failure

@overload [](name)

@param [String] name The name of the material.
@return [Sketchup::Material, nil] a Material object on success, Nil on failure

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 104
def at(arg)
end
count() click to toggle source

@example

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

@note Since SketchUp 2014 the count method is inherited from Ruby's

+Enumable+ mix-in module. Prior to that the {#count} method is an alias
for {#length}.

@return [Integer]

@see length

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 121
def count
end
current() click to toggle source

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

@example

current = Sketchup.active_model.materials.current

@return [Sketchup::Material] a Material object.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 133
def current
end
current=(material) click to toggle source

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

@example

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

@param [Sketchup::Material] material

A Material object.

@return [Sketchup::Material]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 149
def current=(material)
end
each() click to toggle source

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

@example

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

@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.

@return [nil]

@version SketchUp 6.0

@yield [Sketchup::Material] A variable that will hold each Material object as they

are found.
# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 171
def each
end
length() click to toggle source

The number of materials in the collection.

@example

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

@note The returned number includes {Sketchup::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+.

@return [Integer]

@see size

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 189
def length
end
load(filename) click to toggle source

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.

@example

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

@param [String] filename

the path to the SKM file to load.

@raise [RuntimeError] if the material failed to load.

@return [Sketchup::Material] the new loaded material, or existing material.

@version SketchUp 2017

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 211
def load(filename)
end
purge_unused() click to toggle source

The purge_unused method is used to remove unused materials.

@example

materials = Sketchup.active_model.materials
materials.purge_unused

@return [Sketchup::Materials] The Materials object.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 223
def purge_unused
end
remove(material) click to toggle source

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.

@example

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

@example

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

@param [Sketchup::Material] material

The material to remove.

@return [Boolean] true if successful, false if unsuccessful.

@version SketchUp 8.0 M1

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 261
def remove(material)
end
remove_observer(observer) click to toggle source

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

@example

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

@param [Object] observer

An observer.

@return [Boolean] true if successful, false if unsuccessful.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 277
def remove_observer(observer)
end
size() click to toggle source

The number of materials in the collection.

The {#size} method is an alias for {#length}.

@example

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

@note The returned number includes {Sketchup::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+.

@return [Integer]

@see length

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 297
def size
end
unique_name(name) click to toggle source

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.

@example

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

@param [String] name

the suggested name.

@return [String] a unique name.

@version SketchUp 2018

# File lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb, line 315
def unique_name(name)
end