Class: Sketchup::Selection

Inherits:
Object
  • Object
show all
Includes:
Enumerable

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 Method Summary # collapse

Instance Method Details

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

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.

Returns:

  • (Sketchup::Entitiy, nil)

See Also:

Version:

  • SketchUp 6.0

#add(ents_or_array) ⇒ Object

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

Returns status - the number of Entity objects added

Parameters:

  • ents_or_array

    List or Array of Entity objects.

Returns:

  • status - the number of Entity objects added

Version:

  • SketchUp 6.0

#add_observer(observer) ⇒ Object

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

Returns true if successful, false if unsuccessful.

Parameters:

  • observer

    An observer.

Returns:

  • true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#at(index) ⇒ Sketchup::Entitiy?

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.

Returns:

  • (Sketchup::Entitiy, nil)

See Also:

Version:

  • SketchUp 6.0

#clearObject

The clear method is used to clear the selection.

Examples:

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

Returns:

  • nil

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:

Returns:

  • (Boolean)

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 6.0

#countInteger

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.

Examples:

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

Returns:

  • (Integer)

See Also:

Version:

  • SketchUp 6.0

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

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| UI.messagebox(entity) }

Yields:

  • (entity)

    A variable that will hold each Entity object as they are found.

Returns:

  • nil

Version:

  • SketchUp 6.0

#empty?Object

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

Examples:

status = selection.add entity
status = selection.empty

Returns:

  • status - true if the selection is empty. False if the selection is not empty.

  • (Boolean)

Version:

  • SketchUp 6.0

#firstObject

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:

  • entity - the first selected Entity object if successful

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:

Returns:

  • (Boolean)

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 6.0

#is_curve?Object

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?

Returns:

  • status - true if the selection contains all edges that belong to a single curve. False if the selection does not contain all edges that belong to a single curve.

  • (Boolean)

Version:

  • SketchUp 6.0

#is_surface?Object

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

Returns:

  • status - true if the selection contains all faces that belong to a single curved surface. False if the selection does not contain all faces that belong to a single curved surface.

  • (Boolean)

Version:

  • SketchUp 6.0

#lengthInteger

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

Examples:

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

Returns:

  • (Integer)

See Also:

Version:

  • SketchUp 6.0

#modelObject

The model method retrieves the model for the selection.

Examples:

model = selection.model

Returns:

  • model - the model that includes the selection if successful

Version:

  • SketchUp 6.0

#nitemsInteger

The #nitems method is an alias for #length.

Examples:

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

Returns:

  • (Integer)

See Also:

Version:

  • SketchUp 6.0

#remove(ents_or_array) ⇒ Object

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

Returns status - the number of Entity objects removed

Parameters:

  • ents_or_array

    List or Array of Entity objects.

Returns:

  • status - the number of Entity objects removed

Version:

  • SketchUp 6.0

#remove_observer(observer) ⇒ Object

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

Returns true if successful, false if unsuccessful.

Parameters:

  • observer

    An observer.

Returns:

  • true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#shiftObject

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:

  • entity - the first Entity object in the selection set if successful

Version:

  • SketchUp 6.0

#single_object?Object

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

Returns:

  • status - true if the selection contains a single object. False if the selection does not contain a single object.

  • (Boolean)

Version:

  • SketchUp 6.0

#sizeInteger

The #size method is an alias for #length.

Examples:

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

Returns:

  • (Integer)

See Also:

Version:

  • SketchUp 2014

#toggle(ents_or_array) ⇒ Object

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

Returns status - the number of Entity objects changed

Parameters:

  • ents_or_array

    List or Array of Entity objects.

Returns:

  • status - the number of Entity objects changed

Version:

  • SketchUp 6.0