Selection

class

• Introduction
• Methods
• • []
  • add
  • add_observer
  • at
  • clear
  • contains?
  • count
  • each
  • empty?
  • first
  • include?
  • is_curve?
  • is_surface?
  • length
  • model
  • nitems
  • remove
  • remove_observer
  • shift
  • single_object?
  • toggle

Introduction

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

Methods

Selection.[]SketchUp 6.0+

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.

Arguments:

index

The index of the Entity object to retrieve.

Returns:

entity

an Entity object if successful

 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

Selection.addSketchUp 6.0+

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.

Arguments:

ents_or_array

List or Array of Entity objects.

Returns:

status

the number of Entity objects added

 entities = model.active_entities
 entity = entities[0]
 status = selection.add entity

Selection.add_observerSketchUp 6.0+

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

Arguments:

observer

An observer.

Returns:

true if successful, false if unsuccessful.

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

Selection.atSketchUp 6.0+

The at method is used to retrieve an Entity object from the selection by index.

This method is not very efficient. It is equivalent to using selection[]. In the case of this method, you have to start at index 0 to retrieve the first entity.

Arguments:

index

The index of the Entity object to retrieve.

Returns:

entity

an Entity object if successful

 entity = entities[0]
 status = selection.add entity
 # looks like you have to retrieve from the selection set starting
 # at zero.
 entity = selection.at(0)

Selection.clearSketchUp 6.0+

The clear method is used to clear the selection.

Returns:

nil

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

Selection.contains?SketchUp 6.0+

The contains? method is used to determine if a given entity is in the selection.

Arguments:

entity

An Entity object.

Returns:

status

true if the selection contains the entity. False if the selection does not contain the entity.

 entity = entities[0]
 status = selection.add entity
 status = selection.contains? entity
 if (status)
   UI.messagebox status
 else
   UI.messagebox "Failure"
 end

Selection.countSketchUp 6.0+

The count method is an alias for length. See also length.

Returns:

number

the number of Entities in the selection if successful

 number = selection.count

Selection.eachSketchUp 6.0+

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

Arguments:

entity

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

Returns:

nil

 selection.each { |entity| UI.messagebox(entity) }

Selection.empty?SketchUp 6.0+

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

Returns:

status

true if the selection is empty. False if the selection is not empty.

 status = selection.add entity
 status = selection.empty

Selection.firstSketchUp 6.0+

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.

Returns:

entity

the first selected Entity object if successful

 status = selection.add entity
 entity = selection.first

Selection.include?SketchUp 6.0+

The include? method is an alias for contains

Arguments:

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.

 selection.add entity
 status = selection.include? entity

Selection.is_curve?SketchUp 6.0+

The is_curve? method is used to determine if the selection contains all edges that belong to a single 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.

 selection.add entity
 status = selection.is_curve?

Selection.is_surface?SketchUp 6.0+

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.

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.

 selection.add entity
 status = selection.is_surface

Selection.lengthSketchUp 6.0+

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

Returns:

length

the number of entities in the selection if successful

 number = selection.length

Selection.modelSketchUp 6.0+

The model method retrieves the model for the selection.

Returns:

model

the model that includes the selection if successful

 model = selection.model

Selection.nitemsSketchUp 6.0+

The nitems method is an alias for length. See also length.

Returns:

length

the number of entities in the selection if successful

 number = selection.nitems

Selection.removeSketchUp 6.0+

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.

Arguments:

ents_or_array

List or Array of Entity objects.

Returns:

status

the number of Entity objects removed

 entities = model.active_entities
 entity = entities[0]
 status = selection.add entity

Selection.remove_observerSketchUp 6.0+

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

Arguments:

observer

An observer.

Returns:

true if successful, false if unsuccessful.

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

Selection.shiftSketchUp 6.0+

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

Returns:

entity

the first Entity object in the selection set if successful

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

Selection.single_object?SketchUp 6.0+

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.

Returns:

status

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

 status = selection.single_object

Selection.toggleSketchUp 6.0+

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.

Arguments:

ents_or_array

List or Array of Entity objects.

Returns:

status

the number of Entity objects changed

 entities = model.active_entities
 entity = entities[0]
 status = selection.add entity