PickHelper

class PickHelper

Parent: Object | Class Index
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 |
Sample Code:pickhelpertooltests.rb |

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.

Instance Methods

all_picked
The all_picked method retrieves an array of everything that was picked (all entities under the cursor when a mouse or keyboard event occurred).
Syntax:
picked = pickhelper.all_picked
Arguments:
Return Value:
picked - an array of entities picked
Comments:
You must have called do_pick before calling this method.
Example:
ph = view.pick_helper ph.do_pick x,y picked = ph.all_picked

best_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).
Syntax:
entity = pickhelper.best_picked
Arguments:
Return Value:
entity - the best picked entity
Comments:
You must have called do_pick prior to calling this method.
Example:
ph = view.pick_helper ph.do_pick x,y best = ph.best_picked

count
The count method is used to count the number of entities picked (number of pick records)
Syntax:
number = pickhelper.count
Arguments:
Return Value:
number - the number of entities picked
Comments:
Example:
ph = view.pick_helper ph.do_pick x,y num = ph.count

depth_at
The depth_at method retrieves the depth of one of the currently picked entities in the list of pick records.
Syntax:
depth = pickhelper.depth_at index
Arguments:
index - a number from 1 to number of items picked
Return Value:
depth - the depth of the entity if successful
Comments:
Returns 1 if element is outside a component or group.
Example:
ph = view.pick_helper ph.do_pick x,y depth = ph.depth_at 1

do_pick
The do_pick method is used to perform the initial pick. This method is generally called before any other methods in the PickHelper class.
Syntax:
numpicked = pickhelper.do_pick x, y
Arguments:
x - x screen coordinate for the pick y - y screen coordinate for the pick
Return Value:
numpicked - the number of entities picked
Comments:
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.
Example:
ph = view.pick_helpernum = ph.do_pick x,y

element_at
The element_at method is used to retrieve a specific entity in the list of picked elements.
Syntax:
entity = pickhelper.element_at index
Arguments:
index - a number from 0 to number of items picked
Return Value:
entity - the entity at the index position in the list of picked entities.
Comments:
Example:
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

init
The init method is used to initialize the PickHelper for testing points.
Syntax:
pickhelper = pickhelper.init x, y pickhelper = ph.init x, y, aperture
Arguments:
x - x screen coordinate for the pick y - y screen coordinate for the pick aperture -
Return Value:
pickhelper - a PickHelper object
Comments:
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.
Example:
ph = view.pick_helper phnew = ph.init x, y

leaf_at
The leaf_at method retrieves the deepest thing in a pick path.
Syntax:
entity = pickhelper.leaf_at index
Arguments:
index - a number from 1 to number of items picked
Return Value:
entity - the leaf entity
Comments:
For example, if you have a face that is within a component that is within another component, leaf_at returns the face.
Example:
ph = view.pick_helper # Returns nil phnew = ph.leaf_at 1

path_at
The path_at method is used to retrieve the entire path for an entity in the pick list (as an array).
Syntax:
array = pickhelper.path_at index
Arguments:
index - a number from 1 to number of items picked
Return Value:
array - an array of entities including the leaf
Comments:
Example:
ph = view.pick_helper # Returns nil path = ph.path_at 1

pick_segment
The pick_segment method is used to pick a segment of a polyline curve that is defined by an array of points.
Syntax:
index = pickhelper.pick_segment point1, point2, ... <apature> index = pickhelper.pick_sgement [point1, point2, ...] <apature>
Arguments:
point1, point2, ... - a series of Point3d objects in the polyline [point1, point2, ...] - an array of Point3d objects in the polyline
Return Value:
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)
Comments:
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).
Example:
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

picked_edge
The picked_edge method is used to retrieve the "best" Edge picked
Syntax:
edge =pickhelper.picked_edge
Arguments:
Return Value:
edge - an Edge object if successful
Comments:
Example:
ph = view.pick_helper ph.do_pick x,y best = ph.picked_edge

picked_element
The picked_element method retrieves the best drawing element, that is not an edge or a face, picked.
Syntax:
element =pickhelper.picked_element
Arguments:
Return Value:
element - a drawing element that is not an edge or face if successful
Comments:
Returns nil if there was nothing picked. You must have called do_pick before calling this method.
Example:
ph = view.pick_helper ph.do_pick x,y best = ph.picked_element

picked_face
The picked_face method is used to retrieve the best face picked.
Syntax:
face =pickhelper.picked_face
Arguments:
Return Value:
face - a Face object if successful.
Comments:
Returns nil if there were no faces picked. You must have called do_pick before calling this method.
Example:
ph = view.pick_helper ph.do_pick x,y best = ph.picked_face

test_point
The test_point method is used to test a point to see if it would be selected using the default or given pick aperture.
Syntax:
ok = pickhelper.test_point(pt) ok = pickhelper.test_point point, x, y ok = pickhelper.test_point point, x, y, aperture
Arguments:
Return Value:
Comments:
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.
Example:
point = Geom::Point3d.new 0,0,0 ph = view.pick_helper ph.do_pick x,y # returns nil status = ph.test_point point

transformation_at
The transformation_at method is used to get a transformation at a specific index in the pick helper.
Syntax:
transformation = pickhelper.transformation_at index
Arguments:
index - the index where the transformation should be retrieved.
Return Value:
transformation - the transformation found
Comments:
The index represents the depth (whether the transformation is encapsulated in a component or group). A depth of 1 represents no encapsulation.
Example:
ph = view.pick_helper ph.do_pick x,y t = ph.transformation_at 1

view
The view method is used to retrieve the View that this PickHelper is associated with.
Syntax:
view = pickhelper.view
Arguments:
Return Value:
view - the current View object associated with the pick helper
Comments:
Example:
ph = view.pick_helper ph.do_pick x,y v = ph.view