|
SketchUp Ruby API Reference |
The PickHelper class is used
to pick entities that reside under the current cursor location. PickHelper
and InputPoint are similar, but InputPoint also uses inferencing. You
can retrieve a PickHelper object using the pick_helper method on a View
object.
Entities that are picked (found
under the cursor when a mouse or keyboard event occurs), are called Pick
Records and are placed in an indexed list.
Parent:
Object
Methods: all_picked, best_picked, count, depth_at, do_pick, element_at, init, leaf_at, path_at, pick_segment, picked_edge, picked_element, picked_face, test_point, transformation_at, view
Example Code: pickhelpertooltests.rb
The all_picked method retrieves an array of everything that was picked (all entities under the cursor when a mouse or keyboard event occurred).
picked = pickhelper.all_picked
picked - an array of entities picked
You must have called do_pick before calling this method.
ph = view.pick_helper
ph.do_pick x,y
picked = ph.all_picked
The best_picked method is used to retrieve the "best" entity picked (entity that you would have picked if you were using the select tool).
entity = pickhelper.best_picked
entity - the best picked entity
You must have called do_pick prior to calling this method.
ph = view.pick_helper
ph.do_pick x,y
best = ph.best_picked
The count method is used to count the number of entities picked (number of pick records)
number = pickhelper.count
number - the number of entities picked
ph = view.pick_helper
ph.do_pick x,y
num = ph.count
The depth_at method retrieves the depth of one of the currently picked entities in the list of pick records.
depth = pickhelper.depth_at index
index - a number from 1 to number of items picked
depth - the depth of the entity if successful
Returns 1 if element is outside a component or group.
ph = view.pick_helper
ph.do_pick x,y
depth = ph.depth_at 1
The do_pick method is used to perform the initial pick. This method is generally called before any other methods in the PickHelper class.
numpicked = pickhelper.do_pick x, y
x - x screen coordinate for the pick
y - y screen coordinate for the pick
numpicked - the number of entities picked
Returns the number of entities picked. The x and y values are the screen coordinates of the point at which would want to do a pick.
ph = view.pick_helpernum = ph.do_pick x,y
The element_at method is used to retrieve a specific entity in the list of picked elements.
entity = pickhelper.element_at index
index - a number from 0 to number of items picked
entity - the entity at the index position in the list of picked entities.
ph = view.pick_helper
ph.do_pick x,y
# Returns the element at a specific spot in the list of
# elements picked.
element = ph.element_at 0
The init method is used to initialize the PickHelper for testing points.
pickhelper = pickhelper.init x, y
pickhelper = ph.init x, y, aperture
x - x screen coordinate for the pick
y - y screen coordinate for the pick
aperture -
pickhelper - a PickHelper object
You do not normally need to call this method, but you can use this if you want to call test_point on a lot of points.
If the optional aperture is given, it is given in pixels.
ph = view.pick_helper
phnew = ph.init x, y
The leaf_at method retrieves the deepest thing in a pick path.
entity = pickhelper.leaf_at index
index - a number from 1 to number of items picked
entity - the leaf entity
For example, if you have a face that is within a component that is within another component, leaf_at returns the face.
ph = view.pick_helper
# Returns nil
phnew = ph.leaf_at 1
The path_at method is used to retrieve the entire path for an entity in the pick list (as an array).
array = pickhelper.path_at index
index - a number from 1 to number of items picked
array - an array of entities including the leaf
ph = view.pick_helper
# Returns nil
path = ph.path_at 1
The pick_segment method is used to pick a segment of a polyline curve that is defined by an array of points.
index = pickhelper.pick_segment point1, point2, ... <apature>
index = pickhelper.pick_sgement [point1, point2, ...] <apature>
point1, point2, ... - a series of Point3d objects in the polyline
[point1, point2, ...] - an array of Point3d objects in the polyline
index - an index of the point in the array if you clicked on a point or an index of a segment if you clicked on a segment (if successful)
See bezier.rb
If you click on a point in a polyline curve, the index of the point in the curve is returned (starting at 0). If you click on a segment in the polyline curve, the index of the segment is returned. Segments start at index -1 (for the segment connecting the first two points) and increase by a factor of -1 (for example, the segment connecting second and third point is -2).
point1 = Geom::Point3d.new 0,0,0
point2 = Geom::Point3d.new 10,0,0
ph = view.pick_helper
# Returns -1 or 0
path = ph.pick_segment point1, point2
The picked_edge method is used to retrieve the "best" Edge picked
edge =pickhelper.picked_edge
edge - an Edge object if successful
ph = view.pick_helper
ph.do_pick x,y
best = ph.picked_edge
The picked_element method retrieves the best drawing element, that is not an edge or a face, picked.
element =pickhelper.picked_element
element - a drawing element that is not an edge or face if successful
Returns nil if there was nothing picked.
You must have called do_pick before calling this method.
ph = view.pick_helper
ph.do_pick x,y
best = ph.picked_element
The picked_face method is used to retrieve the best face picked.
face =pickhelper.picked_face
face - a Face object if successful.
Returns nil if there were no faces picked.
You must have called do_pick before calling this method.
ph = view.pick_helper
ph.do_pick x,y
best = ph.picked_face
The test_point method is used to test a point to see if it would be selected using the default or given pick aperture.
ok = pickhelper.test_point(pt)
ok = pickhelper.test_point point, x, y
ok = pickhelper.test_point point, x, y, aperture
In the first form, you must have initialized the PickHelper using the init method. This is more efficient if you want to test a lot of points using the same screen point.
In the second and third forms, it initializes the PickHelper using a screen point and an optional pick aperture.
point = Geom::Point3d.new 0,0,0
ph = view.pick_helper
ph.do_pick x,y
# returns nil
status = ph.test_point point
The transformation_at method is used to get a transformation at a specific index in the pick helper.
transformation = pickhelper.transformation_at index
index - the index where the transformation should be retrieved.
transformation - the transformation found
The index represents the depth (whether the transformation is encapsulated in a component or group). A depth of 1 represents no encapsulation.
ph = view.pick_helper
ph.do_pick x,y
t = ph.transformation_at 1
The view method is used to retrieve the View that this PickHelper is associated with.
view = pickhelper.view
view - the current View object associated with the pick helper
ph = view.pick_helper
ph.do_pick x,y
v = ph.view