Class: Sketchup::Layer

Relationships
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Entity`
Instance Chain: self, Comparable, `Entity`
Inherits:	Sketchup::Entity Object Sketchup::Entity Sketchup::Layer

Overview

Note:

As of SketchUp 2020 “Layers” were renamed to “Tags” in the ::UI. The API retains the use of “Layer” for compatibility and is synonymous with “Tag”.

The Layer class contains methods modifying and extracting information for a layer.

By default, a SketchUp model has one layer, Layer 0 (Named “Untagged” in the ::UI since SketchUp 2020), which is the base layer. You can’t delete or rename Layer 0. Unlike certain other CAD software packages, entities associated with different layers in SketchUp still intersect with each other. (If you want collections of entities to not intersect, place them in Groups instead.)

Layers are commonly used to organize your model and control the visibility of related groups and components. For example, you could make all of your wall and roof entities different groups, associate layers with those groups, and then hide those layers so as to display just the floor plan in the model.

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add('Doors')

Version:

SketchUp 6.0

Instance Attribute Summary

#color ⇒ Sketchup::Color rw

The #color method is used to retrieve the color of the layer.
#color=(color) rw

The #color= method is used to set the name of a layer.
#folder ⇒ Sketchup::LayerFolder^? rw

The #folder method is used to return the parent layer folder of a layer.
#folder=(parent) rw

The #folder= method is used to set the parent layer folder of a layer.
#line_style ⇒ Sketchup::LineStyle^? rw

The #line_style method retrieves the line style on this layer.
#line_style=(line_style) ⇒ Sketchup::Layer rw

The #line_style= method lets you set a specific line style to a layer.
#name ⇒ String rw

The #name method is used to retrieve the name of the layer.
#name=(name) rw

The #name= method is used to set the name of a layer.
#page_behavior ⇒ Integer rw

The #page_behavior method is used to retrieve the visibility behavior of the layer for new pages and existing pages.
#page_behavior=(page_behavior) rw

The #page_behavior= method is used to control the layer’s visibility behavior on existing and new pages.
#visible=(visible) rw

The #visible= method is used to set if the layer is visible.
#visible? ⇒ Boolean rw

The #visible? method is used to determine if the layer is visible.

`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

#<=>(layer2) ⇒ Integer

The #<=> method is used to compare two layers based on their names.
#==(other)

The #== method is used to determine if two layers are the same.
#display_name ⇒ String

The #display_name method is used to retrieve the display name of the layer.

