Class: Sketchup::Layers

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

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 Layers collection allows you to see and manage all of the layers in a model. You get a pointer to the Layers object from within the Model.

Examples:

model = Sketchup.active_model
layers = model.layers

Version:

SketchUp 6.0

Instance Attribute Summary

`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

#[](index_or_name) ⇒ Sketchup::Layer^?

The #[] method is used to retrieve a layer by index or name.
#add(layer_name) ⇒ Sketchup::Layer (also: #add_layer)

The #add method is used to add a new layer.
#add_folder(name) ⇒ Sketchup::LayerFolder

The #add_folder method adds or moves a layer folder.
#add_layer(layer_name)

Alias for #add.
#add_observer(observer) ⇒ Boolean

The #add_observer method is used to add an observer to the layers collection.
#at(index_or_name) ⇒ Sketchup::Layer^?

The #at method is an alias for #[].
#count ⇒ Object
#count_folders ⇒ Integer

The #count_folders method counts the number of folders which are direct children of the layer manager.
#count_layers ⇒ Integer

The #count_layers method retrieves the number of layers not in a folder.
#each {|layer| ... }

The #each method is used to iterate through all of the layers in the model.
#each_folder {|folder| ... }

The #each_folder method is used to iterate through the folders that are direct children to the layer manager.
#each_layer {|layer| ... }

The #each_layer method is used to iterate through the layers that are not inside a layer folder.
#folders ⇒ Array<Sketchup::LayerFolder>

The #folders method returns the folders of the layer manager.
#layers ⇒ Array<Sketchup::Layer>

The #layers method retrieves the layers not in a folder.
#length ⇒ Integer

The #length method retrieves the number of layers.
#purge_unused ⇒ Integer (also: #purge_unused_layers)

The #purge_unused method is used to remove unused layers.
#purge_unused_folders {|folder| ... }

The #purge_unused_folders method is used to remove all layer folder with no children.
#purge_unused_layers

Alias for #purge_unused.
#remove(layer, remove_geometry = false) ⇒ Boolean (also: #remove_layer)

Remove the given layer from the model, optionally removing the geometry.
#remove_folder(folder) ⇒ nil

The #remove_folder method removes the folder from the model.
#remove_layer(layer, remove_geometry = false)

Alias for #remove.
#remove_observer(observer) ⇒ Boolean

The #remove_observer method is used to remove an observer from the current object.
#size ⇒ Integer

The #size method is an alias of #length.
#unique_name ⇒ String

The #unique_name method can be used to get a string that will be a unique layer name inside this collection.

`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 Method Details

#[](index_or_name) ⇒ Sketchup::Layer^?

The #[] method is used to retrieve a layer by index or name.

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add "test layer"
layer_by_number = layers[1]
layer_by_name = layers["test layer"]

Parameters:

index_or_name (Integer, String) —

A number representing the layer’s index in an array of Layer objects, or the name of the layer.

See Also:

Version:

SketchUp 6.0

#add(layer_name) ⇒ Sketchup::Layer Also known as: #add_layer

The #add method is used to add a new layer.

If you give the name of a Layer that is already defined, it will return the existing Layer rather than adding a new one.

Examples:

layers = Sketchup.active_model.layers
layer = layers.add("Test Layer")

Parameters:

layer_name (String) —

The name of the added layer.

Version:

SketchUp 6.0

#add_folder(name) ⇒ Sketchup::LayerFolder #add_folder(folder) ⇒ Sketchup::LayerFolder

The #add_folder method adds or moves a layer folder.

Examples:

manager = Sketchup.active_model.layers
folder = manager.add_folder('Doors')

Overloads:

#add_folder(name) ⇒ Sketchup::LayerFolder

Adds a new folder with the given name. Unlike layers, folders do not need to have a unique name. But the name does have to be non-empty.
Parameters:
- name (String)
#add_folder(folder) ⇒ Sketchup::LayerFolder

Moves an existing LayerFolder to the receiver. This will include any children in the given folder.
Parameters:
- folder (Sketchup::LayerFolder)
See Also:
- Information on how which notifications trigger when reparenting an existing folder.

See Also:

#count_layers

Version:

SketchUp 2021.0

#add_layer(layer_name)

Alias for #add.

#add_observer(observer) ⇒ `Boolean`

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

Examples:

layers = Sketchup.active_model.layers
status = layers.add_observer observer

Parameters:

observer (Sketchup::LayersObserver)

Returns:

(Boolean) —

true if successful, false if unsuccessful.

