Flags parameter in a tool's onKeyDown/Up

Dan Rathbun

You clearly asked the following question which I answered (not just for your benefit, but also for others who may be new to programming and/or the SKetchUp Ruby API.)

@ittayd said:

What is the meaning of the values of the flags parameter to the key callback methods in a tool?

I'm editing my previous post to insert this question, to make it clear what I am answering.

Re-reading your original post the second paragraph is not at all clear. Ie: Run-on sentences. Not stating what callback (onKeyUp/onKeyDown) you are referencing.

In order for us to see what you see, we'd need a code snippet to try to re-create the issue. (Meaning, that if you've already written the code to test this, share it. Don't make us write up code also.)

This API has been working for more than 10 years. There is no clamour from the developers at large that something with this is amiss.

And BTW, you do not state what SketchUp version you are testing.

Dan Rathbun

@ittayd said:

What is the meaning of the values of the flags parameter to the key callback methods in a tool?

Each bit in a bitfield represents a boolean switch for some feature.

In this case, is it whether a certain key's flag is sent to an onKey... callback.

To test whether whatever virtual keycode (that you got in the key argument,) is also associated with one of the "modifier" keys (or mouse buttons,) you test the flags bitfield against the desired bitmask constant (listed at the top of the Tools class documentation page,) using the bitwise AND ( &) method.

If the result is 0 then that modifier key was not associated with the key.
If the result is non- 0 (usually the value of the mask constant,) then that modifier key WAS associated with the key.

This is accomplished because the & operation ignores all bits in the bitfield that are unset (0) in the mask argument. (Only that bit that you are testing for is set to 1 in the mask.)

See wikipedia:
http://en.wikipedia.org/wiki/Mask_(computing)#Querying_the_status_of_a_bit

Was the SHIFT modifier associated with the key argument ?
flags & CONSTRAIN_MODIFIER_MASK != 0

Was the Alt/Option on Mac, CTRL on PC modifier associated with the key argument ?
flags & COPY_MODIFIER_MASK != 0

Was the Command on Mac, ALT on PC modifier associated with the key argument ?
flags & ALT_MODIFIER_MASK != 0

The mousekeys modifier constants are:
MK_ALT, MK_COMMAND, MK_CONTROL, MK_LBUTTON, MK_MBUTTON, MK_RBUTTON, MK_SHIFT

It may help you to wrap them up into methods with names that make sense to you:
ie:

def mask_has_shift?(flags)
  flags & CONSTRAIN_MODIFIER_MASK != 0
end

... etc.

BTW, all the virtual key codes and modifier mask constants are global (the API defines them at the toplevel.)

ittayd

@dan rathbun said:

Re-reading your original post the second paragraph is not at all clear. Ie: Run-on sentences. Not stating what callback (onKeyUp/onKeyDown) you are referencing.

Sorry if my message wasn't clear, English is not my native language (I don't even know what run-on sentences mean) and I wrote the post after a couple of hours of frustration. I edited it to make it clearer

I couldn't find code that demonstrated the use of flags in onKeyDown or onKeyUp (including searching my plugins folder, github, google).

Dan Rathbun

@ittayd said:

onKeyDown prints 101010 on hitting shift (when the ctrl is still down) which suggests it "forgets" the ctrl is down.

Why do you say this, when it is clear that the 4th bit (for CTRL modifier) is set ?

@ittayd said:

I couldn't find code examples that use flags in onKeyDown and onKeyUp either

The API docs have junky examples. They've never been a good teaching tool.

ittayd

@dan rathbun said:

@ittayd said:

onKeyDown prints 101010 on hitting shift (when the ctrl is still down) which suggests it "forgets" the ctrl is down.

Why do you say this, when it is clear that the 4th bit (for CTRL modifier) is set ?

Typo. ctrl should be shift. But it is pretty obvious from the other examples (as well as this one) that the flags values are probably the bit set they were meant to be

Dan Rathbun

@ittayd said:

Typo. ctrl should be shift.

... okay, then, let us try again:

@ittayd said:

Hitting ctrl+shift as ctrl, keeping pressed and then shift:
onKeyDown prints 11101 on hitting ctrl, note again the flags mean both ctrl and shift are down
onKeyDown prints 101010 on hitting shift (when the ctrl is still down) which suggests it "forgets" the shift is down.

It seems you are making a fundamental mistake. In this example in the quote above, the detected KEY is the SHIFT key, and it is what is causing the onKeyDown() callback to fire, and it's keycode VK_SHIFT will be stored in the key argument.

So, then you do not detect IT within the flags bitfield, because you already know what the firing key is.

Instead, at this point in time, you check the flags bitfield for whatever other modifiers are associated with this press of the SHIFT key.

Here's an example, assuming you've defined boolean methods to test the modifiers (as I explained in my educational post above.)


case key
when VK_SHIFT
  if flags_has_copy_modifier?
    # CTRL is also pressed, act accordingly
  elsif flags_has_alt_modifier?
    # ALT is also pressed, act accordingly
  else
    # act is some other way
  end
