123456789_123456789_123456789_123456789_123456789_

Class: Sketchup::Selection

Relationships
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, Enumerable
Inherits: Object

Overview

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.

Examples:

# Get a handle to the selection set.
model = Sketchup.active_model
selection = model.selection

Version:

  • SketchUp 6.0

Instance Attribute Summary

  • #empty? ⇒ Boolean readonly

    The empty? method is used to determine if there are entities in the selection.

  • #is_curve? ⇒ Boolean readonly

    The is_curve? method is used to determine if the selection contains all edges that belong to a single curve.

  • #is_surface? ⇒ Boolean readonly

    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.

  • #single_object? ⇒ Boolean readonly

    The single_object? method is used to determine if the selection contains a single object.

Instance Method Summary

Instance Attribute Details

#empty? ⇒ Boolean (readonly)

The empty? method is used to determine if there are entities in the selection.

Examples:

status = selection.add entity
status = selection.empty

Version:

  • SketchUp 6.0

#is_curve? ⇒ Boolean (readonly)

The is_curve? method is used to determine if the selection contains all edges that belong to a single curve.

Examples:

selection.add entity
status = selection.is_curve?

Version:

  • SketchUp 6.0

#is_surface? ⇒ Boolean (readonly)

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.

Examples:

selection.add entity
status = selection.is_surface

Version:

  • SketchUp 6.0

#single_object? ⇒ Boolean (readonly)

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.

Examples:

status = selection.single_object

Version:

  • SketchUp 6.0

Instance Method Details

#[](index) ⇒ Sketchup::Entity?

The #[] method is used to retrieve an 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.

Examples:

model = Sketchup.active_model
entities = model.active_entities
selection = model.selection
selection.add(entities.to_a)
p selection[0]

Parameters:

  • index (Integer) —

    The index of the Entity object to retrieve.

See Also:

Version:

  • SketchUp 6.0

#add(entities) ⇒ Integer #add(*entities) ⇒ Integer

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.

Examples:

# Add by listing the entities...
ss.add(e1, e2, e3)

# ...or add by passing an Array of entities.
ss.add([e1, e2, e3])
entities = model.active_entities
entity = entities[0]
status = selection.add entity

Overloads:

Returns:

  • (Integer) —

    the number of Entity objects added

Version:

  • SketchUp 6.0

#add_observer(observer) ⇒ Boolean

The add_observer method is used to add an observer to the selection object.

Examples:

selection = Sketchup.active_model.selection
status = selection.add_observer observer

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#at(index) ⇒ Sketchup::Entity?

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

Examples:

model = Sketchup.active_model
entities = model.active_entities
selection = model.selection
selection.add(entities.to_a)
p selection.at(0)

Parameters:

  • index (Integer) —

    The index of the Entity object to retrieve.

See Also:

Version:

  • SketchUp 6.0

#clear ⇒ nil

The clear method is used to clear the selection.

Examples:

entity = entities[0]
selection.add entity
UI.messagebox "Ready to Clear"
selection.clear

Version:

  • SketchUp 6.0

#contains?(entity) ⇒ Boolean

The contains? method is and alias of #include?.

Examples:

model = Sketchup.active_model
entity = model.active_entities.first
selection = model.selection
selection.add(entity)
p selection.contains?(entity)

Parameters:

See Also:

Version:

  • SketchUp 6.0

#count ⇒ Integer

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:

selection = Sketchup.active_model.selection
number = selection.count

See Also:

Version:

  • SketchUp 6.0

#each {|entity| ... } ⇒ nil

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.

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 #[].

Examples:

selection.each { |entity| puts entity }

Yield Parameters:

Version:

  • SketchUp 6.0

#first ⇒ Sketchup::Entity

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.

Examples:

status = selection.add entity
entity = selection.first

Returns:

Version:

  • SketchUp 6.0

#include?(entity) ⇒ Boolean

The include? method is used to determine if a given Entity is in the selection.

Examples:

model = Sketchup.active_model
entity = model.active_entities.first
selection = model.selection
selection.add(entity)
p selection.include?(entity)

Parameters:

See Also:

Version:

  • SketchUp 6.0

#invert ⇒ nil

The #invert method is used to invert the selection.

Examples:

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

Version:

  • SketchUp 2019.2

#length ⇒ Integer

The #length method is used to retrieve the number of selected entities.

Examples:

selection = Sketchup.active_model.selection
number = selection.length

See Also:

Version:

  • SketchUp 6.0

#model ⇒ Sketchup::Model

The model method retrieves the model for the selection.

Examples:

model = selection.model

Returns:

  • (Sketchup::Model) —

    the model that includes the selection if successful

Version:

  • SketchUp 6.0

#nitems ⇒ Integer

The #nitems method is an alias for #length.

Examples:

selection = Sketchup.active_model.selection
number = selection.nitems

See Also:

Version:

  • SketchUp 6.0

#remove(entities) ⇒ Integer #remove(*entities) ⇒ Integer

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.

Examples:

# Remove by listing the entities...
ss.remove(e1, e2, e3)

# ...or remove by passing an Array of entities.
ss.remove([e1, e2, e3])
entities = model.active_entities
entity = entities[0]
status = selection.add entity

Overloads:

Returns:

  • (Integer) —

    the number of Entity objects removed

Version:

  • SketchUp 6.0

#remove_observer(observer) ⇒ Boolean

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

Examples:

selection = Sketchup.active_model.selection
status = object.remove_observer observer

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#shift ⇒ Sketchup::Entity

The shift method is used to remove the first entity from the selection and returns it.

Examples:

status = selection.add entity
UI.messagebox "Ready to remove item from selection set"
entity = selection.shift

Returns:

Version:

  • SketchUp 6.0

#size ⇒ Integer

The #size method is an alias for #length.

Examples:

selection = Sketchup.active_model.selection
number = selection.size

See Also:

Version:

  • SketchUp 2014

#toggle(entities) ⇒ Integer #toggle(*entities) ⇒ Integer

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.

Examples:

# Toggle by listing the entities...
ss.toggle(e1, e2, e3)

# ...or toggle by passing an Array of entities.
ss.toggle([e1, e2, e3])
entities = model.active_entities
entity = entities[0]
status = selection.add entity

Overloads:

Returns:

  • (Integer) —

    the number of Entity objects changed

Version:

  • SketchUp 6.0