class InputPoint

 

Parent: Object

Class Index

Methods:new, ==, clear, copy!, degrees_of_freedom, depth, display?, draw, edge, face, pick, position, tooltip, transformation, valid?, vertex

 

Sample Code:inputpointtooltests

 

The InputPoint used to pick entities that reside under the current cursor location. InputPoint and PickHelper are similar, but InputPoint also uses inferencing.   Only tools react to cursor location. Therefore, most of the methods in this class are only useful in the context of a tool you are writing. For example, if you want to determine the entity that you just clicked on with the mouse, you would use InputPoint.pick from within your onLMouseButton method in a tool.

See the example script linetool.rb for examples of using the InputPoint class.

Class Methods


 

new

The new method is used to create a new InputPoint object.

Syntax:

inputpoint = Sketchup::InputPoint.new

Arguments:

 

Return Value:

inputpoint - the newly created InputPoint object if successful

Comments:

 

Example:

ip1 = Sketchup::InputPoint.new

 
 

Instance Methods

 

==

The == method is used to determine if two input points are the same.

Syntax:

status = inputpoint1 == inputpoint2

Arguments:

inputpoint1 - the first input point in the comparison

inputpoint2 - the second input point in the comparison

Return Value:

status - true if the InputPoint objects are the same object. False if the objects are not the same.

Comments:

 

Example:

ip1 = Sketchup::InputPoint.new
ip2 = view.inputpoint x,y
# Copy the contents of inputpoint2 into inputpoint1
ip1.copy! ip2
# Returns true
status = ip1 == ip2


 

clear

The clear method is used to clear the input point.

Syntax:

inputpoint = inputpoint.clear

Arguments:

 

Return Value:

inputpoint - the cleared (empty) input point if this successful

Comments:

This sets it to an empty state. After calling this, valid? will return false.

Example:

ip1 = view.inputpoint x,y
# Returns true
ip = ip1.clear


 

copy!

The copy! method is used to copy the data from a second input point into this input point.

Syntax:

status = inputpoint.copy! inputpoint

Arguments:

inputpoint - the second input point

Return Value:

inputpoint - the new input point that received the copy if successful

Comments:

 

Example:

ip1 = Sketchup::InputPoint.new
ip2 = view.inputpoint x,y
# Copy the contents of inputpoint2 into inputpoint1
ip = ip1.copy! ip2


 

degrees_of_freedom

The degrees_of_freedom method retrieves the number of degrees of freedom there are for an input point.

Syntax:

degreesoffreedom = inputpoint.degrees_of_freedom  

Arguments:

 

Return Value:

degreesoffreedom - see comments.

Comments:

If you are just getting a point in space, then the degrees_of_freedom will be 3 - meaning that there is nothing about the point that would constrain its position.

If you are on a face, then the degrees_of_freedom will be 2 meaning that you can only move on the plane of the face.

If you are on an Edge or an axis, then the degrees_of_freedom will be 1 meaning that you can only move in the direction of the edge or axis.

If you get an end point of an Edge, or an intersection point, then the degrees_of_freedom will be 0.

Example:

ip1 = view.inputpoint x,y
dof = ip1.degrees_of_freedom


 

depth

The depth method retrieves the depth of an inference if it is coming from a component.

Syntax:

depth = inputpoint.depth

Arguments:

 

Return Value:

depth - a number representing the depth of the inputpoint (inside groups and components) if successful

Comments:

If the InputPoint is not getting a position from inside a component, this method will return 0. Otherwise it returns the depth of the entity in a nested component that is providing the position.

Example:

ip1 = view.inputpoint x,y
d = ip1.depth


 

display?

The display? method is used to determine if the input point has anything to draw.

Syntax:

status = inputpoint.display?

Arguments:

 

Return Value:

status - true if the draw method will draw something, false if the draw method has nothing to draw

Comments:

If the method returns true, then the draw method will draw something.

Example:

 ip1 = view.inputpoint x,y
status = ip1.display?


 

draw

The draw method is used to draw the input point.

Syntax:

inputpoint.draw view

Arguments:

view - the current view

Return Value:

 

Comments:

This is useful for showing an InputPoint from within the draw method of a tool that you have implemented in Ruby. Additional examples are available in the Plugins/examples directory.

Example:

ip1 = view.inputpoint x,y
ip = ip1.draw view


 

edge

The edge method is used to retrieve the edge if the input point is getting its position from a point on an Edge.

Syntax:

edge = ip.edge

Arguments:

 

Return Value:

edge - an Edge object if successful, or nil if unsuccessful

Comments:

 

Example:

ip1 = view.inputpoint x,y
e = ip1.edge


 

face

The face method retrieves the face if the input point is getting its position from a face.

Syntax:

face = inputpoint.face

Arguments:

 

Return Value:

face - a Face object if successful, or nil if unsuccessful

Comments:

Otherwise it returns nil.

Example:

ip1 = view.inputpoint x,y
f = ip1.face


 

pick

The pick method is used to get the input point at a specific screen position.

Syntax:

inputpoint.pick view, x, y

inputpoint.pick view, x, y, inputpoint

Arguments:

view - the current view

x - a x value

y - a y value

inputpoint - a second input point used as a reference for the pick

Return Value:

status - true if a valid InputPoint was picked and it is different than it was before.

Comments:

The first form just uses the screen position to compute the InputPoint. It is used when you don't want the InputPoint to be dependent on another InputPoint.

The second form uses the screen position and another InputPoint. It will find additional inferences such as along one of the axis directions from the first point.

Example:

 ip1 = view.inputpoint x,y
# Why is this failing?
s = ip1.pick view, x, y


 

position

The position method is used to get the 3d point from the input point.

Syntax:

point = inputpoint.position

Arguments:

 

Return Value:

point - a Point3d object position for the intput point if successful

Comments:

 

Example:

ip1 = view.inputpoint x,y
point = ip1.position


 

tooltip

The tooltip method is used to retrieve the string that is the tool tip to display for the input point.

Syntax:

tip = inputpoint.tooltip

Arguments:

 

Return Value:

tip - a string tooltip or an empty string (if the input point doesn't provide a tooltip).

Comments:

 

Example:

 ip1 = view.inputpoint x,y
# Click on a face and you get "On Face"
tip = ip1.tooltip


 

transformation

The transformation method retrieves the Transformation object for the input point.

Syntax:

transformation = inputpoint.transformation

Arguments:

 

Return Value:

transformation - the Transformation for the input point if successful

Comments:

If the InputPoint object is getting its position from something inside of a component instance, this method returns the Transformation of the component instance. Otherwise it returns the identity Transformation.

Note that the position method on a input point always returns a point that is transformed into model space. If you are using the edge, face or vertex method on the InputPoint though, you will probably need to use the transformation method to transform the data that you get back from the selected entity.

Example:

ip1 = view.inputpoint x,y
# In this case, returning the identity transformation
tform = ip1.transformation

 

valid?

The valid? method is used to determine if an input point has valid data.

Syntax:

status = inputpoint.valid?

Arguments:

 

Return Value:

status - true if the input point has valid data, false if it does not have valid data.

Comments:

You must have called the pick method to set the data before it is valud.

Example:

ip1 = view.inputpoint x,y
status = ip1.valid?


 

vertex

The vertex retrieves the vertex associated with the input point.

Syntax:

vertex = inputpoint.vertex

Arguments:

 

Return Value:

vertex - a Vertex object if successful.

Comments:

If the InputPoint is on the end of a line, then it will return the Vertex. If the InputPoint does not select any vertices this method returns nil.

Example:

ip1 = view.inputpoint x,y
vertex = ip1.vertex