Material

class Material

Parent: Entity | Class Index
Methods: <=>, ==, alpha, alpha=, color, color=, display_name, materialType, name, texture, texture=, use_alpha? |
Sample Code:materialtests.rb |

The Material class is used to access to the materials used in a model. It is most often applied to Faces.

You can pass any object that can be used as a material to a method that requires a material. Objects include actual materials, color, and classes that can be converted to a color.

The following are valid (assuming the existence of a Material mat1.)

face.material = mat1

face.material = "red"

face.material = 0xff0000

Instance Methods

<=>
The <=> method is used to compare two materials based on name.
Syntax:
status = material1 <=> material2
Arguments:
material1 - a Material object material2 - a Material object
Return Value:
status - 0 if they are equal, 1 if material 1 > material 2, -1 if material 1 < material 2
Comments:
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture object
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
status = m <=> m2
# Yields a 1
if (status)
UI.messagebox status
else
UI.messagebox "Failure"
end
# Yields a -1
status = m2 <=> m
if (status)
UI.messagebox status
else
UI.messagebox "Failure"
end

==
The == method is used to test if two materials are the same.
Syntax:
status = material1 == material2
Arguments:
material1 - a Material object material 2 - a Material object
Return Value:
status - true if the Materials are the same, false if they are different
Comments:
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture object
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4\\Materials\\BlueTile.jpg"
status = m == m2
# Yields a False
if (status)
UI.messagebox status
else
UI.messagebox "The Materials are not Equal"
end

alpha
The alpha method is used to retrieve the opacity of the material.
Syntax:
alpha = material.alpha
Arguments:
Return Value:
alpha - the currently opacity value for the material
Comments:
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
alpha = m.alpha
if (alpha)
UI.messagebox alpha
else
UI.messagebox "Failure"
end

alpha=
The alpha= material is used to set the opacity of the material.
Syntax:
status = material.alpha = alpha
Arguments:
alpha - an opacity value
Return Value:
status - the newly set opacity value
Comments:
The value must be between 0 and 1. A value of 0 means that the material is completely transparent. A value of 1 means that the Material is completely opaque.
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
alpha = m.alpha=0
if (alpha)
UI.messagebox alpha
else
UI.messagebox "Failure"
end

color
The color method is used to retrieve the color of the material.
Syntax:
color = material.color
Arguments:
Return Value:
color - a Color object
Comments:
If it uses a Texture, this will return the average color.
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
color = m.color
if (color)
UI.messagebox color
else
UI.messagebox "Failure"
end

color=
The color= method is used to set the color of the material.
Syntax:
color = material.color = color
Arguments:
color - a Color object
Return Value:
color - the newly set Color object's name
Comments:
If the Material has a Texture, then this turns it into a colorized Texture. To reset the color of a Material with a Texture, set the color to nil.
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
color = m.color ="Blue"
if (color)
UI.messagebox color
else
UI.messagebox "Failure"
end

display_name
The display_name method retrieves the name that is displayed within SketchUp for the material.
Syntax:
name = material.display_name
Arguments:
Return Value:
name - the display name for the material
Comments:
This should be used in most cases rather than using the name method.
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
name = m.display_name
if (name)
UI.messagebox name
else
UI.messagebox "Failure"
end

materialType
The materialType method retrieves the type of the material.
Syntax:
type = material.materialType
Arguments:
Return Value:
type - the material type for the Material object
Comments:
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
type = m.materialType
if (type)
UI.messagebox type
else
UI.messagebox "Failure"

name
The name method retrieves the name of the material.
Syntax:
name = material.name
Arguments:
Return Value:
name - the name of the Material object
Comments:
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
name = m.name
if (name)
UI.messagebox name
else
UI.messagebox "Failure"
end

texture
The texture method retrieves the texture of the material.
Syntax:
texture = material.texture
Arguments:
Return Value:
texture - the Texture object within the Material. Returns nil if the Material does not have a Texture.
Comments:
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
texture = m.texture
if (texture)
UI.messagebox texture
else
UI.messagebox "Failure"
end

texture=
The texture= method sets the texture for the material.
Syntax:
texture = material.texture = texture
Arguments:
texture - the Texture object to apply to the material
Return Value:
texture - the newly set Texture object
Comments:
Setting the Texture to nil will turn it into a solid color.
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
texture = m.texture="c:\\Program Files\\@Last Software\\SketchUp 4\\Materials\\BlueTile.jpg"
if (texture)
UI.messagebox texture
else
UI.messagebox "Failure"
end

use_alpha?
The use_alpha? material is used to determine if the material uses transparency.
Syntax:
status = material.use_alpha?
Arguments:
Return Value:
status - true if transparency is used, false if transparency is not used
Comments:
Example:

model = Sketchup.active_model
materials = model.materials
# Adds a material to the "in-use" material pallet.
m = materials.add "Joe"
m2 = materials.add "Fred"
# Returns nil if not successful, path if successful. Should return a texture objec
m.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\Carpet.jpg"
m2.texture="c:\\Program Files\\@Last Software\\SketchUp 4
\\Materials\\BlueTile.jpg"
texture = m.texture="c:\\Program Files\\@Last Software\\SketchUp 4\\Materials\\BlueTile.jpg"
status = m.use_alpha?
if (status)
UI.messagebox status
else
UI.messagebox "Failure"
end