Unclear docs for InputPoint::display?


#1

I find the API docs at times unclear if the description just repeats the method name in a full phrase without explaining the concept by paraphrasing, synonyms etc.

I have received an input point which is valid, so I assumed it represents a sensible point that I can use for creating geometry (like an edge).

However it has an empty tooltip text! After further inspectation, my inputpoint has nothing (no edge, face, vertes, tooltip) except a position. Is this point “sensible” or useless?

Does anyone understand the difference of valid? and display??


#2

I think display is when there is an inference symbol thingy to draw, e.g. a blue On Face square, or a green On Point circle. There can still be a valid position though from the ground plane (or any vertical plane) even if there is nothing to draw for the point.


#3

@tt_su discussed these methods a bit back in this topic.

From what he wrote I think @eneroth’s interpretation of InputPoint#display? is correct: the display? method is true if the IP’s pick utilized some inference information so it has a tooltip and/or marker it could draw on the view. The return will be false if the IP hasn’t yet done a pick, has been cleared, or the pick didn’t find any inferences.

Per Thomas’s discussion, you need to call the InputPoint#pick method within your Tool’s onMouseMove method and then invalidate the view if you want markers and tooltips drawn dynamically by your Tool when the user moves the cursor.

InputPoint#valid? is true if InputPoint#pick has been called and found some geometry in the model. Like InputPoint#display? it is false if the IP has not yet done a pick or has been cleared. But it pertains to the picked geometry, whereas display? pertains to inference data; they are not equivalent.

I think InputPoint#pick always makes an IP valid. If there is no geometry at the pick location in the view, only the position attribute will be non-nil, and it will be a point on the preferred base plane of the current view (default xy, but can be other if you have orbited?)

The Ruby API documentation has been gradually improving, but still has a ways to go! It used to be packed full of this sort of lazy nonsense, causing extension developers to waste a lot of time experimenting to find out what methods really do.

There are github repositories where one is supposed to be able to submit API and documentation issues, but the one explicitly labelled that way seems to have been abandoned/frozen about 18 months ago and I don’t understand how to submit issues on the other ones. Perhaps @tt_su or @DanRathbun can clarify which to use and the process to submit requests for changes?


#4

It is the stubs repo that is used to change the comments in the SU Core, and from that the YARD template repo that generates the docs in the docs repo (that serves the online docs we read.)

So contribute by logging issues or submitting pull requests to …


#5

Thanks, I know the docs repo and have already contributed.

So I can trust that a valid? inputpoint without display? is a sensible point in 3d space, but I just cannot show a tooltip that explains to the user why the point was picked.


#6

Yup

The first image shows the equivalent of a valid but not displayed InputPoint in native Lien tool.

2018-08-06_15h23_03

2018-08-06_15h23_12