Name: krT82822 Date: 02/15/2000


java version 1.1.7B

Provide a better way to report information regarding mouse events.
-----------------------------------------------

I feel there is a deficiency in the design of the 'MouseEvent' class. More specifically,
the context of a mouse event and the detail of which button on the mouse caused the
event have been more or less combined given the design of the MouseEvent class.

I work for <company> and have worked on <company's> Java-related product.
<product> is the Java client piece to <company's> <svr> server.
<svr> allows a user at the desktop to access Unix, X-based applications in a network
bandwidth-lite fashion. In the process of working on <product>, I have come across what I feel
is a design flaw within the MouseEvent class and feel the design of it should be changed.

If you look at the 'KeyEvent' class, there are two pieces of contextual information provided with
KeyEvents. One is the 'keyCode' which is a virtual code representing a key on keyboard, the
other is the set of modifiers which is accessible via the 'getModifiers' method inherited from
the 'InputEvent' class. Whenever a key is struck on the keyboard, a Java application is able to
determine which key caused the event as well as any other keys that may have been pressed
at the same time. It's important to note that these two pieces of information are contained
within the same KeyEvent but are obtained from the event object by two means, as I've
stated above. The design flaw I see with the MouseEvent class is that unlike the KeyEvent
class, there is only one way to obtain both the contex of a MouseEvent and the distinct mouse
button that caused the event. If the MouseEvent class were orthogonal to the KeyEvent
class in terms of design, there would be a 'getButton' method that would return a virtual code
representing which button on the mouse caused the event. Secondly, the 'getModifiers'
method would return any other keys or mouse buttons that happen to be pressed at the
time of the event. However, given that these two pieces of information are combined in
one method, 'getModifiers', there is no way to determine, in a reasonable manner what the
actual state of the mouse is from one event to the next. You may ask why is the important ?
The reason being is that <company> develops software that allows the remote display of both
X applications and Windows applications. It is important for both applications to accurately
reflect the state of the mouse at all times to the remote applications. However, the current
design of the 'MouseEvent' class is insufficient for accurate mouse event reporting and
doesn't allow <company to do the best job possible. Consider the following scenario:
1. User pushes the first mouse button down and a 'MouseEvent' is sent to our application.
    Our application then reports to a remote server that the first mouse button is now down.
2. User then pushes down the third, or right most mouse button and the mouse event is
   sent to our application. Our application determines based on the previous state of the
   mouse and the set of modifiers returned from the 'getModifiers' method which actual
   mouse button caused the event since the current set of modifers for the current mouse event
   contains both the 'BUTTON1_MASK' value and the 'BUTTON3_MASK' values.
3. The user releases the first mouse button and our application receives a 'buttonReleased'
   event. Upon querying the set of modifiers via 'getModifiers', both the 'BUTTON1_MASK'
   *and* the 'BUTTON3_MASK' is set. If our application maintains a "previous state" of the
   mouse, then there's no difference between the current state of the mouse, as reported
   by 'getModifiers' and our previous state. So, what has actually happened ? The only
   possibility is to wait for another mouse event to occur, then compare the state to look
   for any differences. However, this possibility doesn't work for our application as we
   are required to send every mouse event to the server. Furthermore, different VM's,
    Netscape and IE don't report the modifiers in a consistent manner.

Based on the type of software we develop and our interest in contining to support the
Java Platform as one of our client platforms, I would like to suggest the following small
design change in the 'MouseEvent' class. I propose an additional method on the
'MouseEvent' class that will return a distinct "mouse button value" that was responsible
for the event. I propose adding 4 additional "public static final int" constants to the
'MouseEvent' class, maybe call them 'NOBUTTON', 'BUTTON1', 'BUTTON2' and 'BUTTON3'.
In addition, the method mentioned above could be called 'getButton' which will return
one of the above constants. In the case of a 'MouseEvent' occuring where there are
no buttons pressed on the mouse, the 'getButton' would return 'NOBUTTON'. In all
other cases where mouse presses/releases cause an event, 'getButton' returns either
'BUTTON1', 'BUTTON2' or 'BUTTON3'. A Java application should also check the
'getModifiers' method to determine what, if any, other keys or buttons are currently
held down. For backwards compatability reasons, the button that caused the event
could still have it's mask set in the return value of 'getModifiers', however, applications
requiring more detailed information, such as the software that <company> creates, could
be able to compare the return value of 'getModifiers' with 'getButton' to determine
which button actually caused the event. In later releases of the Java Platform, the
combining of the button which caused the event with the set of modifiers could be
phased out with 'getButton' being the preferred way to obtain this information.

I hope Sun/JavaSoft takes this suggestion seriously as the above ambigous situation
has been the cause of much frustration in developing our <product>. It would also
serve to clear an ambiguous situation that is not consistently handled among various VMs.

(Review ID: 101266)
======================================================================