Browse files

Corrections to documentation of GUI event loop support.

  • Loading branch information...
1 parent 5a20bad commit 6f1b5b15b6e3569cebd9d3066d027d4f47c1261b @takluyver committed Jul 20, 2011
Showing with 9 additions and 10 deletions.
  1. +9 −10 docs/source/interactive/reference.txt
19 docs/source/interactive/reference.txt
@@ -1186,8 +1186,8 @@ import IPython.extensions.PhysicalQInput
.. _gui_support:
-GUI event loop support support
+GUI event loop support
.. versionadded:: 0.11
The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
@@ -1207,16 +1207,15 @@ advantages of this are:
For users, enabling GUI event loop integration is simple. You simple use the
``%gui`` magic as follows::
- %gui [-a] [GUINAME]
+ %gui [GUINAME]
With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
-arguments are ``wx``, ``qt4``, ``gtk`` and ``tk``. The ``-a`` option will
-create and return a running application object for the selected GUI toolkit.
+arguments are ``wx``, ``qt4``, ``gtk`` and ``tk``.
Thus, to use wxPython interactively and create a running :class:`wx.App`
object, do::
- %gui -a wx
+ %gui wx
For information on IPython's Matplotlib integration (and the ``pylab`` mode)
see :ref:`this section <matplotlib_support>`.
@@ -1261,7 +1260,7 @@ PyQt and PySide
.. attempt at explanation of the complete mess that is Qt support
-When you use ``gui=qt`` or ``pylab=qt``, IPython can work with either
+When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either
PyQt4 or PySide. There are three options for configuration here, because
PyQt4 has two APIs for QString and QVariant - v1, which is the default on
Python 2, and the more natural v2, which is the only API supported by PySide.
@@ -1279,7 +1278,7 @@ PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
QString and QVariant, so ETS codes like MayaVi will also work with IPython.
-If you launch IPython in pylab mode with ``ipython pylab=qt``, then IPython
+If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython
will ask matplotlib which Qt library to use (only if QT_API is *not set*),
via the 'backend.qt4' rcParam.
If matplotlib is version 1.0.1 or older, then IPython will always use PyQt4
@@ -1292,7 +1291,7 @@ without setting the v2 APIs, since neither v2 PyQt nor PySide work.
an incompatible mode.
It also means that you must *not* have ``QT_API`` set if you want to
- use ``gui=qt`` with code that requires PyQt4 API v1.
+ use ``--gui=qt`` with code that requires PyQt4 API v1.
@@ -1314,7 +1313,7 @@ process of working with the Matplotlib developers to finalize the new pylab
API, but for now you can use Matplotlib interactively using the following
- %gui -a wx
+ %gui wx
import matplotlib
from matplotlib import pylab

4 comments on commit 6f1b5b1


When using the Qt console, %gui throws a NotImplementedError ( line 387). Unless this is a temporary condition, can we have a note in the documentation explaining that --gui=qt must be used instead when starting the Qt console?


@minrk: Do you know anything about this? Is it simple to make the %gui and %pylab commands work from the Qt console?


Based on the results I got from the example, I don't know if it is proper for line 1215 to imply that GUIs can be used interactively from the IPython console, at least for Qt. I still don't know enough to be able to tell if this is just because the example is still not quite right, or if this is a limitation of the current QT GUI support, or maybe I'm just plain wrong. If this is a temporary limitation of the current code base, could the documentation include a warning message that this is the case? (Such as the warning at the top of the "IPython as a System Shell" section.)


Later in this documentation section, there is a code snippet (wx-specific) that includes a call to enable_wx. Based on your changes to the example, it appears that at least in the case of Qt, an additional call to start_event_loop_qt4 is also required there. I'm not sure if that is right, but as it stands the example and the documentation are not consistent.

I appreciate the time you have been taking to look at these issues. I do not want to come across as critical.

Please sign in to comment.