[Python-checkins] cpython (2.7): Issue #22155: Add File Handlers subsection with createfilehandler to Tkinter

[terry.reedy]

https://hg.python.org/cpython/rev/e8dd65c7fb6b
changeset:   96118:e8dd65c7fb6b
branch:      2.7
parent:      96113:247f003b42ea
user:        Terry Jan Reedy <tjreedy at udel.edu>
date:        Sun May 17 14:49:20 2015 -0400
summary:
  Issue #22155: Add File Handlers subsection with createfilehandler to Tkinter
doc.  Remove obsolete example from FAQ.  Patch by Martin Panter.

files:
  Doc/faq/gui.rst         |  25 +------------
  Doc/library/tkinter.rst |  50 +++++++++++++++++++++++++++++
  Misc/NEWS               |   6 +++
  3 files changed, 59 insertions(+), 22 deletions(-)


diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst
--- a/Doc/faq/gui.rst
+++ b/Doc/faq/gui.rst
@@ -125,30 +125,11 @@
 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
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -817,3 +817,53 @@
 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
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -30,6 +30,12 @@
 
 - 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?

-- 
Repository URL: https://hg.python.org/cpython