onRButtonDown (flags, x, y, view) proprieties



Hello everybody
is there anybody who can make me understand what is the Flags parameter, by the way I understand the mouse settings, but what I did not understand or maybe my brain refuses to understand what serves Flags, I can not understand what state indicates and how someone can exploit this parameter? something else can we change the mouse pointer by another figure, if it is yes how to proceed? Thanks a lot to all


flags — A bit mask that tells the state of the modifier keys and other mouse buttons at the time.

an example would be using Alt to move a copy…



To expand on what John said, you can compare the flag bitmask to one of the bitmask constants in the API to check if that key was pressed.

flags & COPY_MODIFIER_MASK != 0 will be true if the copy key (Ctrl on PC Alt/Option on Mac) was pressed.


(In some of my earliest plugins I created a string representation of the bitmask using base 2 and checked whether a certain index hold a 1 or 0, soemthing like this;

bitmask.to_s(2).reverse[3] == "1"

Don’t do that! It’s slower and much, much harder to read)


A bit map is an efficient way to store the status of multiple boolean properties within a single variable. Alternatively, SketchUp could have given you just two separate booleans (or a very long list of x booleans). The bit map is not at all intuitive, but once you are experienced using it, you may find it handy.

It is a sequence of bits, which can be read as an integer, but as an integer we don’t understand its meaning.

As Christina started already, we represent binary numbers here in reversed order (least significant bit left) for ease of explanation. Naturally, positional numbers have no specific order, it is only a convention. Subsequently the number of zeros at the right does not matter.

With the following code

class MyTool
  def onRButtonUp(flags, x, y, view)
    puts("onRButtonUp(flags=#{flags}==#{flags.to_s(2).reverse}, x=#{x}, y=#{y}, view=#{view})")
  rescue Exception => e
    puts e

when holding shift and right-clicking, I get:

onRButtonUp(flags=4==0010, x=758, y=493, view=#<Sketchup::View:0x00000024de1e20>)

The API documentation provides these constants:

                      decimal  dual (reversed)
COPY_MODIFIER_MASK      =  8 = 000100
ALT_MODIFIER_MASK       = 32 = 000001

(There is obviously more information encoded, e.g. for 1, 2, 16 which are not documented.)

Now when you press multiple modifier keys like shiftctrl simultaneously, you get a mix:

onRButtonUp(flags=12==0011, x=758, y=493, view=#<Sketchup::View:0x00000024de1e20>)

How can you tell from the decimal representation “12” that it is composed of “4+8”?

That’s what we can use masks for, to filter out the piece of encoded information that we are interested in. Note that the binary operation “AND” gives 1 if both input bits are 1 and otherwise 0.

    001100 (flags)
AND 001000 (CONSTRAIN_MODIFIER_MASK, mask for shift key)
    001000 != 0

    001100 (flags)
AND 000001 (ALT_MODIFIER_MASK, mask for alt key)
    000000 == 0

That means if the bit that we want to extract (filter out) is contained in the bit map, we get a number different from zero, otherwise we get zero. Note that if you do an equality comparison instead of applying a mask, you would get flags == CONSTRAIN_MODIFIER_MASK to be false although shift was pressed because your test would require all the encoded state to match exactly the pattern.

Idea: Your Tool class could even implement a different behavior if both shift and ctrl are pressed simultaneously, by testing against (CONSTRAIN_MODIFIER_MASK | COPY_MODIFIER_MASK) (0011)!

In Ruby code, we can use the more readable constant names:

> true
flags & ALT_MODIFIER_MASK != 0
> false


This had me confused, until you said:

In this context “string” had me thinking you meant storing the bits in an actual string. Or doing bit operation on strings (similar to what Christina described in the post above.)

Seeing how “string” is a specific type I’d avoid using that term to avoid confusion and conflating terms. It’s not too uncommon to see beginners convert data to strings to manipulate it - inefficiently.


It’s a common name in computer science and not a character string. But I know, we get a lot of beginner mistakes here. Now I’ve looked up synonyms and found some on Wikipedia (bit array, bit map) and edited the post.