when VK_CONTROL
  if flags_has_constrain_modifier?
    # SHIFT is also pressed, act accordingly
  elsif flags_has_alt_modifier?
    # ALT is also pressed, act accordingly
  else
    # act is some other way
  end
else
  if flags_has_constrain_modifier?
    # SHIFT is also pressed, act accordingly
  elsif flags_has_copy_modifier?
    # CTRL is also pressed, act accordingly
  elsif flags_has_alt_modifier?
    # ALT is also pressed, act accordingly
  else
    # act is some other way
  end
end

ittayd

@dan rathbun said:

@ittayd said:

Hitting ctrl+shift as ctrl, keeping pressed and then shift:
onKeyDown prints 11101 on hitting ctrl, note again the flags mean both ctrl and shift are down
onKeyDown prints 101010 on hitting shift (when the ctrl is still down) which suggests it "forgets" the shift is down.

It seems you are making a fundamental mistake. In this example in the quote above, the detected KEY is the SHIFT key, and it is what is causing the onKeyDown() callback to fire, and it's keycode VK_SHIFT will be stored in the key argument.

So, then you do not detect IT within the flags bitfield, because you already know what the firing key is.

Instead, at this point in time, you check the flags bitfield for whatever other modifiers are associated with this press of the SHIFT key.

OK, so you took just the last line of a whole example:

When I press'shift' only, without 'ctrl' first, I get 101010. As if ctrl is pressed, but it is not.
And even with the 'ctrl' pressed first, what is the meaning of the 6th and 2nd bits?
When I press 'ctrl' only, without shift, I get 11101, as if ctrl and shift are pressed.
And also, what is the meaning of the 5th and 1st bits?
I get the same codes in onKeyDown and onKeyUp regardless of whether I press ctrl with shift already pressed or not or when I press shift and ctrl is pressed before or not.

And sure, the 'key' parameter does hold the code for ctrl and shift, and I ended up maintaining an instance variable to flip bits on and off when the callbacks are called. But I'm still confused as to the meaning of the flags parameter.

I'd like to mention that I have 16 years of professional programming: 1.5 years of Ruby, 8 years Java, 2 years of Scala, 5 years of C/C++ and in particular 1 year of Linux kernel development (in the virtual memory handling subsystem), as well as other assorted languages. In particular, I had many chances of doing bit manipulation of variables as well as work with bit sets.

All of that doesn't help me in understand the values of the flags parameter which in the case of onKeyDown/onKeyUp doesn't make sense to me. For comparison, in onLButtonDown, the flags are 1001 if ctrl is down when the button is clicked, 101 if shift is down and 1101 if both and just 1 when nothing is pressed. These are consistent with showing the value of the modifier keys, but inconsistent with the values I listed in my original post.

fredo6

This is what I use in my plugins

%(#008000)[def buttonLDown?(flags) ; flags & MK_LBUTTON == MK_LBUTTON ; end
def shiftDown?(flags) ; flags & CONSTRAIN_MODIFIER_MASK == CONSTRAIN_MODIFIER_MASK ; end
def ctrlDown?(flags) ; flags & COPY_MODIFIER_MASK == COPY_MODIFIER_MASK ; end
def altDown?(flags) ; flags & ALT_MODIFIER_MASK == ALT_MODIFIER_MASK ; end]

Dan Rathbun

@ittayd said:

All of that doesn't help me in understand the values of the flags parameter which in the case of onKeyDown/onKeyUp doesn't make sense to me.

You know, ... I've been involved with SKetchUp Ruby for like 10 years, and the docs are still very poor. Also there has never been a public API BugTracker, so after all this time I have lost track of all the bugs, which ones have been fixed, and which ones haven't.

But this thread has jogged my memory a bit. I seem to remember an old thread here, (perhaps started by Jim Foltz, in which we discussed funky issues with the key callbacks in the abstract Tool class. I think he even stick a test script in it named "KeyTest.rb" ? I think in it we all agreed that onKeyDown had bugs, and you had to rely more on onKeyUp.

I did a bit of testing (SU2016), and I do see that the repeat arg still is not correct in onKeyDown.

I'll see if I can find that old thread.

Dan Rathbun

Ah okay, 3 years and two months ago, Fredo was noticing these same issues in the following topic thread:

onKeyDown: getting the charcater value from key

In that thread, post # 9, I noted several other related topic threads, and the one that I just remembered by Jim Foltz, which was back in 2009.
flags on onKeyDown?
(Note that at this time Chris Fullmer was not yet a member of the SketchUp Team, and had not yet learned much programming.)

See other related threads:

My Apple Keyboard VK_KEYS

very difficult key codes!

keycodes intelmac

Jim's KeyTool.rb is also posted in this topic thread, but not sure if it is the latest version ?

Key sequence in ruby

Now, @Anton_S posted a Windows only method that calls Windows API C functions, in this post:
http://sketchucation.com/forums/viewtopic.php?f=180%26amp;t=57450%26amp;p=522915%26amp;hilit=keytest#p522915