Version:

SketchUp 6.0

#at(index_or_name) ⇒ Sketchup::Layer^?

The #at method is an alias for #[].

Examples:

model = Sketchup.active_model
layers = model.layers
new_layer = layers.add "test layer"
layer_by_number = layers.at(1)
layer_by_name = layers.at("test layer")

See Also:

Version:

SketchUp 6.0

#count ⇒ `Object`

Note:

Since SketchUp 2014 the count method is inherited from Ruby’s Enumerable mix-in module. Prior to that the #count method is an alias for #length.

Examples:

layers = Sketchup.active_model.layers
number = layers.count

Returns:

integer - the number of layers in the collection

See Also:

#length

Version:

SketchUp 6.0

#count_folders ⇒ `Integer`

The #count_folders method counts the number of folders which are direct children of the layer manager.

Examples:

manager = Sketchup.active_model.layers
folder = manager.add_folder('Doors')
num_folders = manager.count_folders

Version:

SketchUp 2021.0

#count_layers ⇒ `Integer`

The #count_layers method retrieves the number of layers not in a folder.

Examples:

layers = Sketchup.active_model.layers
number = layers.count_layers

See Also:

#size
#length

Version:

SketchUp 2021.0

#each {|layer| ... }

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.

The #each method is used to iterate through all of the layers in the model. This include layers that are nested inside folders.

Examples:

model = Sketchup.active_model
layers = model.layers
layers.add("Test layer")
layers.each { | layer | puts layer.name }

Yields:

(layer)

Yield Parameters:

layer (Sketchup::Layer)

Version:

SketchUp 6.0

#each_folder {|folder| ... }

The #each_folder method is used to iterate through the folders that are direct children to the layer manager.

Examples:

manager = Sketchup.active_model.layers
folder = manager.add_folder('Doors')
folder = manager.add_folder('Windows')
manager.each_folder { |folder|
  puts folder.name
}

Yields:

(folder)

Yield Parameters:

folder (Sketchup::LayerFolder)

Version:

SketchUp 2021.0

#each_layer {|layer| ... }

The #each_layer method is used to iterate through the layers that are not inside a layer folder.

Examples:

model = Sketchup.active_model
layers = model.layers
layers.add('Test layer')
layers.each_layer { | layer | puts layer.name }

Yields:

(layer)

Yield Parameters:

layer (Sketchup::Layer)

Version:

SketchUp 2021.0

#folders ⇒ Array<Sketchup::LayerFolder>

Note:

This does not return all the folders in the model, only those that are direct children of the layer manager.

The #folders method returns the folders of the layer manager.

Examples:

manager = Sketchup.active_model.layers
manager.add_folder('Doors')
manager.add_folder('Windows')
folders = manager.folders

Version:

SketchUp 2021.0

#layers ⇒ Array<Sketchup::Layer>

The #layers method retrieves the layers not in a folder.

Examples:

manager = Sketchup.active_model.layers
layers = manager.layers

Version:

SketchUp 2021.0

#length ⇒ `Integer`

The #length method retrieves the number of layers.

Examples:

layers = Sketchup.active_model.layers
number = layers.length

See Also:

#size

Version:

SketchUp 6.0

#purge_unused ⇒ `Integer` Also known as: #purge_unused_layers

The #purge_unused method is used to remove unused layers.

Examples:

layers = Sketchup.active_model.layers
num_layers_removed = layers.purge_unused

Returns:

(Integer) —

Number of unused layers removed

See Also:

#purge_unused_folders

Version:

SketchUp 6.0

#purge_unused_folders {|folder| ... }

The #purge_unused_folders method is used to remove all layer folder with no children.

Examples:

manager = Sketchup.active_model.layers
folder = manager.add_folder('Doors')
folder = manager.add_folder('Windows')
manager.purge_unused_folders

Yields:

(folder)

Yield Parameters:

folder (Sketchup::LayerFolder)

Version:

SketchUp 2021.0

#purge_unused_layers

Alias for #purge_unused.

#remove(layer, remove_geometry = false) ⇒ `Boolean` Also known as: #remove_layer

Remove the given layer from the model, optionally removing the geometry.

Examples:

# Remove layer by layer reference.
layer = Sketchup.active_model.layers.add("MyLayer")
Sketchup.active_model.layers.remove(layer)

# Remove layer by name.
Sketchup.active_model.layers.add("MyLayer")
Sketchup.active_model.layers.remove("MyLayer")

# Remove layer by index.
Sketchup.active_model.layers.remove(1)

