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) ⇒ Object

The [] method is used to retrieve an Entity object 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 Selection.each instead of using this method to manually grab each one.

Examples:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
selection = model.selection
entity = entities[0]
status = selection.add entity
entity = selection[0]
if (entity)
  UI.messagebox entity
else
  UI.messagebox "Failure"
end

Parameters:

  • index

    The index of the Entity object to retrieve.

Returns:

  • entity - an Entity object if successful

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) ⇒ Object

The [] method is used to retrieve an Entity object 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 Selection.each instead of using this method to manually grab each one.

Examples:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
selection = model.selection
entity = entities[0]
status = selection.add entity
entity = selection[0]
if (entity)
  UI.messagebox entity
else
  UI.messagebox "Failure"
end

Parameters:

  • index

    The index of the Entity object to retrieve.

Returns:

  • entity - an Entity object if successful

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

#include?(entity) ⇒ Object

The include? method is an alias for contains

Examples:

selection.add entity
status = selection.include? entity

Returns status - true if the Entity object is in the selection. False if the Entity object is not in the selection.

Parameters:

  • entity

    An Entity object.

Returns:

  • status - true if the Entity object is in the selection. False if the Entity object is not in the selection.

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0

#countObject

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.

Returns integer - the number of Entities in the selection if successful

Examples:

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

Returns:

  • integer - the number of Entities in the selection if successful

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) ⇒ Object

The include? method is an alias for contains

Examples:

selection.add entity
status = selection.include? entity

Returns status - true if the Entity object is in the selection. False if the Entity object is not in the selection.

Parameters:

  • entity

    An Entity object.

Returns:

  • status - true if the Entity object is in the selection. False if the Entity object is not in the selection.

Returns:

  • (Boolean)

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

#lengthObject

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

The #nitems methods is an alias of #length.

The #size methods is an alias of #length added in SketchUp 2014.

Examples:

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

Returns:

  • integer - the number of entities in the selection if successful

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

#nitemsObject

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

The #nitems methods is an alias of #length.

The #size methods is an alias of #length added in SketchUp 2014.

Examples:

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

Returns:

  • integer - the number of entities in the selection if successful

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

#sizeObject

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

The #nitems methods is an alias of #length.

The #size methods is an alias of #length added in SketchUp 2014.

Examples:

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

Returns:

  • integer - the number of entities in the selection if successful

Version:

  • SketchUp 6.0

#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