<type>documentation</type>
<domain>debug</domain>
<id>debug-x-grab</id>
<title>Debugging Linux Code with XGrab* Calls</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

On Linux, Wing may lock up when a debug process that is running on the same X11 display as
Wing uses ``XGrabPointer`` or ``XGrabKey`` and similar X11 resource grabs while the
debugger is stepping through code. This causes Wing to become unresponsive to the keyboard
or mouse or both. 

This problem does not affect Wing on Windows or macOS, where it is not running as an X11
application. However, when remote debugging an X11 application, it will still affect other
applications running on the same X11 display used by the remotely debugged process, until
the process releases the grab or is terminated.

Here are some tips for working around this problem:

``(1)`` Most Linux systems offer some way to break through X11 pointer and
keyboard grabs. 

For example, ``X.org`` installations define a key symbol that releases all pointer and
keyboard grabs. You can map a key sequence to it with `xdotool
<https://www.semicomplete.com/projects/xdotool/>`__ as in the following example::

  setxkbmap -option grab:break_actions
  xdotool ctrl+alt+n XF86Ungrab

``(2)`` Some toolkits have an option to disable resource grabs specifically to avoid this
problem during debugging. For example, PyQt has a command line option ``-nograb`` that
prevents it from ever grabbing the keyboard or pointer. Adding this to the debug process
command line solves the problem.

When this option is not available, another option is to move processing into a timer or
idle task so it occurs after the grab has been released.

``(3)`` If all else fails, you can log in remotely, use ``ps`` to find the debug process,
and kill it with ``kill`` or ``kill -9`` . This will unlock your X display.

``(4)`` Setting DISPLAY to send your debug process window to another X display avoids
tying up Wing in this way. The remote display will release its grabs once you kill the
debug process from the IDE.
