Class: Sketchup::Materials

Inherits:
Entity
  • Object
show all
Includes:
Enumerable

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 Method Summary collapse

Methods inherited from Entity

#attribute_dictionaries, #attribute_dictionary, #delete_attribute, #deleted?, #entityID, #get_attribute, #inspect, #model, #parent, #persistent_id, #set_attribute, #to_s, #typename, #valid?

Instance Method Details

#[](index) ⇒ Object #[](name) ⇒ Object

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) ⇒ Object

    Returns material - a Material object on success, Nil on failure

    Parameters:

    • index

      A number representing the material's index in an array of Material objects.

    Returns:

    • material - a Material object on success, Nil on failure

  • #[](name) ⇒ Object

    Returns material - a Material object on success, Nil on failure

    Parameters:

    • name

      The name of the material.

    Returns:

    • material - a Material object on success, Nil on failure

Version:

  • SketchUp 6.0

#add(name) ⇒ Object

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

Returns material - a Material object

Parameters:

  • name

    The name of the new material.

Returns:

  • material - a Material object

Version:

  • SketchUp 6.0

#add_observer(observer) ⇒ Object

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)

Returns success - true if successful, false if unsuccessful.

Parameters:

  • observer

    An observer.

Returns:

  • success - true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#[](index) ⇒ Object #[](name) ⇒ Object

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) ⇒ Object

    Returns material - a Material object on success, Nil on failure

    Parameters:

    • index

      A number representing the material's index in an array of Material objects.

    Returns:

    • material - a Material object on success, Nil on failure

  • #[](name) ⇒ Object

    Returns material - a Material object on success, Nil on failure

    Parameters:

    • name

      The name of the material.

    Returns:

    • material - a Material object on success, Nil on failure

Version:

  • SketchUp 6.0

#countObject

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.

Returns integer - number of materials in the collection.

Examples:

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

Returns:

  • integer - number of materials in the collection.

See Also:

Version:

  • SketchUp 6.0

#currentObject

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:

  • material - a Material object.

Version:

  • SketchUp 6.0

#current=(material) ⇒ Object

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]

Returns true if successful, false if unsuccessful.

Parameters:

  • material

    A Material object.

Returns:

  • true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

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

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
}

Yields:

  • (material)

    A variable that will hold each Material object as they are found.

Returns:

  • material - a Material object

Version:

  • SketchUp 6.0

#lengthObject

The number of materials in the collection.

The #size method is an alias for #length added in SketchUp 2014.

Examples:

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

Returns:

  • integer - number of materials in the collection.

Version:

  • SketchUp 6.0

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

Raises:

  • (RuntimeError)

    if the material failed to load.

Version:

  • SketchUp 2017

#purge_unusedObject

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) ⇒ Object

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:

model = Sketchup.active_model
materials = model.materials
material = materials.add('Joe')
materials.remove(material)
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

Returns status - true if successful, false if unsuccessful.

Parameters:

  • material

    The material to remove.

Returns:

  • status - true if successful, false if unsuccessful.

Version:

  • SketchUp 8.0 M1

#remove_observer(observer) ⇒ Object

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)

Returns success - true if successful, false if unsuccessful.

Parameters:

  • observer

    An observer.

Returns:

  • success - true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#sizeObject

The number of materials in the collection.

The #size method is an alias for #length added in SketchUp 2014.

Examples:

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

Returns:

  • integer - number of materials in the collection.

Version:

  • SketchUp 6.0