Xev

Xev creates a window and then asks the X server to send it events when ever anything happens to the window (such as it being moved, resized, typed in, clicked in, etc.). You can also attach it to an existing window. It is useful for seeing what causes events to occur and to display the information that they contain; it is essentially a debugging and development tool, and should not be needed in normal usage. (From man page)

How to get the log file

Here are the general steps to follow..

1. Open the terminal window from Applications>Accessories>Terminal.

2. Type in the command

   $xev 

3. Experiment with it and get a feel of how events are generated.

4. Close it and type again in terminal

   $xev > xev.log 

5. This time all the events will be redirected to xev.log in your {home} directory.
6. Type an identifier(say a) from the keyboard.
7. Generate appropriate events from the mouse or keyboard without generating unnecessary events, as this will create noise in the log file.
8. Again type an identifier(same as above). This will help to find relevant events from the log file later.
9. Close as soon as possible, and try to generate minimum events to keep the log file small and readable.
10. Upload the log file.

eg from a bug report - A windows will pop up that will log all entries to xev.log in your home directory. Now point your mouse pointer in that window and press a keyboard key (say a). Now without doing anything else, try to scroll horizontally a few times. Having unable to do so, press 'a' again and then exit the window. Now upload the xev.log to launchpad.

What actually happens

Suppose the user touches the touchpad and moves the cursor a bit. The touchpad hardware sends signals to kernel which in turn communicate signals to xserver. The xserver sends signals to the window and depending on these signals various events gets raised in the window. eg - scrolling events, click, etc. Now depending on the events and the current cursor position, the window may respond in many different ways. Think of a simple web browser window regarding this. The default xev window simply outputs the events it receive along with the cursor position. Now whenever you change anything in the window created by the xev, events get generated which are printed right on the terminal so we can check what has happened.

How to use the tool?

When using this tool for uploading logs to various bug management sites typically launchpad, an identifier should be used before and after the events that are to be depicted in the particular situation. This will help in filtering out events form the large log, that such type of tools create.

For example a typical situation is to show that, some events does not work properly. A simple key press from the keyboard should be used as an identifier to easily depict what are the events of interest.

MotionNotify event, serial 30, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 4578412, (109,105), root:(116,173),
    state 0x0, is_hint 0, same_screen YES

Other events that are generated automatically and are unavoidable

KeyPress event, serial 33, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 5409865, (139,92), root:(146,160),
    state 0x0, keycode 39 (keysym 0x73, s), same_screen YES,
    XLookupString gives 1 bytes: (73) "s"
    XmbLookupString gives 1 bytes: (73) "s"
    XFilterEvent returns: False

KeyRelease event, serial 33, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 5409996, (139,92), root:(146,160),
    state 0x0, keycode 39 (keysym 0x73, s), same_screen YES,
    XLookupString gives 1 bytes: (73) "s"
    XFilterEvent returns: False

ButtonRelease event, serial 30, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 4579474, (113,105), root:(120,173),
    state 0x0, button 6, same_screen YES

ButtonPress event, serial 30, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 4579527, (113,105), root:(120,173),
    state 0x0, button 6, same_screen YES

Other events that you want to depict

KeyPress event, serial 33, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 5409865, (139,92), root:(146,160),
    state 0x0, keycode 39 (keysym 0x73, s), same_screen YES,
    XLookupString gives 1 bytes: (73) "s"
    XmbLookupString gives 1 bytes: (73) "s"
    XFilterEvent returns: False

KeyRelease event, serial 33, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 5409996, (139,92), root:(146,160),
    state 0x0, keycode 39 (keysym 0x73, s), same_screen YES,
    XLookupString gives 1 bytes: (73) "s"
    XFilterEvent returns: False

More events that are unavoidable
 

Here

KeyPress event, serial 33, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 5409865, (139,92), root:(146,160),
    state 0x0, keycode 39 (keysym 0x73, s), same_screen YES,
    XLookupString gives 1 bytes: (73) "s"
    XmbLookupString gives 1 bytes: (73) "s"
    XFilterEvent returns: False

KeyRelease event, serial 33, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 5409996, (139,92), root:(146,160),
    state 0x0, keycode 39 (keysym 0x73, s), same_screen YES,
    XLookupString gives 1 bytes: (73) "s"
    XFilterEvent returns: False

works as an identifier. Now our area of interest can be easily identified and found using a simple search in any text editor.

