OS-dependent flags in 'onMouseMove' callback

I’ve just encountered yet another inconsistency between macOS and Windows. This time around it happened while implementing the onMouseMove(flags, x, y, view) callback for a custom drawing tool that is supposed to update the geometry when the user selects an item (via left-click) and then drags the mouse cursor to a certain location.

Since I couldn’t find the possible values of flags in the documentation, I went ahead and printed the parameter to the console while developing my extension on macOS. Having found that flags = 2 when dragging the mouse and holding down the left-button (or, in my case, pressing with one finger on the trackpad), I happily hard-coded that value without realizing that it might be different on my least-favorite OS, Windows.

Of course, the little extension I wrote didn’t work at all when switching to Windows. It didn’t take too long to narrow down why my code wasn’t working there, but the process of investigating and having to find the correct value (which is 1 instead of 2) irked me a bit.

I find it baffling that the docs don’t say anything about the flags parameter and only provide the following “example” for all Tool callbacks:

def onMouseMove(flags, x, y, view)
  puts "onMouseMove: flags = #{flags}"
  puts "                  x = #{x}"
  puts "                  y = #{y}"
  puts "               view = #{view}"
end

I really love the SketchUp Ruby API for everything it can do, but the documentation could at least be revamped to include more details about the differences between macOS and Windows. That would certainly improve the developer experience and make coding extensions a more enjoyable activity.

I think that the constants are listed in the Tool class Overview section.

Also be aware that the API adds many cross-platform constants to the top level ObjectSpace.

These constants should always be used rather than hard-coded integers.

In addition, some API classes define cross-platform constants within the class context.

Back to the mouse dragging. The flags I think are for key modifiers, for like CTRL+mouse-click, etc.
(I think,) to trap a drag, your tool will need to set a state variable true in the onLButtonDown callback. Then on the onMouseMove callback your conditional code would test that state variable to know if the mouse button was down. Eventually the user will release the mouse button which should be trapped in the onLButtonUp callback, which would unset your state variable.

SketchUp’s API documentation has always been “behind”. Embarrassing considering that the customers are engineers using the product to create documentation.

At present there are 152 open documentation issues in the official API Issue tracker …

If you find issues that do not have an open tracker issue, feel free to open a new issue. (Please avoid duplicates.)

1 Like

Oh, so the flags are for even more complex situations… And yes, I have actually implemented the exact same logic you described by setting and unsetting a state variable in those 2 callbacks. But I started off with the flags parameter and then added that state variable, so I didn’t realize that the very first condition was actually redundant.

Thanks again, Dan!

1 Like

FYI, I posted a test tool that traps dragging some time ago, in this API tracker issue :

Sketchup::PickHelper window and boundingbox picks not correct in nested contexts · Issue #459

… readers might glean some ideas from this.

1 Like