1:tocdepth: 2
2
3==========================
4Graphic User Interface FAQ
5==========================
6
7.. only:: html
8
9   .. contents::
10
11.. XXX need review for Python 3.
12
13
14General GUI Questions
15=====================
16
17What platform-independent GUI toolkits exist for Python?
18========================================================
19
20Depending on what platform(s) you are aiming at, there are several.  Some
21of them haven't been ported to Python 3 yet.  At least `Tkinter`_ and `Qt`_
22are known to be Python 3-compatible.
23
24.. XXX check links
25
26Tkinter
27-------
28
29Standard builds of Python include an object-oriented interface to the Tcl/Tk
30widget set, called :ref:`tkinter <Tkinter>`.  This is probably the easiest to
31install (since it comes included with most
32`binary distributions <https://www.python.org/downloads/>`_ of Python) and use.
33For more info about Tk, including pointers to the source, see the
34`Tcl/Tk home page <https://www.tcl.tk>`_.  Tcl/Tk is fully portable to the
35Mac OS X, Windows, and Unix platforms.
36
37wxWidgets
38---------
39
40wxWidgets (https://www.wxwidgets.org) is a free, portable GUI class
41library written in C++ that provides a native look and feel on a
42number of platforms, with Windows, Mac OS X, GTK, X11, all listed as
43current stable targets.  Language bindings are available for a number
44of languages including Python, Perl, Ruby, etc.
45
46wxPython (http://www.wxpython.org) is the Python binding for
47wxwidgets.  While it often lags slightly behind the official wxWidgets
48releases, it also offers a number of features via pure Python
49extensions that are not available in other language bindings.  There
50is an active wxPython user and developer community.
51
52Both wxWidgets and wxPython are free, open source, software with
53permissive licences that allow their use in commercial products as
54well as in freeware or shareware.
55
56
57Qt
58---
59
60There are bindings available for the Qt toolkit (using either `PyQt
61<https://riverbankcomputing.com/software/pyqt/intro>`_ or `PySide
62<https://wiki.qt.io/PySide>`_) and for KDE (`PyKDE4 <https://techbase.kde.org/Languages/Python/Using_PyKDE_4>`__).
63PyQt is currently more mature than PySide, but you must buy a PyQt license from
64`Riverbank Computing <https://www.riverbankcomputing.com/commercial/license-faq>`_
65if you want to write proprietary applications.  PySide is free for all applications.
66
67Qt 4.5 upwards is licensed under the LGPL license; also, commercial licenses
68are available from `The Qt Company <https://www.qt.io/licensing/>`_.
69
70Gtk+
71----
72
73The `GObject introspection bindings <https://wiki.gnome.org/Projects/PyGObject>`_
74for Python allow you to write GTK+ 3 applications.  There is also a
75`Python GTK+ 3 Tutorial <https://python-gtk-3-tutorial.readthedocs.org/en/latest/>`_.
76
77The older PyGtk bindings for the `Gtk+ 2 toolkit <http://www.gtk.org>`_ have
78been implemented by James Henstridge; see <http://www.pygtk.org>.
79
80Kivy
81----
82
83`Kivy <https://kivy.org/>`_ is a cross-platform GUI library supporting both
84desktop operating systems (Windows, macOS, Linux) and mobile devices (Android,
85iOS).  It is written in Python and Cython, and can use a range of windowing
86backends.
87
88Kivy is free and open source software distributed under the MIT license.
89
90FLTK
91----
92
93Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
94powerful and mature cross-platform windowing system, are available from `the
95PyFLTK project <http://pyfltk.sourceforge.net>`_.
96
97
98FOX
99----
100
101A wrapper for `the FOX toolkit <http://www.fox-toolkit.org/>`_ called `FXpy
102<http://fxpy.sourceforge.net/>`_ is available.  FOX supports both Unix variants
103and Windows.
104
105
106OpenGL
107------
108
109For OpenGL bindings, see `PyOpenGL <http://pyopengl.sourceforge.net>`_.
110
111
112What platform-specific GUI toolkits exist for Python?
113========================================================
114
115By installing the `PyObjc Objective-C bridge
116<https://pythonhosted.org/pyobjc/>`_, Python programs can use Mac OS X's
117Cocoa libraries.
118
119:ref:`Pythonwin <windows-faq>` by Mark Hammond includes an interface to the
120Microsoft Foundation Classes and a Python programming environment
121that's written mostly in Python using the MFC classes.
122
123
124Tkinter questions
125=================
126
127How do I freeze Tkinter applications?
128-------------------------------------
129
130Freeze is a tool to create stand-alone applications.  When freezing Tkinter
131applications, the applications will not be truly stand-alone, as the application
132will still need the Tcl and Tk libraries.
133
134One solution is to ship the application with the Tcl and Tk libraries, and point
135to them at run-time using the :envvar:`TCL_LIBRARY` and :envvar:`TK_LIBRARY`
136environment variables.
137
138To get truly stand-alone applications, the Tcl scripts that form the library
139have to be integrated into the application as well. One tool supporting that is
140SAM (stand-alone modules), which is part of the Tix distribution
141(http://tix.sourceforge.net/).
142
143Build Tix with SAM enabled, perform the appropriate call to
144:c:func:`Tclsam_init`, etc. inside Python's
145:file:`Modules/tkappinit.c`, and link with libtclsam and libtksam (you
146might include the Tix libraries as well).
147
148
149Can I have Tk events handled while waiting for I/O?
150---------------------------------------------------
151
152On platforms other than Windows, yes, and you don't even
153need threads!  But you'll have to restructure your I/O
154code a bit.  Tk has the equivalent of Xt's :c:func:`XtAddInput()` call, which allows you
155to register a callback function which will be called from the Tk mainloop when
156I/O is possible on a file descriptor.  See :ref:`tkinter-file-handlers`.
157
158
159I can't get key bindings to work in Tkinter: why?
160-------------------------------------------------
161
162An often-heard complaint is that event handlers bound to events with the
163:meth:`bind` method don't get handled even when the appropriate key is pressed.
164
165The most common cause is that the widget to which the binding applies doesn't
166have "keyboard focus".  Check out the Tk documentation for the focus command.
167Usually a widget is given the keyboard focus by clicking in it (but not for
168labels; see the takefocus option).
169