`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

#color ⇒ Sketchup::Color (rw)

The #color method is used to retrieve the color of the layer.

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add('Test layer')
color = new_layer.color

Version:

SketchUp 2014

#color=(color) (rw)

The #color= method is used to set the name of a layer.

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add('Test layer')
new_layer.color = Sketchup::Color.new(192, 0, 0)

Parameters:

color (Sketchup::Color)

Version:

SketchUp 2014

#folder ⇒ Sketchup::LayerFolder^? (rw)

The #folder method is used to return the parent layer folder of a layer.

Examples:

model = Sketchup.active_model
layers = model.layers
folder1 = layers.add_folder('Folder1')
layer1 = layers.add('Layer1')
layer1.folder = folder1
parent_folder = layer1.folder # Returns: folder1

Returns:

(Sketchup::LayerFolder, nil) —

nil if the folder is a direct child to the layer manager.

Version:

SketchUp 2021.0

#folder=(parent) (rw)

The #folder= method is used to set the parent layer folder of a layer.

This will trigger onParentFolderChanged in normal cases and onLayerChanged during undo/redo.

Examples:

model = Sketchup.active_model
layers = model.layers
folder = layers.add_folder('Hello')
layer = layers.add_layer('World')
layer.folder = folder

Parameters:

parent (Sketchup::LayerFolder, nil) —

nil will make the layer a direct child to the layer manager.

Version:

SketchUp 2021.0

#line_style ⇒ Sketchup::LineStyle^? (rw)

The #line_style method retrieves the line style on this layer.

Examples:

line_style = Sketchup.active_model.layers[0].line_style

Returns:

(Sketchup::LineStyle, nil) —

The line style retrieved.

Version:

SketchUp 2019

#line_style=(line_style) ⇒ `Layer` (rw)

The #line_style= method lets you set a specific line style to a layer

Examples:

line_style = Sketchup.active_model.line_styles["Dot"]
Sketchup.active_model.layers[0].line_style = line_style

Parameters:

line_style (Sketchup::LineStyle, nil) —

The line style to set on this layer.

Returns:

(Layer) —

The layer that the line style was applied on.

Version:

SketchUp 2019

#name ⇒ String (rw)

The #name method is used to retrieve the name of the layer.

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add "test layer"
name = new_layer.name

#name=(name) (rw)

The #name= method is used to set the name of a layer.

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add "test layer"
name = new_layer.name = "new test layer"

Parameters:

name (String)

Version:

SketchUp 6.0

#page_behavior ⇒ `Integer` (rw)

The #page_behavior method is used to retrieve the visibility behavior of the layer for new pages and existing pages. For example, you may want your layer to be visible or hidden by default in any new pages (aka Scenes) created by the user.

A page keeps a list of layers that do not have their default behavior. If a layer is not in that list, then it is set to its default visibility determined by one of these values:

The behaviour is composed of a combination of these flags:

Default visibility

These flags are used to set the value of #page_behavior. A page keeps a list of layers that do not have their default behavior. If a layer is not in that list, then it is set to its default visibility which is determined by one of these flags.

LAYER_VISIBLE_BY_DEFAULT: 0x0000
LAYER_HIDDEN_BY_DEFAULT: 0x0001

Visibility on new pages

You can also set this addition flag that controls the visibility of a layer on newly created pages.

LAYER_USES_DEFAULT_VISIBILITY_ON_NEW_PAGES: 0x0000
LAYER_IS_VISIBLE_ON_NEW_PAGES: 0x0010
LAYER_IS_HIDDEN_ON_NEW_PAGES: 0x0020

The default visibility for a layer is set by either LAYER_VISIBLE_BY_DEFAULT or LAYER_HIDDEN_BY_DEFAULT. This is what will be used when a page does not contain the visibility state of a layer.

The remaining flags control the visibility of the layer for new pages.

Examples:

model = Sketchup.active_model
layers = model.layers
layer = layers.add('Test Layer')
hidden_by_default = (layer.page_behavior & LAYER_HIDDEN_BY_DEFAULT) ==
                    LAYER_HIDDEN_BY_DEFAULT

Returns:

(Integer) —

an integer representing the current behavior of the layer.

Version:

SketchUp 6.0

#page_behavior=(page_behavior) (rw)

The #page_behavior= method is used to control the layer’s visibility behavior on existing and new pages.

When you Update a page (as opposed to creating a new page) the current visibility of the layer is used.

The behavior is composed of a combination of these flags:

Default visibility

These flags are used to set the value of #page_behavior. A page keeps a list of layers that do not have their default behavior. If a layer is not in that list, then it is set to its default visibility which is determined by one of these flags.

LAYER_VISIBLE_BY_DEFAULT: 0x0000
LAYER_HIDDEN_BY_DEFAULT: 0x0001

Visibility on new pages

You can also set this addition flag that controls the visibility of a layer on newly created pages.

LAYER_USES_DEFAULT_VISIBILITY_ON_NEW_PAGES: 0x0000
LAYER_IS_VISIBLE_ON_NEW_PAGES: 0x0010
LAYER_IS_HIDDEN_ON_NEW_PAGES: 0x0020

Examples:

layers = Sketchup.active_model.layers
layer = layers.add('Test Layer')
behavior = LAYER_HIDDEN_BY_DEFAULT | LAYER_IS_HIDDEN_ON_NEW_PAGES
layer.page_behavior = behavior

Parameters:

page_behavior (Integer)

Version:

SketchUp 6.0

#visible=(visible) (rw)

The #visible= method is used to set if the layer is visible.

Examples:

model = Sketchup.active_model
layers = model.layers
layer = layers.add('Hello World')
layer.visible = false

Parameters:

visible (Boolean)

Version:

SketchUp 6.0

#visible? ⇒ `Boolean` (rw)

The #visible? method is used to determine if the layer is visible.

Examples:

model = Sketchup.active_model
layers = model.layers
layer = layers.add('Hello World')
layer.visible? # Returns: true

Version:

SketchUp 6.0

Instance Method Details

#<=>(layer2) ⇒ `Integer`

The #<=> method is used to compare two layers based on their names. This enables the Ruby Array#sort method to sort SketchUp layers.

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add "test layer"
layer1 = layers[0]
layer2 = layers[1]
status = layer1 <=> layer2

Parameters:

layer2 (Layer)

Returns:

(Integer) —

-1 if layer1 is less than layer2. 1 if layer2 is less than layer1. 0 if layer1 and layer2 are equal.

Version:

SketchUp 6.0

#==(other)

The #== method is used to determine if two layers are the same.

Examples:

model = Sketchup.active_model
layers = model.layers
layer1 = layers.add("Test layer 1")
layer2 = layers.add("Test layer 2")
equal = layer1 == layer2

Parameters:

other (Object)

Version:

SketchUp 6.0

#display_name ⇒ String

The #display_name method is used to retrieve the display name of the layer.

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add ("test layer")
name = new_layer.display_name

Class: Sketchup::Layer

Overview

Instance Attribute Summary

Entity - Inherited

Instance Method Summary

Entity - Inherited

Instance Attribute Details

#color ⇒ Sketchup::Color (rw)

#color=(color) (rw)

#folder ⇒ Sketchup::LayerFolder? (rw)

#folder=(parent) (rw)

#line_style ⇒ Sketchup::LineStyle? (rw)

#line_style=(line_style) ⇒ Layer (rw)

#name ⇒ String (rw)

#name=(name) (rw)

#page_behavior ⇒ Integer (rw)

#page_behavior=(page_behavior) (rw)

#visible=(visible) (rw)

#visible? ⇒ Boolean (rw)

Instance Method Details

#<=>(layer2) ⇒ Integer

#==(other)

#display_name ⇒ String

`Entity` - Inherited

`Entity` - Inherited

#folder ⇒ Sketchup::LayerFolder^? (rw)

#line_style ⇒ Sketchup::LineStyle^? (rw)

#line_style=(line_style) ⇒ `Layer` (rw)

#page_behavior ⇒ `Integer` (rw)

#visible? ⇒ `Boolean` (rw)

#<=>(layer2) ⇒ `Integer`