In Android, what is the difference between getAction() and getActionMasked() in MotionEvent?

Question

I am confused by the two methods in Android. It seems that both methods tell you what kind of event it is, i.e., whether it is a down or up event.

When will I use which?

public void onTouchEvent(MotionEvent e)

Don't quote the documentation please, because I read it, and I don't see any parameter I can supply to either of the methods to get something different.

public final int getAction ()

and

public final int getActionMasked()

Pact

Answer 1

Yes, they both return the action (up/down etc.), but getAction() may return the action with pointer information, in which case the events may be a little different. getActionMasked() will always return "simple" actions with the pointer information "masked out" (get it?). You would then call getPointerIndex() on the same event to get the index of the pointer. Note that you will most commonly see this on multi-touch devices with multiple points of contact (pointers). The pointer index is essentially a way of matching events to contact points so you can tell them apart.

Psychophysics

Additional bit fields in the return value; the action and pointer index are returned in the same integer. Android defines a set of bit masks to extract them (which is essentially what getActionMasked does) – Psychophysics

Answer 2

getAction() returns a pointer id and an event (i.e., up, down, move) information.

getActionMasked() returns just an event (i.e., up, down, move) information. Other info is masked out.

For example:

getAction() returns 0x0105.
getActionMasked() will return 0x0005, which is 0x0105 && ACTION_MASK.

1. The value of ACTION_MASK is 0xFF. It masks the following actions.
   • ACTION_DOWN 0, UP 1, MOVE 2
   • ACTION_POINTER_DOWN 5, UP 6
2. The value of ACTION_POINTER_ID_MASK is 0xFF00. It masked the pointer ID from following deprecated constants.
   • ACTION_POINTER_1_DOWN 0x0005
   • ACTION_POINTER_2_DOWN 0x0105
   • ACTION_POINTER_3_DOWN 0x0205
   • ...

Dilatory

I don't see it yet: why would I ever want to use getActionMasked()? does that ever have any advantage over getAction()? – Diatomaceous

@Diatomaceous With getAction(), you have to bitshift/mask to separate these two pieces of data; whereas with getActionMasked() and getActionIndex() you get them separately (but probably at a higher runtime cost, due to two separate function calls). I would imagine that the combined representation returned by getAction() is what is used internally in the Android OS, since having two values combined this way is more storage- and cache-efficient on mobile hardware, bearing in mind that the touch API also stores a history of recent touch events, so there may be many of these data to be stored.. – Amias