##// END OF EJS Templates
Backport PR #9977: Update docs section on event loops...
Carol Willing -
Show More
@@ -7,7 +7,7 b' SPHINXBUILD = sphinx-build'
7 PAPER =
7 PAPER =
8 SRCDIR = source
8 SRCDIR = source
9 BUILDDIR = build
9 BUILDDIR = build
10 PYTHON = python
10 PYTHON = python3
11
11
12 # Internal variables.
12 # Internal variables.
13 PAPEROPT_a4 = -D latex_paper_size=a4
13 PAPEROPT_a4 = -D latex_paper_size=a4
@@ -829,20 +829,10 b' And pasting from IPython sessions works equally well::'
829 GUI event loop support
829 GUI event loop support
830 ======================
830 ======================
831
831
832 .. versionadded:: 0.11
833 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
834
835 IPython has excellent support for working interactively with Graphical User
832 IPython has excellent support for working interactively with Graphical User
836 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
833 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
837 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
834 implemented by running the toolkit's event loop while IPython is waiting for
838 is extremely robust compared to our previous thread-based version. The
835 input.
839 advantages of this are:
840
841 * GUIs can be enabled and disabled dynamically at runtime.
842 * The active GUI can be switched dynamically at runtime.
843 * In some cases, multiple GUIs can run simultaneously with no problems.
844 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
845 all of these things.
846
836
847 For users, enabling GUI event loop integration is simple. You simple use the
837 For users, enabling GUI event loop integration is simple. You simple use the
848 :magic:`gui` magic as follows::
838 :magic:`gui` magic as follows::
@@ -850,7 +840,7 b' For users, enabling GUI event loop integration is simple. You simple use the'
850 %gui [GUINAME]
840 %gui [GUINAME]
851
841
852 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
842 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
853 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
843 arguments include ``wx``, ``qt``, ``qt5``, ``gtk``, ``gtk3`` and ``tk``.
854
844
855 Thus, to use wxPython interactively and create a running :class:`wx.App`
845 Thus, to use wxPython interactively and create a running :class:`wx.App`
856 object, do::
846 object, do::
@@ -865,33 +855,17 b' flag::'
865 For information on IPython's matplotlib_ integration (and the ``matplotlib``
855 For information on IPython's matplotlib_ integration (and the ``matplotlib``
866 mode) see :ref:`this section <matplotlib_support>`.
856 mode) see :ref:`this section <matplotlib_support>`.
867
857
868 For developers that want to use IPython's GUI event loop integration in the
858 For developers that want to integrate additional event loops with IPython, see
869 form of a library, these capabilities are exposed in library form in the
859 :doc:`/config/eventloops`.
870 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
871 Interested developers should see the module docstrings for more information,
872 but there are a few points that should be mentioned here.
873
874 First, the ``PyOSInputHook`` approach only works in command line settings
875 where readline is activated. The integration with various eventloops
876 is handled somewhat differently (and more simply) when using the standalone
877 kernel, as in the qtconsole and notebook.
878
860
879 Second, when using the ``PyOSInputHook`` approach, a GUI application should
861 When running inside IPython with an integrated event loop, a GUI application
880 *not* start its event loop. Instead all of this is handled by the
862 should *not* start its own event loop. This means that applications that are
881 ``PyOSInputHook``. This means that applications that are meant to be used both
863 meant to be used both
882 in IPython and as standalone apps need to have special code to detects how the
864 in IPython and as standalone apps need to have special code to detects how the
883 application is being run. We highly recommend using IPython's support for this.
865 application is being run. We highly recommend using IPython's support for this.
884 Since the details vary slightly between toolkits, we point you to the various
866 Since the details vary slightly between toolkits, we point you to the various
885 examples in our source directory :file:`examples/Embedding` that demonstrate
867 examples in our source directory :file:`examples/IPython Kernel/gui/` that
886 these capabilities.
868 demonstrate these capabilities.
887
888 Third, unlike previous versions of IPython, we no longer "hijack" (replace
889 them with no-ops) the event loops. This is done to allow applications that
890 actually need to run the real event loops to do so. This is often needed to
891 process pending events at critical points.
892
893 Finally, we also have a number of examples in our source directory
894 :file:`examples/Embedding` that demonstrate these capabilities.
895
869
896 PyQt and PySide
870 PyQt and PySide
897 ---------------
871 ---------------
General Comments 0
You need to be logged in to leave comments. Login now