class Sketchup::Layers

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.

@example

model = Sketchup.active_model
layers = model.layers

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

@version SketchUp 6.0

Public Instance Methods

[](index_or_name) click to toggle source

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

@example

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

@param [Integer, String] index_or_name

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

@return [Sketchup::Layer, nil]

@see at

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 42
def [](index_or_name)
end
add(layer_name) click to toggle source

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.

@example

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

@param [String] layer_name

The name of the added layer.

@return [Sketchup::Layer]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 60
def add(layer_name)
end
Also aliased as: add_layer
add_folder(arg) click to toggle source

The {#add_folder} method adds or moves a layer folder.

@api TagFolder

@example

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

@overload add_folder(name)

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.
@param [String] name

@overload add_folder(folder)

Moves an existing {Sketchup::LayerFolder} to the receiver. This will
include any children in the given folder.
@param [Sketchup::LayerFolder] folder
@see Sketchup::LayerFolder#folder= Information on how which notifications
  trigger when reparenting an existing folder.

@return [Sketchup::LayerFolder]

@see count_layers

@version SketchUp 2021.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 91
def add_folder(arg)
end
add_layer(layer_name)
Alias for: add
add_observer(observer) click to toggle source

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

@example

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

@param [Sketchup::LayersObserver] observer

@return [Boolean] true if successful, false if unsuccessful.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 106
def add_observer(observer)
end
at(index_or_name) click to toggle source

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

@example

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

@return [Sketchup::Layer, nil]

@see []

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 123
def at(index_or_name)
end
count() click to toggle source

@example

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

@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}.

@return integer - the number of layers in the collection

@see length

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 140
def count
end
count_folders() click to toggle source

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

@api TagFolder

@example

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

@return [Integer]

@version SketchUp 2021.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 156
def count_folders
end
count_layers() click to toggle source

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

@api TagFolder

@example

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

@return [Integer]

@see size

@see length

@version SketchUp 2021.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 174
def count_layers
end
each() click to toggle source

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

@example

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

@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.

@version SketchUp 6.0

@yield [layer]

@yieldparam [Sketchup::Layer] layer

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 196
def each
end
each_folder() click to toggle source

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

@api TagFolder

@example

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

@version SketchUp 2021.0

@yield [folder]

@yieldparam [Sketchup::LayerFolder] folder

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 217
def each_folder
end
each_layer() click to toggle source

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

@api TagFolder

@example

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

@version SketchUp 2021.0

@yield [layer]

@yieldparam [Sketchup::Layer] layer

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 236
def each_layer
end
folders() click to toggle source

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

@api TagFolder

@example

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

@note This does not return all the folders in the model, only those that are

direct children of the layer manager.

@return [Array<Sketchup::LayerFolder>]

@version SketchUp 2021.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 255
def folders
end
layers() click to toggle source

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

@api TagFolder

@example

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

@return [Array<Sketchup::Layer>]

@version SketchUp 2021.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 269
def layers
end
length() click to toggle source

The {#length} method retrieves the number of layers.

@example

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

@return [Integer]

@see size

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 283
def length
end
purge_unused() click to toggle source

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

@example

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

@return [Integer] Number of unused layers removed

@see purge_unused_folders

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 297
def purge_unused
end
Also aliased as: purge_unused_layers
purge_unused_folders() click to toggle source

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

@api TagFolder

@example

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

@version SketchUp 2021.0

@yield [folder]

@yieldparam [Sketchup::LayerFolder] folder

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 317
def purge_unused_folders
end
purge_unused_layers()
Alias for: purge_unused
remove(layer, remove_geometry = false) click to toggle source

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

@example

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

@param [Sketchup::Layer, Integer, String] layer

@param [Boolean] remove_geometry

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.

@return [Boolean] true if successful, false if unsuccessful.

@version SketchUp 2015

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 349
def remove(layer, remove_geometry = false)
end
Also aliased as: remove_layer
remove_folder(folder) click to toggle source

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

@api TagFolder

@example

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

@param [Sketchup::LayerFolder] folder

@raise [ArgumentError] if the folder is not a direct child of the receiver.

@return [nil]

@version SketchUp 2021.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 370
def remove_folder(folder)
end
remove_layer(layer, remove_geometry = false)
Alias for: remove
remove_observer(observer) click to toggle source

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

@example

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

@param [Sketchup::LayersObserver] observer

@return [Boolean] true if successful, false if unsuccessful.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 385
def remove_observer(observer)
end
size() click to toggle source

The {#size} method is an alias of {#length}.

@example

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

@return [Integer]

@see length

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 399
def size
end
unique_name(*args) click to toggle source

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

@example

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

@overload unique_name

@return [String]  Will default to using "Layer" (SketchUp2019 and older)
                  or "Tag" as basename for a unique name.

@overload unique_name(base_name)

@param [String] base_name  The base name to build the unique name from.
@return [String]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb, line 424
def unique_name(*args)
end