class Sketchup::InputPoint

The {Sketchup::InputPoint} class is used to pick 3d points and/or entities that reside under the current cursor location, similar to native Line tool and other drawing tools. Unlike {Sketchup::PickHelper}, {Sketchup::InputPoint} uses inference, i.e. “snaps” to vertices and other entities when the cursor is close to them.

Only {Sketchup::Tool}s react to cursor location and most of these methods are only useful in the context of a tool. For example, if you want to determine the 3d point you just moved the cursor over, you would use {#pick} from within your {Sketchup::Tool#onMouseMove} method. {Sketchup::InputPoints} are best picked from mouse move, as you want them to draw them to the view.

For an example, see github.com/SketchUp/sketchup-ruby-api-tutorials/tree/master/examples/02_custom_tool.

To lock inference similar to native SketchUp tools, see {View#lock_inference}.

@version SketchUp 6.0

Public Class Methods

new(*args) click to toggle source

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

@example

ip1 = Sketchup::InputPoint.new

# Or you can construct it at an arbitrary location.
starting_point = Geom::Point3d.new(100, 200, 300)
ip2 = Sketchup::InputPoint.new(starting_point)

@note Prior to SketchUp 2019 it was not possible to

sub-class {Sketchup::InputPoint} due to a bug in how SketchUp initialized
the class.

@overload initialize()

@return [Sketchup::InputPoint]

@overload initialize(pt_or_vertex)

@param pt_or_vertex  [Geom::Point3d, Sketchup::Vertex] An optional Point3d
                     or Vertex where the new InputPoint should be created.
@return              [Sketchup::InputPoint]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 243
def initialize(*args)
end

Public Instance Methods

==(inputpoint2) click to toggle source

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

@example

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

@param inputpoint2

The second input point in the comparison.

@return status - true if the InputPoint objects are the same

object. False if the objects are not the same.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 47
def ==(inputpoint2)
end
clear() click to toggle source

The clear method is used to clear the input point.

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

@example

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
# Returns true
ip = ip1.clear

@return inputpoint - the cleared (empty) input point if this

successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 67
def clear
end
copy!(inputpoint) click to toggle source

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

@example

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

@param inputpoint

The second input point.

@return inputpoint - the new input point that received the copy

if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 89
def copy!(inputpoint)
end
degrees_of_freedom() click to toggle source

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

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

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
dof = ip1.degrees_of_freedom

@return degrees_of_freedom - see comments.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 118
def degrees_of_freedom
end
depth() click to toggle source

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

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

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
d = ip1.depth

@return depth - a number representing the depth of the

inputpoint (inside groups and components) if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 139
def depth
end
display?() click to toggle source

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

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

@example

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
status = ip1.display

@return [Boolean] status - true if the draw method will draw something,

false if the draw method has nothing to draw

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 158
def display?
end
draw(view) click to toggle source

The draw method is used to draw the input point.

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

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
ip = ip1.draw view

@param view

The current view.

@return view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 180
def draw(view)
end
edge() click to toggle source

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

@example

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
e = ip1.edge

@return edge - an Edge object if successful, or nil if

unsuccessful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 197
def edge
end
face() click to toggle source

The face method retrieves the face at or behind the input point. This can be used to determine a plane, similar to what native Rotate tool does.

@example

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
f = ip1.face

@note The InputPoint doesn't necessarily lie on the face, but can be e.g. on

an edge in front of the face.

@return [Sketchup::Face, nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 216
def face
end
instance_path() click to toggle source

The {#instance_path} method retrieves the instance path for the picked point.

The returned instance_path is a copy of what the input point is holding on to at the moment you access it. Your copy will not update if you make new picks with the input point.

If there has been no valid pick it will return `nil`.

@example

view = Sketchup.active_model.active_view
x = 100
y = 100
ip = view.inputpoint(x, y)
instance_path = ip.instance_path

@return [Sketchup::InstancePath, nil]

@version SketchUp 2017

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 264
def instance_path
end
pick(view, x, y, inputpoint) click to toggle source

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

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

view = Sketchup.active_model.active_view
x = 100
y = 100
inputpoint = view.inputpoint x, y
inputpoint2 = Sketchup::InputPoint.new
inputpoint.pick view, x, y
inputpoint.pick view, x, y, inputpoint2

@param view

The current view.

@param x

A x value.

@param y

A y value.

@param [optional] inputpoint

A second input point used as a reference
for the pick.

@return status - true if a valid InputPoint was picked and it

is different than it was before.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 304
def pick(view, x, y, inputpoint)
end
position() click to toggle source

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

@example

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
point = ip1.position

@return point - a Point3d object position for the input point

if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 320
def position
end
tooltip() click to toggle source

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

@example

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

@return tip - a string tooltip or an empty string (if the input

point doesn't provide a tooltip).

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 338
def tooltip
end
transformation() click to toggle source

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

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

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

@return transformation - the Transformation for the input point

if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 366
def transformation
end
valid?() click to toggle source

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

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

@example

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
status = ip1.valid?

@return [Boolean] status - true if the input point has valid data, false

if it does not have valid data.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 384
def valid?
end
vertex() click to toggle source

The vertex method returns a Vertex associated with the InputPoint. 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

view = Sketchup.active_model.active_view
x = 100
y = 100
ip1 = view.inputpoint x,y
# Click on a face and you get "On Face"
tip = ip1.vertex

@return vertex - The associated vertex

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb, line 402
def vertex
end