blob: 5e1d8beafd6e0590ac1f28b665f5a318a96d22f6 [file] [log] [blame]
Georg Brandl6728c5a2009-10-11 18:31:23 +00001:tocdepth: 2
2
3==========================
4Graphic User Interface FAQ
5==========================
6
Georg Brandl44ea77b2013-03-28 13:28:44 +01007.. only:: html
8
9 .. contents::
Georg Brandl6728c5a2009-10-11 18:31:23 +000010
Georg Brandl6728c5a2009-10-11 18:31:23 +000011What platform-independent GUI toolkits exist for Python?
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000012========================================================
Georg Brandl6728c5a2009-10-11 18:31:23 +000013
14Depending on what platform(s) you are aiming at, there are several.
15
16.. XXX check links
17
18Tkinter
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000019-------
Georg Brandl6728c5a2009-10-11 18:31:23 +000020
21Standard builds of Python include an object-oriented interface to the Tcl/Tk
22widget set, called Tkinter. This is probably the easiest to install and use.
23For more info about Tk, including pointers to the source, see the Tcl/Tk home
Ned Deily4624b002014-04-12 09:31:28 -070024page at http://www.tcl.tk. Tcl/Tk is fully portable to the Mac OS X, Windows,
25and Unix platforms.
Georg Brandl6728c5a2009-10-11 18:31:23 +000026
Andrew M. Kuchling5c4e6eb2009-10-13 16:11:49 +000027wxWidgets
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000028---------
Georg Brandl6728c5a2009-10-11 18:31:23 +000029
Andrew M. Kuchling2eaa5422010-05-27 13:22:53 +000030wxWidgets (http://www.wxwidgets.org) is a free, portable GUI class
31library written in C++ that provides a native look and feel on a
Ned Deily4624b002014-04-12 09:31:28 -070032number of platforms, with Windows, Mac OS X, GTK, X11, all listed as
Andrew M. Kuchling2eaa5422010-05-27 13:22:53 +000033current stable targets. Language bindings are available for a number
34of languages including Python, Perl, Ruby, etc.
Georg Brandl6728c5a2009-10-11 18:31:23 +000035
Andrew M. Kuchling2eaa5422010-05-27 13:22:53 +000036wxPython (http://www.wxpython.org) is the Python binding for
37wxwidgets. While it often lags slightly behind the official wxWidgets
38releases, it also offers a number of features via pure Python
39extensions that are not available in other language bindings. There
40is an active wxPython user and developer community.
Andrew M. Kuchling5c4e6eb2009-10-13 16:11:49 +000041
Andrew M. Kuchling2eaa5422010-05-27 13:22:53 +000042Both wxWidgets and wxPython are free, open source, software with
43permissive licences that allow their use in commercial products as
44well as in freeware or shareware.
45
Georg Brandl6728c5a2009-10-11 18:31:23 +000046
47Qt
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000048---
Georg Brandl6728c5a2009-10-11 18:31:23 +000049
Ezio Melotti8f899282013-10-06 01:02:09 +030050There are bindings available for the Qt toolkit (using either `PyQt
Georg Brandl0f5d6c02014-10-29 10:57:37 +010051<http://www.riverbankcomputing.co.uk/software/pyqt/intro>`_ or `PySide
Georg Brandlfa55a312014-10-29 09:24:54 +010052<http://www.pyside.org/>`_) and for KDE (`PyKDE <https://techbase.kde.org/Development/Languages/Python>`__).
Ezio Melotti8f899282013-10-06 01:02:09 +030053PyQt is currently more mature than PySide, but you must buy a PyQt license from
54`Riverbank Computing <http://www.riverbankcomputing.co.uk/software/pyqt/license>`_
55if you want to write proprietary applications. PySide is free for all applications.
56
57Qt 4.5 upwards is licensed under the LGPL license; also, commercial licenses
Georg Brandlfa55a312014-10-29 09:24:54 +010058are available from `The Qt Company <http://www.qt.io/licensing/>`_.
Georg Brandl6728c5a2009-10-11 18:31:23 +000059
60Gtk+
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000061----
Georg Brandl6728c5a2009-10-11 18:31:23 +000062
63PyGtk bindings for the `Gtk+ toolkit <http://www.gtk.org>`_ have been
Andrew M. Kuchling5c4e6eb2009-10-13 16:11:49 +000064implemented by James Henstridge; see <http://www.pygtk.org>.
Georg Brandl6728c5a2009-10-11 18:31:23 +000065
66FLTK
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000067----
Georg Brandl6728c5a2009-10-11 18:31:23 +000068
69Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
70powerful and mature cross-platform windowing system, are available from `the
71PyFLTK project <http://pyfltk.sourceforge.net>`_.
72
73
74FOX
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000075----
Georg Brandl6728c5a2009-10-11 18:31:23 +000076
77A wrapper for `the FOX toolkit <http://www.fox-toolkit.org/>`_ called `FXpy
78<http://fxpy.sourceforge.net/>`_ is available. FOX supports both Unix variants
79and Windows.
80
81
82OpenGL
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000083------
Georg Brandl6728c5a2009-10-11 18:31:23 +000084
85For OpenGL bindings, see `PyOpenGL <http://pyopengl.sourceforge.net>`_.
86
87
88What platform-specific GUI toolkits exist for Python?
Andrew M. Kuchling3bfd0312010-05-27 13:30:09 +000089========================================================
Georg Brandl6728c5a2009-10-11 18:31:23 +000090
Andrew M. Kuchling5c4e6eb2009-10-13 16:11:49 +000091By installing the `PyObjc Objective-C bridge
Georg Brandlfa55a312014-10-29 09:24:54 +010092<https://pythonhosted.org/pyobjc/>`_, Python programs can use Mac OS X's
Ned Deily4624b002014-04-12 09:31:28 -070093Cocoa libraries.
Georg Brandl6728c5a2009-10-11 18:31:23 +000094
95:ref:`Pythonwin <windows-faq>` by Mark Hammond includes an interface to the
Andrew M. Kuchling5c4e6eb2009-10-13 16:11:49 +000096Microsoft Foundation Classes and a Python programming environment
97that's written mostly in Python using the MFC classes.
Georg Brandl6728c5a2009-10-11 18:31:23 +000098
99
100Tkinter questions
101=================
102
103How do I freeze Tkinter applications?
104-------------------------------------
105
106Freeze is a tool to create stand-alone applications. When freezing Tkinter
107applications, the applications will not be truly stand-alone, as the application
108will still need the Tcl and Tk libraries.
109
Andrew M. Kuchling5c4e6eb2009-10-13 16:11:49 +0000110One solution is to ship the application with the Tcl and Tk libraries, and point
Georg Brandl6728c5a2009-10-11 18:31:23 +0000111to them at run-time using the :envvar:`TCL_LIBRARY` and :envvar:`TK_LIBRARY`
112environment variables.
113
114To get truly stand-alone applications, the Tcl scripts that form the library
115have to be integrated into the application as well. One tool supporting that is
116SAM (stand-alone modules), which is part of the Tix distribution
Andrew M. Kuchling5c4e6eb2009-10-13 16:11:49 +0000117(http://tix.sourceforge.net/).
118
119Build Tix with SAM enabled, perform the appropriate call to
Sandro Tosi98ed08f2012-01-14 16:42:02 +0100120:c:func:`Tclsam_init`, etc. inside Python's
Andrew M. Kuchling5c4e6eb2009-10-13 16:11:49 +0000121:file:`Modules/tkappinit.c`, and link with libtclsam and libtksam (you
122might include the Tix libraries as well).
Georg Brandl6728c5a2009-10-11 18:31:23 +0000123
124
125Can I have Tk events handled while waiting for I/O?
126---------------------------------------------------
127
128Yes, and you don't even need threads! But you'll have to restructure your I/O
Sandro Tosi98ed08f2012-01-14 16:42:02 +0100129code a bit. Tk has the equivalent of Xt's :c:func:`XtAddInput()` call, which allows you
Georg Brandl6728c5a2009-10-11 18:31:23 +0000130to register a callback function which will be called from the Tk mainloop when
131I/O is possible on a file descriptor. Here's what you need::
132
133 from Tkinter import tkinter
134 tkinter.createfilehandler(file, mask, callback)
135
136The file may be a Python file or socket object (actually, anything with a
137fileno() method), or an integer file descriptor. The mask is one of the
138constants tkinter.READABLE or tkinter.WRITABLE. The callback is called as
139follows::
140
141 callback(file, mask)
142
143You must unregister the callback when you're done, using ::
144
145 tkinter.deletefilehandler(file)
146
147Note: since you don't know *how many bytes* are available for reading, you can't
148use the Python file object's read or readline methods, since these will insist
149on reading a predefined number of bytes. For sockets, the :meth:`recv` or
150:meth:`recvfrom` methods will work fine; for other files, use
151``os.read(file.fileno(), maxbytecount)``.
152
153
154I can't get key bindings to work in Tkinter: why?
155-------------------------------------------------
156
157An often-heard complaint is that event handlers bound to events with the
158:meth:`bind` method don't get handled even when the appropriate key is pressed.
159
160The most common cause is that the widget to which the binding applies doesn't
161have "keyboard focus". Check out the Tk documentation for the focus command.
162Usually a widget is given the keyboard focus by clicking in it (but not for
163labels; see the takefocus option).
164
165
166