From 52e687146eb585822f5819c840171cec9f5acabf 2009-08-31 22:05:38
From: Brian Granger <ellisonbg@gmail.com>
Date: 2009-08-31 22:05:38
Subject: [PATCH] Added a few more docs about GUI event loop integration.

---

diff --git a/docs/examples/lib/gui-wx.py b/docs/examples/lib/gui-wx.py
index 007d7dc..9a937e8 100644
--- a/docs/examples/lib/gui-wx.py
+++ b/docs/examples/lib/gui-wx.py
@@ -8,7 +8,9 @@ In [6]: %run gui-wx.py
 
 Ref: Modified from wxPython source code wxPython/samples/simple/simple.py
 
-This example can only be run once in a given IPython session.
+This example can only be run once in a given IPython session because when 
+the frame is closed, wx goes through its shutdown sequence, killing further
+attempts.  I am sure someone who knows wx can fix this issue.
 """
 
 import wx
diff --git a/docs/source/interactive/reference.txt b/docs/source/interactive/reference.txt
index 2277200..c1afa10 100644
--- a/docs/source/interactive/reference.txt
+++ b/docs/source/interactive/reference.txt
@@ -1382,7 +1382,7 @@ IPython has excellent support for working interactively with Graphical User
 Interface (GUI) toolkits, such as wxPython, PyQt4, PyGTK and Tk. This is
 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
 is extremely robust compared to our previous threaded based version. The
-advantages of
+advantages of this are:
 
 * GUIs can be enabled and disabled dynamically at runtime.
 * The active GUI can be switched dynamically at runtime.
@@ -1399,7 +1399,7 @@ 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.
 
-This to use wxPython interactively and create a running :class:`wx.App`
+Thus, to use wxPython interactively and create a running :class:`wx.App`
 object, do::
 
     %gui -a wx
@@ -1408,11 +1408,38 @@ For information on IPython's Matplotlib integration (and the ``pylab`` mode)
 see :ref:`this section <matplotlib_support>`.
 
 For developers that want to use IPython's GUI event loop integration in
-the form of a library, the capabilities are exposed in library form
+the form of a library, these capabilities are exposed in library form
 in the :mod:`IPython.lib.inputhook`.  Interested developers should see the
-module docstrings for more information.
-
-In addition, we also have a number of examples in our source directory
+module docstrings for more information, but there are a few points that
+should be mentioned here.
+
+First, the ``PyOSInputHook`` approach only works in command line settings 
+where readline is activated.
+
+Second, when using the ``PyOSInputHook`` approach, a GUI application should
+*not* start its event loop. Instead all of this is handled by the
+``PyOSInputHook``. This means that applications that are meant to be used both
+in IPython and as standalone apps need to have special code to detects how the
+application is being run. We highly recommend using IPython's
+:func:`appstart_` functions for this. Here is a simple example that shows the
+recommended code that should be at the bottom of a wxPython using GUI
+application::
+
+  try:
+      from IPython import appstart_wx
+      appstart_wx(app)
+  except ImportError:
+      app.MainLoop()
+
+This pattern should be used instead of the simple ``app.MainLoop()`` code
+that a standalone wxPython application would have.
+
+Third, unlike previous versions of IPython, we no longer "hijack" (replace
+them with no-ops) the event loops. This is done to allow applications that
+actually need to run the real event loops to do so. This is often needed to
+process pending events at critical points.
+
+Finally, we also have a number of examples in our source directory
 :file:`docs/examples/lib` that demonstrate these capabilities.
 
 .. _matplotlib_support: