SketchUp  Ruby API Reference 

Class Index

Method Index

Developers Guide

Examples

Material class

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

Parent:Entity

Methods:  <=>, ==, alpha, alpha=, color, color=, display_name, materialType, name, texture, texture=, use_alpha?

Example Code: materialtests.rb

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

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

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

Return Value

alpha - the currently opacity value for the material

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"
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 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"
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

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 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"
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 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"
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

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 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"
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

Return Value

type - the material type for the Material object

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"
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

Return Value

name - the name of the Material object

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"
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

Return Value

texture - the Texture object within the Material. Returns nil if the Material does not have a Texture.

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"
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 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"
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?

Return Value

status - true if transparency is used, false if transparency is not used

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"
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  t

    

SketchUp  Ruby API Reference: Material

© Google Inc. 2007 sketchup.google.com