Add docs about extending GUI integration

docs/source/config/eventloops.rst

@@ -0,0 +1,103 b''
+================================
+Integrating with GUI event loops
+================================
+
+When the user types ``%gui qt``, IPython integrates itself with the Qt event
+loop, so you can use both a GUI and an interactive prompt together. IPython
+supports a number of common GUI toolkits, but from IPython 3.0, it is possible
+to integrate other event loops without modifying IPython itself.
+
+Terminal IPython handles event loops very differently from the IPython kernel,
+so different steps are needed to integrate with each.
+
+Event loops in the terminal
+---------------------------
+
+In the terminal, IPython uses a blocking Python function to wait for user input.
+However, the Python C API provides a hook, :c:func:`PyOS_InputHook`, which is
+called frequently while waiting for input. This can be set to a function which
+briefly runs the event loop and then returns.
+
+IPython provides Python level wrappers for setting and resetting this hook. To
+use them, subclass :class:`IPython.lib.inputhook.InputHookBase`, and define
+an ``enable(app=None)`` method, which initialises the event loop and calls
+``self.manager.set_inputhook(f)`` with a function which will briefly run the
+event loop before exiting. Decorate the class with a call to
+:func:`IPython.lib.inputhook.register`::
+
+    from IPython.lib.inputhook import register, InputHookBase
+
+    @register('clutter')
+    class ClutterInputHook(InputHookBase):
+        def enable(self, app=None):
+            self.manager.set_inputhook(inputhook_clutter)
+
+You can also optionally define a ``disable()`` method, taking no arguments, if
+there are extra steps needed to clean up. IPython will take care of resetting
+the hook, whether or not you provide a disable method.
+
+The simplest way to define the hook function is just to run one iteration of the
+event loop, or to run until no events are pending. Most event loops provide some
+mechanism to do one of these things. However, the GUI may lag slightly,
+because the hook is only called every 0.1 seconds. Alternatively, the hook can
+keep running the event loop until there is input ready on stdin. IPython
+provides a function to facilitate this:
+
+.. currentmodule:: IPython.lib.inputhook
+
+.. function:: stdin_ready()
+
+   Returns True if there is something ready to read on stdin.
+   
+   If this is the case, the hook function should return immediately.
+   
+   This is implemented for Windows and POSIX systems - on other platforms, it
+   always returns True, so that the hook always gives Python a chance to check
+   for input.
+
+
+Event loops in the kernel
+-------------------------
+
+The kernel runs its own event loop, so it's simpler to integrate with others.
+IPython allows the other event loop to take control, but it must call
+:meth:`IPython.kernel.zmq.kernelbase.Kernel.do_one_iteration` periodically.
+
+To integrate with this, write a function that takes a single argument,
+the IPython kernel instance, arranges for your event loop to call
+``kernel.do_one_iteration()`` at least every ``kernel._poll_interval`` seconds,
+and starts the event loop.
+
+Decorate this function with :func:`IPython.kernel.zmq.eventloops.register_integration`,
+passing in the names you wish to register it for. Here is a slightly simplified
+version of the Tkinter integration already included in IPython::
+
+    @register_integration('tk')
+    def loop_tk(kernel):
+        """Start a kernel with the Tk event loop."""
+        from tkinter import Tk
+
+        # Tk uses milliseconds
+        poll_interval = int(1000*kernel._poll_interval)
+        # For Tkinter, we create a Tk object and call its withdraw method.
+        class Timer(object):
+            def __init__(self, func):
+                self.app = Tk()
+                self.app.withdraw()
+                self.func = func
+
+            def on_timer(self):
+                self.func()
+                self.app.after(poll_interval, self.on_timer)
+
+            def start(self):
+                self.on_timer()  # Call it once to get things going.
+                self.app.mainloop()
+
+        kernel.timer = Timer(kernel.do_one_iteration)
+        kernel.timer.start()
+
+Some event loops can go one better, and integrate checking for messages on the
+kernel's ZMQ sockets, making the kernel more responsive than plain polling. How
+to do this is outside the scope of this document; if you are interested, look at
+the integration with Qt in :mod:`IPython.kernel.zmq.eventloops`.

docs/source/whatsnew/pr/inputhook_extensible.rst

@@ -0,0 +1,4 b''
+* It's now possible to provide mechanisms to integrate IPython with other event
+  loops, in addition to the ones we already support. This lets you run GUI code
+  in IPython with an interactive prompt, and to embed the IPython
+  kernel in GUI applications. See :doc:`/config/eventloops` for details.

IPython/lib/inputhook.py

@@ -190,8 +190,7 b' class InputHookManager(object):'
         the names with which to register this GUI integration. The classes
         themselves should subclass :class:`InputHookBase`.
         
-        Examples
-        --------
+        ::
         
         @inputhook_manager.register('qt')
         class QtInputHook(InputHookBase):

docs/source/config/index.rst

@@ -30,3 +30,4 b' Extending and integrating with IPython'
    custommagics
    inputtransforms
    callbacks
+   eventloops