# Remove layer and the entities on the layer.
edge = Sketchup.active_model.entities.add_line([0, 0, 0], [9, 9, 9])
edge.layer = Sketchup.active_model.layers.add("MyLayer")
Sketchup.active_model.layers.remove("MyLayer", true)

Parameters:

layer (Sketchup::Layer, Integer, String)
remove_geometry (Boolean) (defaults to: false) —

If true, geometry in the removed layer will be removed as well. If false (which is the default), this geometry will be placed on Layer 0.

Returns:

(Boolean) —

true if successful, false if unsuccessful.

Version:

SketchUp 2015

#remove_folder(folder) ⇒ `nil`

The #remove_folder method removes the folder from the model. All children are preserved, but moved up one level.

Examples:

manager = Sketchup.active_model.layers
folder = manager.add_folder('Doors')
manager.remove_folder(folder)

Parameters:

folder (Sketchup::LayerFolder)

Raises:

(ArgumentError) —

if the folder is not a direct child of the receiver.

Version:

SketchUp 2021.0

#remove_layer(layer, remove_geometry = false)

Alias for #remove.

#remove_observer(observer) ⇒ `Boolean`

The #remove_observer method is used to remove an observer from the current object.

Examples:

layers = Sketchup.active_model.layers
status = layers.remove_observer observer

Parameters:

observer (Sketchup::LayersObserver)

Returns:

(Boolean) —

true if successful, false if unsuccessful.

Version:

SketchUp 6.0

#size ⇒ `Integer`

The #size method is an alias of #length.

Examples:

layers = Sketchup.active_model.layers
number = layers.size

See Also:

#length

Version:

SketchUp 2014

#unique_name ⇒ String #unique_name(base_name) ⇒ String

The #unique_name method can be used to get a string that will be a unique layer name inside this collection.

Examples:

model = Sketchup.active_model
layers = model.layers
# Will return "Joe" since there are probably no other layers named that.
# Or might return something like "Joe #2" if there is already a layer
# named Joe.
good_name = layers.unique_name("Joe")

Overloads:

#unique_name ⇒ String
Returns:
- (String) —
  
  Will default to using “Layer” (SketchUp2019 and older) or “Tag” as basename for a unique name.
#unique_name(base_name) ⇒ String
Parameters:
- base_name (String) —
  
  The base name to build the unique name from.

Version:

SketchUp 6.0

Class: Sketchup::Layers

Overview

Instance Attribute Summary

Entity - Inherited

Instance Method Summary

Entity - Inherited

Instance Method Details

#[](index_or_name) ⇒ Sketchup::Layer?

#add(layer_name) ⇒ Sketchup::Layer Also known as: #add_layer

#add_folder(name) ⇒ Sketchup::LayerFolder #add_folder(folder) ⇒ Sketchup::LayerFolder

#add_layer(layer_name)

#add_observer(observer) ⇒ Boolean

#at(index_or_name) ⇒ Sketchup::Layer?

#count ⇒ Object

#count_folders ⇒ Integer

#count_layers ⇒ Integer

#each {|layer| ... }

#each_folder {|folder| ... }

#each_layer {|layer| ... }

#folders ⇒ Array<Sketchup::LayerFolder>

#layers ⇒ Array<Sketchup::Layer>

#length ⇒ Integer

#purge_unused ⇒ Integer Also known as: #purge_unused_layers

#purge_unused_folders {|folder| ... }

#purge_unused_layers

#remove(layer, remove_geometry = false) ⇒ Boolean Also known as: #remove_layer

#remove_folder(folder) ⇒ nil

#remove_layer(layer, remove_geometry = false)

#remove_observer(observer) ⇒ Boolean

#size ⇒ Integer

#unique_name ⇒ String #unique_name(base_name) ⇒ String

`Entity` - Inherited

`Entity` - Inherited

#[](index_or_name) ⇒ Sketchup::Layer^?

#add_observer(observer) ⇒ `Boolean`

#at(index_or_name) ⇒ Sketchup::Layer^?

#count ⇒ `Object`

#count_folders ⇒ `Integer`

#count_layers ⇒ `Integer`

#length ⇒ `Integer`

#purge_unused ⇒ `Integer` Also known as: #purge_unused_layers

#remove(layer, remove_geometry = false) ⇒ `Boolean` Also known as: #remove_layer

#remove_folder(folder) ⇒ `nil`

#remove_observer(observer) ⇒ `Boolean`

#size ⇒ `Integer`