class Sketchup::Selection
A set of the currently selected entities. Use the Model.selection method to get a Selection
object. Note that the order of entities (selection[0]
, selection[1]
and so on) in the set is in no particular order and should not be assumed to be in the same order as the user selected the entities.
@example
# Get a handle to the selection set. model = Sketchup.active_model selection = model.selection
@version SketchUp 6.0
Public Instance Methods
The {#[]} method is used to retrieve an {Sketchup::Entity} from the selection by index. Index 0 is the first entity in the selection.
This method is not very efficient. If you need to look at every entity in the selection, consider using {#each} instead of using this method to manually grab each one.
@example
model = Sketchup.active_model entities = model.active_entities selection = model.selection selection.add(entities.to_a) p selection[0]
@param [Integer] index
The index of the Entity object to retrieve.
@return [Sketchup::Entity, nil]
@see at
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 46 def [](index) end
The add method is used to add entities to the selection. Entities that are added to the Selection
are visually indicated by the selection bounding box.
You can pass it individual Entities or an Array
of Entities: Note that the add, remove, and toggle methods are all aliases for one another. So if you call remove on an entity that is not selected, it will be toggled to be selected, not removed! Be cautious when writing your code to not make the assumption about the currently selected state of a given entity.
@example
# Add by listing the entities... ss.add(e1, e2, e3) # ...or add by passing an Array of entities. ss.add([e1, e2, e3])
@example
entities = model.active_entities entity = entities[0] status = selection.add entity
@overload add(entities)
@param [Array<Sketchup::Entity>] entities
@overload add(*entities)
@param [Array<Sketchup::Entity>] entities
@return [Integer] the number of Entity objects added
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 81 def add(*args) end
The add_observer
method is used to add an observer to the selection object.
@example
selection = Sketchup.active_model.selection status = selection.add_observer observer
@param [Object] observer
An observer.
@return [Boolean] true if successful, false if unsuccessful.
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 96 def add_observer(observer) end
The {#at} method is an alias for {#[]}.
@example
model = Sketchup.active_model entities = model.active_entities selection = model.selection selection.add(entities.to_a) p selection.at(0)
@param [Integer] index
The index of the Entity object to retrieve.
@return [Sketchup::Entity, nil]
@see []
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 116 def at(index) end
The clear method is used to clear the selection.
@example
entity = entities[0] selection.add entity UI.messagebox "Ready to Clear" selection.clear
@return [nil]
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 130 def clear end
The {contains?} method is and alias of {#include?}.
@example
model = Sketchup.active_model entity = model.active_entities.first selection = model.selection selection.add(entity) p selection.contains?(entity)
@param [Sketchup::Entity] entity
@return [Boolean]
@see include?
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 149 def contains?(entity) end
@example
selection = Sketchup.active_model.selection number = selection.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]
@see length
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 166 def count end
The each method is used to iterate through all of the selected entities.
If you want to do something with all of the selected Entities, this is more efficient than using [].
@example
selection.each { |entity| puts entity }
@note Don't remove content from this collection while iterating over it with
{#each}. This would change the size of the collection and cause elemnts 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.
@return [nil]
@version SketchUp 6.0
@yield [Sketchup::Entity] A variable that will hold each Entity object as they
are found.
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 188 def each end
The empty? method is used to determine if there are entities in the selection.
@example
status = selection.add entity status = selection.empty
@return [Boolean]
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 201 def empty? end
The first method is used to retrieve the first selected entity
Returns nil if nothing is selected. This method is useful when you know that only a single entity is selected, or you are only interested in the first selected entity.
@example
status = selection.add entity entity = selection.first
@return [Sketchup::Entity] the first selected Entity object if successful
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 217 def first end
The {include?} method is used to determine if a given {Sketchup::Entity} is in the selection.
@example
model = Sketchup.active_model entity = model.active_entities.first selection = model.selection selection.add(entity) p selection.include?(entity)
@param [Sketchup::Entity] entity
@return [Boolean]
@see contains?
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 237 def include?(entity) end
The {#invert} method is used to invert the selection.
@example
model = Sketchup.active_model entities = model.active_entities selection = model.selection # Create a cube face = entities.add_face([0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0]) face.pushpull(-9) # Add the first two faces to the selection faces = entities.grep(Sketchup::Face).take(2) selection.add(faces) # Invert selection selection.invert
@return [nil]
@version SketchUp 2019.2
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 258 def invert end
The is_curve? method is used to determine if the selection contains all edges that belong to a single curve.
@example
selection.add entity status = selection.is_curve?
@return [Boolean]
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 271 def is_curve? end
The is_surface? method is used to determine if the selection contains only all of the faces that are part of a single curved surface.
@example
selection.add entity status = selection.is_surface
@return [Boolean]
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 284 def is_surface? end
The model method retrieves the model for the selection.
@example
model = selection.model
@return [Sketchup::Model] the model that includes the selection if
successful
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 312 def model end
The {#nitems} method is an alias for {#length}.
@example
selection = Sketchup.active_model.selection number = selection.nitems
@return [Integer]
@see length
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 326 def nitems end
The remove method is used to remove entities from the selection.
You can pass it individual Entities or an Array
of Entities: Note that the add, remove, and toggle methods are all aliases for one another. So if you call remove on an entity that is not selected, it will be toggled to be selected, not removed! Be cautious when writing your code to not make the assumption about the currently selected state of a given entity.
@example
# Remove by listing the entities... ss.remove(e1, e2, e3) # ...or remove by passing an Array of entities. ss.remove([e1, e2, e3])
@example
entities = model.active_entities entity = entities[0] status = selection.add entity
@overload remove(entities)
@param [Array<Sketchup::Entity>] entities
@overload remove(*entities)
@param [Array<Sketchup::Entity>] entities
@return [Integer] the number of Entity objects removed
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 360 def remove(*args) end
The remove_observer
method is used to remove an observer from the selection object.
@example
selection = Sketchup.active_model.selection status = object.remove_observer observer
@param [Object] observer
An observer.
@return [Boolean] true if successful, false if unsuccessful.
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 376 def remove_observer(observer) end
The shift method is used to remove the first entity from the selection and returns it.
@example
status = selection.add entity UI.messagebox "Ready to remove item from selection set" entity = selection.shift
@return [Sketchup::Entity] the first Entity object in the selection set
if successful
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 391 def shift end
The single_object? method is used to determine if the selection contains a single object.
It can either be a single Entity or a group of Entities for which is_curve? or is_surface? will return true.
@example
status = selection.single_object
@return [Boolean]
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 406 def single_object? end
The {#size} method is an alias for {#length}.
@example
selection = Sketchup.active_model.selection number = selection.size
@return [Integer]
@see length
@version SketchUp 2014
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 420 def size end
The toggle method is used to change whether an entity is part of the selection. Entities that are not already selected are added. Entities that are already selected are removed.
You can pass it individual Entities or an Array
of Entities: Note that the add, remove, and toggle methods are all aliases for one another. So if you call remove on an entity that is not selected, it will be toggled to be selected, not removed! Be cautious when writing your code to not make the assumption about the currently selected state of a given entity.
@example
# Toggle by listing the entities... ss.toggle(e1, e2, e3) # ...or toggle by passing an Array of entities. ss.toggle([e1, e2, e3])
@example
entities = model.active_entities entity = entities[0] status = selection.add entity
@overload toggle(entities)
@param [Array<Sketchup::Entity>] entities
@overload toggle(*entities)
@param [Array<Sketchup::Entity>] entities
@return [Integer] the number of Entity objects changed
@version SketchUp 6.0
# File lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb, line 456 def toggle(*args) end