When to use the tool?

This tool is extremely useful in confirming bug reports in which the user is not able to produce specific events from the input device. These events may be generated by a direct hardware(mouse scroll) or virtually emulated(touchpad scroll). When the user is not able to scroll horizontally, it means the xserver is not sending the scroll horizontal events and this can be easily verified, in a xev window that prints all events it receive.

What does various events mean?

MotionNotify

Motion notify event occurs when the cursor changes position in the xev-window. time means the time of occurrence of event and (26,122) implies coordinates of the cursor with respect to the xev-window at that time. root:(967,589) implies similar coordinates with respect to whole screen.

MotionNotify event, serial 33, synthetic NO, window 0x3a00001,
    root 0xfb, subw 0x0, time 12332088, (26,122), root:(967,589),
    state 0x0, is_hint 0, same_screen YES

Focus out

You have changed the focus of the input from the xev-window to some other wondow.

FocusOut event, serial 33, synthetic NO, window 0x3a00001,
    mode NotifyNormal, detail NotifyNonlinear

Focus in

Leave Notify

This event is generated when the cursor leaves the window. time 13927290, (139,179), root:(227,245) implies time and coordinates with respect to window and screen respectfully from the point the cursor has left the window.

LeaveNotify event, serial 33, synthetic NO, window 0x3a00001,
    root 0xfb, subw 0x0, time 13927290, (139,179), root:(227,245),
    mode NotifyNormal, detail NotifyAncestor, same_screen YES,
    focus YES, state 0

Scrolling

The scrolling from a touchpad is achieved by emulation of a clickable button which when pressed down and released causes one unit scrolling up or down, like in a mouse. The main benefit of this emulation is that whether the events come from a real mouse or a touchpad emulation or any other type of device, the same software is good for all of them. For upward and downward we have two separate emulated buttons. So for each one unit scroll in upward or downward direction we have two events, a ButtonPress and a ButtonRelease event.

Vertical scrolling

Button 4 event is generated when upward vertical scrolling. This is a emulation of a button, pressing which will cause upward vertical scrolling by one unit. So, we have two events ButtonPress and ButtonRelease for one unit upward vertical scrolling. The emulated button is Button4

ButtonPress event, serial 33, synthetic NO, window 0x3a00001,
    root 0xfb, subw 0x0, time 14158474, (170,151), root:(258,217),
    state 0x0, button 4, same_screen YES

ButtonRelease event, serial 33, synthetic NO, window 0x3a00001,
    root 0xfb, subw 0x0, time 14158474, (170,151), root:(258,217),
    state 0x800, button 4, same_screen YES

Similarly for downward vertical scrolling we have Button5 emulation and two events that will be caused repeatedly when downward vertical scrolling are

ButtonPress event, serial 33, synthetic NO, window 0x3a00001,
    root 0xfb, subw 0x0, time 14526959, (163,117), root:(251,183),
    state 0x0, button 5, same_screen YES

ButtonRelease event, serial 33, synthetic NO, window 0x3a00001,
    root 0xfb, subw 0x0, time 14526959, (163,117), root:(251,183),
    state 0x1000, button 5, same_screen YES

Here time 14526959, (163,117), root:(251,183) represents the time of one scroll event and coordinates with respect to xev-window and screen. Note that the coordinates for the pair of ButtonPress and ButtonRelease events should remain same because while scrolling cursor does not move and a single emulated button press should occur at same time and at same coordinates.

Horizontal scrolling

Button 6 event is generated when left horizontal scrolling. This is a emulation of a button, pressing which will cause left horizontal scrolling by one unit. So, we have two events ButtonPress and ButtonRelease for one unit upward vertical scrolling. The emulated button is Button6

ButtonPress event, serial 30, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 4513763, (112,150), root:(119,218),
    state 0x0, button 6, same_screen YES

ButtonRelease event, serial 30, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 4513763, (112,150), root:(119,218),
    state 0x0, button 6, same_screen YES

Similarly for right horizontal scrolling we have Button7 emulation and two events that will be caused repeatedly when right horizontal scrolling are

ButtonPress event, serial 30, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 4514366, (112,150), root:(119,218),
    state 0x0, button 7, same_screen YES

ButtonRelease event, serial 30, synthetic NO, window 0x3800001,
    root 0x101, subw 0x0, time 4514366, (112,150), root:(119,218),
    state 0x0, button 7, same_screen YES