Issue #22155: Add File Handlers subsection with createfilehandler to Tkinter

doc.  Remove obsolete example from FAQ.  Patch by Martin Panter.

diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst
index 5e1d8beafd6e0590ac1f28b665f5a318a96d22f6..44e5908474b4e4de40668a2e12f52842e4561386 100644 (file)
--- a/Doc/faq/gui.rst
+++ b/Doc/faq/gui.rst
@@ -125,30 +125,11 @@ might include the Tix libraries as well).
 Can I have Tk events handled while waiting for I/O?
 ---------------------------------------------------
 
-Yes, and you don't even need threads!  But you'll have to restructure your I/O
+On platforms other than Windows, yes, and you don't even
+need threads!  But you'll have to restructure your I/O
 code a bit.  Tk has the equivalent of Xt's :c:func:`XtAddInput()` call, which allows you
 to register a callback function which will be called from the Tk mainloop when
-I/O is possible on a file descriptor.  Here's what you need::
-
-   from Tkinter import tkinter
-   tkinter.createfilehandler(file, mask, callback)
-
-The file may be a Python file or socket object (actually, anything with a
-fileno() method), or an integer file descriptor.  The mask is one of the
-constants tkinter.READABLE or tkinter.WRITABLE.  The callback is called as
-follows::
-
-   callback(file, mask)
-
-You must unregister the callback when you're done, using ::
-
-   tkinter.deletefilehandler(file)
-
-Note: since you don't know *how many bytes* are available for reading, you can't
-use the Python file object's read or readline methods, since these will insist
-on reading a predefined number of bytes.  For sockets, the :meth:`recv` or
-:meth:`recvfrom` methods will work fine; for other files, use
-``os.read(file.fileno(), maxbytecount)``.
+I/O is possible on a file descriptor.  See :ref:`tkinter-file-handlers`.
 
 
 I can't get key bindings to work in Tkinter: why?

diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
index 846f96e1a103d9e3a1ee11e9a920b9d9c295dd9d..fa60c154f6360a6738a7c53e18915ddcbf0a6387 100644 (file)
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -817,3 +817,53 @@ reference to the image. When the last Python reference to the image object is
 deleted, the image data is deleted as well, and Tk will display an empty box
 wherever the image was used.
 
+
+.. _tkinter-file-handlers:
+
+File Handlers
+-------------
+
+Tk allows you to register and unregister a callback function which will be
+called from the Tk mainloop when I/O is possible on a file descriptor.
+Only one handler may be registered per file descriptor. Example code::
+
+   import Tkinter
+   widget = Tkinter.Tk()
+   mask = Tkinter.READABLE | Tkinter.WRITABLE
+   widget.tk.createfilehandler(file, mask, callback)
+   ...
+   widget.tk.deletefilehandler(file)
+
+This feature is not available on Windows.
+
+Since you don't know how many bytes are available for reading, you may not
+want to use the :class:`~io.BufferedIOBase` or :class:`~io.TextIOBase`
+:meth:`~io.BufferedIOBase.read` or :meth:`~io.IOBase.readline` methods,
+since these will insist on reading a predefined number of bytes.
+For sockets, the :meth:`~socket.socket.recv` or
+:meth:`~socket.socket.recvfrom` methods will work fine; for other files,
+use raw reads or ``os.read(file.fileno(), maxbytecount)``.
+
+
+.. method:: Widget.tk.createfilehandler(file, mask, func)
+
+   Registers the file handler callback function *func*. The *file* argument
+   may either be an object with a :meth:`~io.IOBase.fileno` method (such as
+   a file or socket object), or an integer file descriptor. The *mask*
+   argument is an ORed combination of any of the three constants below.
+   The callback is called as follows::
+
+      callback(file, mask)
+
+
+.. method:: Widget.tk.deletefilehandler(file)
+
+   Unregisters a file handler.
+
+
+.. data:: READABLE
+          WRITABLE
+          EXCEPTION
+
+   Constants used in the *mask* arguments.
+

diff --git a/Misc/NEWS b/Misc/NEWS
index 05d609da3fa1db877b41fbe054846c1313643afa..ab36ec45a954d40ac81ccf7ae1108a5f752c82f9 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -30,6 +30,12 @@ IDLE
 
 - Issue #15809: IDLE shell now uses locale encoding instead of Latin1 for
   decoding unicode literals.
+  
+Documentation
+-------------
+
+- Issue #22155: Add File Handlers subsection with createfilehandler to Tkinter
+  doc.  Remove obsolete example from FAQ.  Patch by Martin Panter.
 
 
 What's New in Python 2.7.10 release candidate 1?