Selection

class Selection

Parent: Object | Class Index
Methods:[], add, at, clear, contains?, count, each, empty?, first, include?, is_curve?, is_surface?, length, model, nitems, remove, shift, single_object?, toggle |
Sample Code:selectiontests.rb |

A set of the currently selected entities. Use the Selection method from the Model class to get a Selection object.

Instance Methods

[]
The [] method is used to retrieve an Entity object from the selection by index
Syntax:
entity = selection[index]
Arguments:
index - the index of the Entity object to retrieve
Return Value:
entity - an Entity object if successful
Comments:
This method is not very efficient. entity = model.selection[0]
Example:

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

add
The add method is used to add entities to the selection.
Syntax:
status = selection.add(ent1) status = selection.add(ent1, ent2, ...) status = selection.add([entity1, entity2, ...])
Arguments:
ent1, ent2, ... - Entity objects [entity1, entity2, ...] - an Array of Entity objects
Return Value:
status - the number of Entity objects added
Comments:
You can pass it individual Entities or an Array of Entities. ss.add(e1, e2, e3, ...) or ss.add([e1, e2, e3,...])
Example:
entities = model.active_entities entity = entities[0] status = selection.add entity

at
The at method is used to retrieve an Entity object from the selection by index.
Syntax:
entity = selection.at index
Arguments:
index - the index of the Entity object to retrieve
Return Value:
entity - an Entity object if successful
Comments:
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.
Example:
entity = entities[0] status = selection.add entity # looks like you have to retrieve from the selection set starting # at zero. entity = selection.at(0)

clear
The clear method is used to clear the selection.
Syntax:
selection.clear
Arguments:
Return Value:
Comments:
Example:
entity = entities[0] selection.add entity UI.messagebox "Ready to Clear" selection.clear

contains?
The contains? method is used to determine if a given entity is in the selection.
Syntax:
status = selection.contains? entity
Arguments:
entity - an Entity object
Return Value:
status - true if the selection contains the entity. False if the selection does not contain the entity.
Comments:
Example:

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

count
The count method is an alias for length. See also length.
Syntax:
number = selection.count
Arguments:
Return Value:
numter - the number of Entities in the selection if successful
Comments:
Example:
number = selection.count

each
The each method is used to iterate through all of the selected entities.
Syntax:
selection.each {| entity | ...}
Arguments:
entity - a variable that will hold each Entity object as they are found.
Return Value:
Comments:
If you want to do something with all of the selected Entities, this is more efficient than using []
Example:
selection = model.selection entity = entities[0] status = selection.add entity selection.each { | entity| UI.messagebox entity }

empty?
The empty? method is used to determine if there are entities in the selection.
Syntax:
status = selection.empty?
Arguments:
Return Value:
status - true if the selection is empty. False if the selection is not empty.
Comments:
Example:
status = selection.add entity status = selection.empty?

first
The first method is used to retrieve the first selected entity
Syntax:
entity = selection.first
Arguments:
Return Value:
entity - the first selected Entity object if successful
Comments:
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

include?
The include? method is an alias for contains?
Syntax:
status = selection.include? entity
Arguments:
entity - an Entity object
Return Value:
status - true if the Entity object is in the selection. False if the Entity object is not in the selection.
Comments:
Example:
selection.add entity status = selection.include? entity

is_curve?
The is_curve? method is used to determine if the selection contains all edges that belong to a single curve.
Syntax:
status = selection.is_curve?
Arguments:
Return Value:
status - true if the selection contains all edges that belong to a single curve. False if the selectio does not contain all edges that belong to a single curve.
Comments:
Example:
selection.add entity status = selection.is_curve?

is_surface?
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.
Syntax:
status = selection.is_surface?
Arguments:
Return Value:
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.
Comments:
Example:
selection.add entity status = selection.is_surface?

length
The length method is used to retrieve the number of selected Entities.
Syntax:
number = selection.length
Arguments:
Return Value:
length - the number of entities in the selection if successful
Comments:
Example:
number = selection.length

model
The model method retrieves the model for the selection.
Syntax:
model = selection.model
Arguments:
Return Value:
model - the model that includes the selection if successful
Comments:
Example:

model = selection.model
if (model)
UI.messagebox status
else
UI.messagebox "Failure"
end

nitems
The nitems method is an alias for length.
Syntax:
number = selection.nitems
Arguments:
Return Value:
number - the number of items in the selection if successful
Comments:
Example:

number = selection.nitems
if (number)
UI.messagebox number
else
UI.messagebox "Failure"
end

remove
The remove method is used to remove entities from the selection.
Syntax:
status = selection.remove entity status = selection.remove entity1, entity2, ... status = selection.remove([entity1, entity2, ...])
Arguments:
ent1, ent2, ... - Entity objects [entity1, entity2, ...] - an Array of Entity objects
Return Value:
status - the number of Entity objects removed if successful
Comments:
Example:
entity = entities[0] status = selection.add entity UI.messagebox "Ready to remove item from selection set" # returns number of items removed status = selection.remove entity

shift
The shift method is used to remove the first entity from the selection and returns it
Syntax:
entity = selection.shift
Arguments:
Return Value:
entity - the first Entity object in the selection set if successful
Comments:
Example:
status = selection.add entity UI.messagebox "Ready to remove item from selection set" entity = selection.shift

single_object?
The single_object? method is used to determine if the selection contains a single object
Syntax:
status - selection.single_object?
Arguments:
Return Value:
status - true if the selection contains a single object. False if the selection does not contain a single object.
Comments:
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?

toggle
The toggle method is used to add or remove entities from the selection.
Syntax:
status = selection.toggle entity status = selection.toggle entity1, entity2, ... status = selection.toggle([entity1, entity2, ...])
Arguments:
ent1, ent2, ... - Entity objects [entity1, entity2, ...] - an Array of Entity objects
Return Value:
status - status - the number of Entity objects toggled if successful
Comments:
You can pass it individual Entities or an Array of Entities. Entities that are not already selected are added. Entities that are already selected are removed.
Example:
status = selection.add entity UI.messagebox "Ready to toggle item in selection set" status = selection.toggle entity