[Python-checkins] bpo-25237: Documentation for tkinter modules (GH-1870)
Julien Palard
webhook-mailer at python.org
Tue Sep 10 04:55:38 EDT 2019
https://github.com/python/cpython/commit/80428ed4e19b31071433806b4d89465c88e084c6
commit: 80428ed4e19b31071433806b4d89465c88e084c6
branch: master
author: Nikhil <12703092+patel-nikhil at users.noreply.github.com>
committer: Julien Palard <julien at palard.fr>
date: 2019-09-10T10:55:34+02:00
summary:
bpo-25237: Documentation for tkinter modules (GH-1870)
files:
A Doc/library/dialog.rst
A Doc/library/tk_msg.png
A Doc/library/tkinter.colorchooser.rst
A Doc/library/tkinter.dnd.rst
A Doc/library/tkinter.font.rst
A Doc/library/tkinter.messagebox.rst
A Misc/NEWS.d/next/Documentation/2018-06-02-12-55-23.bpo-25237.m8-JMu.rst
M Doc/library/tk.rst
M Doc/library/tkinter.rst
M Doc/library/tkinter.scrolledtext.rst
diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst
new file mode 100644
index 000000000000..836f66296337
--- /dev/null
+++ b/Doc/library/dialog.rst
@@ -0,0 +1,230 @@
+Tkinter Dialogs
+===============
+
+:mod:`tkinter.simpledialog` --- Standard Tkinter input dialogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. module:: tkinter.simpledialog
+ :platform: Tk
+ :synopsis: Simple dialog windows
+
+**Source code:** :source:`Lib/tkinter/simpledialog.py`
+
+--------------
+
+The :mod:`tkinter.simpledialog` module contains convenience classes and
+functions for creating simple modal dialogs to get a value from the user.
+
+
+.. function:: askfloat(title, prompt, **kw)
+ askinteger(title, prompt, **kw)
+ askstring(title, prompt, **kw)
+
+ The above three functions provide dialogs that prompt the user to enter a value
+ of the desired type.
+
+.. class:: Dialog(parent, title=None)
+
+ The base class for custom dialogs.
+
+ .. method:: body(master)
+
+ Override to construct the dialog's interface and return the widget that
+ should have initial focus.
+
+ .. method:: buttonbox()
+
+ Default behaviour adds OK and Cancel buttons. Override for custom button
+ layouts.
+
+
+
+:mod:`tkinter.filedialog` --- File selection dialogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. module:: tkinter.filedialog
+ :platform: Tk
+ :synopsis: Dialog classes for file selection
+
+**Source code:** :source:`Lib/tkinter/filedialog.py`
+
+--------------
+
+The :mod:`tkinter.filedialog` module provides classes and factory functions for
+creating file/directory selection windows.
+
+Native Load/Save Dialogs
+------------------------
+
+The following classes and functions provide file dialog windows that combine a
+native look-and-feel with configuration options to customize behaviour.
+The following keyword arguments are applicable to the classes and functions
+listed below:
+
+ | *parent* - the window to place the dialog on top of
+
+ | *title* - the title of the window
+
+ | *initialdir* - the directory that the dialog starts in
+
+ | *initialfile* - the file selected upon opening of the dialog
+
+ | *filetypes* - a sequence of (label, pattern) tuples, '*' wildcard is allowed
+
+ | *defaultextension* - default extension to append to file (save dialogs)
+
+ | *multiple* - when True, selection of multiple items is allowed
+
+
+**Static factory functions**
+
+The below functions when called create a modal, native look-and-feel dialog,
+wait for the user's selection, then return the selected value(s) or ``None`` to the
+caller.
+
+.. function:: askopenfile(mode="r", **options)
+ askopenfiles(mode="r", **options)
+
+ The above two functions create an :class:`Open` dialog and return the opened
+ file object(s) in read-only mode.
+
+.. function:: asksaveasfile(mode="w", **options)
+
+ Create a :class:`SaveAs` dialog and return a file object opened in write-only mode.
+
+.. function:: askopenfilename(**options)
+ askopenfilenames(**options)
+
+ The above two functions create an :class:`Open` dialog and return the
+ selected filename(s) that correspond to existing file(s).
+
+.. function:: asksaveasfilename(**options)
+
+ Create a :class:`SaveAs` dialog and return the selected filename.
+
+.. function:: askdirectory(**options)
+
+ | Prompt user to select a directory.
+ | Additional keyword option:
+ | *mustexist* - determines if selection must be an existing directory.
+
+.. class:: Open(master=None, **options)
+ SaveAs(master=None, **options)
+
+ The above two classes provide native dialog windows for saving and loading
+ files.
+
+**Convenience classes**
+
+The below classes are used for creating file/directory windows from scratch.
+These do not emulate the native look-and-feel of the platform.
+
+.. class:: Directory(master=None, **options)
+
+ Create a dialog prompting the user to select a directory.
+
+.. note:: The *FileDialog* class should be subclassed for custom event
+ handling and behaviour.
+
+.. class:: FileDialog(master, title=None)
+
+ Create a basic file selection dialog.
+
+ .. method:: cancel_command(event=None)
+
+ Trigger the termination of the dialog window.
+
+ .. method:: dirs_double_event(event)
+
+ Event handler for double-click event on directory.
+
+ .. method:: dirs_select_event(event)
+
+ Event handler for click event on directory.
+
+ .. method:: files_double_event(event)
+
+ Event handler for double-click event on file.
+
+ .. method:: files_select_event(event)
+
+ Event handler for single-click event on file.
+
+ .. method:: filter_command(event=None)
+
+ Filter the files by directory.
+
+ .. method:: get_filter()
+
+ Retrieve the file filter currently in use.
+
+ .. method:: get_selection()
+
+ Retrieve the currently selected item.
+
+ .. method:: go(dir_or_file=os.curdir, pattern="*", default="", key=None)
+
+ Render dialog and start event loop.
+
+ .. method:: ok_event(event)
+
+ Exit dialog returning current selection.
+
+ .. method:: quit(how=None)
+
+ Exit dialog returning filename, if any.
+
+ .. method:: set_filter(dir, pat)
+
+ Set the file filter.
+
+ .. method:: set_selection(file)
+
+ Update the current file selection to *file*.
+
+
+.. class:: LoadFileDialog(master, title=None)
+
+ A subclass of FileDialog that creates a dialog window for selecting an
+ existing file.
+
+ .. method:: ok_command()
+
+ Test that a file is provided and that the selection indicates an
+ already existing file.
+
+.. class:: SaveFileDialog(master, title=None)
+
+ A subclass of FileDialog that creates a dialog window for selecting a
+ destination file.
+
+ .. method:: ok_command()
+
+ Test whether or not the selection points to a valid file that is not a
+ directory. Confirmation is required if an already existing file is
+ selected.
+
+:mod:`tkinter.commondialog` --- Dialog window templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. module:: tkinter.commondialog
+ :platform: Tk
+ :synopsis: Tkinter base class for dialogs
+
+**Source code:** :source:`Lib/tkinter/commondialog.py`
+
+--------------
+
+The :mod:`tkinter.commondialog` module provides the :class:`Dialog` class that
+is the base class for dialogs defined in other supporting modules.
+
+.. class:: Dialog(master=None, **options)
+
+ .. method:: show(color=None, **options)
+
+ Render the Dialog window.
+
+
+.. seealso::
+
+ Modules :mod:`tkinter.messagebox`, :ref:`tut-files`
\ No newline at end of file
diff --git a/Doc/library/tk.rst b/Doc/library/tk.rst
index 95cd1c7712e7..c6c73f057cab 100644
--- a/Doc/library/tk.rst
+++ b/Doc/library/tk.rst
@@ -33,14 +33,17 @@ alternatives, see the :ref:`other-gui-packages` section.
.. toctree::
tkinter.rst
+ tkinter.colorchooser.rst
+ tkinter.font.rst
+ dialog.rst
+ tkinter.messagebox.rst
+ tkinter.scrolledtext.rst
+ tkinter.dnd.rst
tkinter.ttk.rst
tkinter.tix.rst
- tkinter.scrolledtext.rst
idle.rst
othergui.rst
.. Other sections I have in mind are
Tkinter internals
- Freezing Tkinter applications
-
-
+ Freezing Tkinter applications
\ No newline at end of file
diff --git a/Doc/library/tk_msg.png b/Doc/library/tk_msg.png
new file mode 100644
index 000000000000..c122d8f8ae5b
Binary files /dev/null and b/Doc/library/tk_msg.png differ
diff --git a/Doc/library/tkinter.colorchooser.rst b/Doc/library/tkinter.colorchooser.rst
new file mode 100644
index 000000000000..60f4d707270d
--- /dev/null
+++ b/Doc/library/tkinter.colorchooser.rst
@@ -0,0 +1,29 @@
+:mod:`tkinter.colorchooser` --- Color choosing dialog
+=====================================================
+
+.. module:: tkinter.colorchooser
+ :platform: Tk
+ :synopsis: Color choosing dialog
+
+**Source code:** :source:`Lib/tkinter/colorchooser.py`
+
+--------------
+
+The :mod:`tkinter.colorchooser` module provides the :class:`Chooser` class
+as an interface to the native color picker dialog. ``Chooser`` implements
+a modal color choosing dialog window. The ``Chooser`` class inherits from
+the :class:`~tkinter.commondialog.Dialog` class.
+
+.. class:: Chooser(master=None, **options)
+
+.. function:: askcolor(color=None, **options)
+
+ Create a color choosing dialog. A call to this method will show the window,
+ wait for the user to make a selection, and return the selected color (or
+ ``None``) to the caller.
+
+
+.. seealso::
+
+ Module :mod:`tkinter.commondialog`
+ Tkinter standard dialog module
\ No newline at end of file
diff --git a/Doc/library/tkinter.dnd.rst b/Doc/library/tkinter.dnd.rst
new file mode 100644
index 000000000000..6c11c739e1fa
--- /dev/null
+++ b/Doc/library/tkinter.dnd.rst
@@ -0,0 +1,64 @@
+:mod:`tkinter.dnd` --- Drag and drop support
+============================================
+
+.. module:: tkinter.dnd
+ :platform: Tk
+ :synopsis: Tkinter drag-and-drop interface
+
+**Source code:** :source:`Lib/tkinter/dnd.py`
+
+--------------
+
+.. note:: This is experimental and due to be deprecated when it is replaced
+ with the Tk DND.
+
+The :mod:`tkinter.dnd` module provides drag-and-drop support for objects within
+a single application, within the same window or between windows. To enable an
+object to be dragged, you must create an event binding for it that starts the
+drag-and-drop process. Typically, you bind a ButtonPress event to a callback
+function that you write (see :ref:`Bindings-and-Events`). The function should
+call :func:`dnd_start`, where 'source' is the object to be dragged, and 'event'
+is the event that invoked the call (the argument to your callback function).
+
+Selection of a target object occurs as follows:
+
+#. Top-down search of area under mouse for target widget
+
+ * Target widget should have a callable *dnd_accept* attribute
+ * If *dnd_accept* is not present or returns None, search moves to parent widget
+ * If no target widget is found, then the target object is None
+
+2. Call to *<old_target>.dnd_leave(source, event)*
+#. Call to *<new_target>.dnd_enter(source, event)*
+#. Call to *<target>.dnd_commit(source, event)* to notify of drop
+#. Call to *<source>.dnd_end(target, event)* to signal end of drag-and-drop
+
+
+.. class:: DndHandler(source, event)
+
+ The *DndHandler* class handles drag-and-drop events tracking Motion and
+ ButtonRelease events on the root of the event widget.
+
+ .. method:: cancel(event=None)
+
+ Cancel the drag-and-drop process.
+
+ .. method:: finish(event, commit=0)
+
+ Execute end of drag-and-drop functions.
+
+ .. method:: on_motion(event)
+
+ Inspect area below mouse for target objects while drag is performed.
+
+ .. method:: on_release(event)
+
+ Signal end of drag when the release pattern is triggered.
+
+.. function:: dnd_start(source, event)
+
+ Factory function for drag-and-drop process.
+
+.. seealso::
+
+ :ref:`Bindings-and-Events`
\ No newline at end of file
diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst
new file mode 100644
index 000000000000..30c1e7b5f9eb
--- /dev/null
+++ b/Doc/library/tkinter.font.rst
@@ -0,0 +1,96 @@
+:mod:`tkinter.font` --- Tkinter font wrapper
+============================================
+
+.. module:: tkinter.font
+ :platform: Tk
+ :synopsis: Tkinter font-wrapping class
+
+**Source code:** :source:`Lib/tkinter/font.py`
+
+--------------
+
+The :mod:`tkinter.font` module provides the :class:`Font` class for creating
+and using named fonts.
+
+The different font weights and slants are:
+
+.. data:: NORMAL
+ BOLD
+ ITALIC
+ ROMAN
+
+.. class:: Font(root=None, font=None, name=None, exists=False, **options)
+
+ The :class:`Font` class represents a named font. *Font* instances are given
+ unique names and can be specified by their family, size, and style
+ configuration. Named fonts are Tk's method of creating and identifying
+ fonts as a single object, rather than specifying a font by its attributes
+ with each occurrence.
+
+ arguments:
+
+ | *font* - font specifier tuple (family, size, options)
+ | *name* - unique font name
+ | *exists* - self points to existing named font if true
+
+ additional keyword options (ignored if *font* is specified):
+
+ | *family* - font family i.e. Courier, Times
+ | *size* - font size
+ | If *size* is positive it is interpreted as size in points.
+ | If *size* is a negative number its absolute value is treated as
+ as size in pixels.
+ | *weight* - font emphasis (NORMAL, BOLD)
+ | *slant* - ROMAN, ITALIC
+ | *underline* - font underlining (0 - none, 1 - underline)
+ | *overstrike* - font strikeout (0 - none, 1 - strikeout)
+
+ .. method:: actual(option=None, displayof=None)
+
+ Return the attributes of the font.
+
+ .. method:: cget(option)
+
+ Retrieve an attribute of the font.
+
+ .. method:: config(**options)
+
+ Modify attributes of the font.
+
+ .. method:: copy()
+
+ Return new instance of the current font.
+
+ .. method:: measure(text, displayof=None)
+
+ Return amount of space the text would occupy on the specified display
+ when formatted in the current font. If no display is specified then the
+ main application window is assumed.
+
+ .. method:: metrics(*options, **kw)
+
+ Return font-specific data.
+ Options include:
+
+ *ascent* - distance between baseline and highest point that a
+ character of the font can occupy
+
+ *descent* - distance between baseline and lowest point that a
+ character of the font can occupy
+
+ *linespace* - minimum vertical separation necessary between any two
+ characters of the font that ensures no vertical overlap between lines.
+
+ *fixed* - 1 if font is fixed-width else 0
+
+.. function:: families(root=None, displayof=None)
+
+ Return the different font families.
+
+.. function:: names(root=None)
+
+ Return the names of defined fonts.
+
+.. function:: nametofont(name)
+
+ Return a :class:`Font` representation of a tk named font.
\ No newline at end of file
diff --git a/Doc/library/tkinter.messagebox.rst b/Doc/library/tkinter.messagebox.rst
new file mode 100644
index 000000000000..872e72f7a7e2
--- /dev/null
+++ b/Doc/library/tkinter.messagebox.rst
@@ -0,0 +1,39 @@
+:mod:`tkinter.messagebox` --- Tkinter message prompts
+=====================================================
+
+.. module:: tkinter.messagebox
+ :platform: Tk
+ :synopsis: Various types of alert dialogs
+
+**Source code:** :source:`Lib/tkinter/messagebox.py`
+
+--------------
+
+The :mod:`tkinter.messagebox` module provides a template base class as well as
+a variety of convenience methods for commonly used configurations. The message
+boxes are modal and will return a subset of (True, False, OK, None, Yes, No) based on
+the user's selection. Common message box styles and layouts include but are not
+limited to:
+
+.. figure:: tk_msg.png
+
+.. class:: Message(master=None, **options)
+
+ Create a default information message box.
+
+**Information message box**
+
+.. method:: showinfo(title=None, message=None, **options)
+
+**Warning message boxes**
+
+.. method:: showwarning(title=None, message=None, **options)
+ showerror(title=None, message=None, **options)
+
+**Question message boxes**
+
+.. method:: askquestion(title=None, message=None, **options)
+ askokcancel(title=None, message=None, **options)
+ askretrycancel(title=None, message=None, **options)
+ askyesno(title=None, message=None, **options)
+ askyesnocancel(title=None, message=None, **options)
\ No newline at end of file
diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
index e1fc051d9597..2dc44ad36a7f 100644
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -109,9 +109,6 @@ Or, more often::
Other modules that provide Tk support include:
-:mod:`tkinter.scrolledtext`
- Text widget with a vertical scroll bar built in.
-
:mod:`tkinter.colorchooser`
Dialog to let the user choose a color.
@@ -127,6 +124,9 @@ Other modules that provide Tk support include:
:mod:`tkinter.messagebox`
Access to standard Tk dialog boxes.
+:mod:`tkinter.scrolledtext`
+ Text widget with a vertical scroll bar built in.
+
:mod:`tkinter.simpledialog`
Basic dialogs and convenience functions.
@@ -680,9 +680,10 @@ scrollcommand
This is almost always the :meth:`!set` method of some scrollbar widget, but can
be any widget method that takes a single argument.
-wrap:
+wrap
Must be one of: ``"none"``, ``"char"``, or ``"word"``.
+.. _Bindings-and-Events:
Bindings and Events
^^^^^^^^^^^^^^^^^^^
@@ -860,4 +861,4 @@ use raw reads or ``os.read(file.fileno(), maxbytecount)``.
WRITABLE
EXCEPTION
- Constants used in the *mask* arguments.
+ Constants used in the *mask* arguments.
\ No newline at end of file
diff --git a/Doc/library/tkinter.scrolledtext.rst b/Doc/library/tkinter.scrolledtext.rst
index 138720e4785f..d20365baa386 100644
--- a/Doc/library/tkinter.scrolledtext.rst
+++ b/Doc/library/tkinter.scrolledtext.rst
@@ -14,8 +14,7 @@
The :mod:`tkinter.scrolledtext` module provides a class of the same name which
implements a basic text widget which has a vertical scroll bar configured to do
the "right thing." Using the :class:`ScrolledText` class is a lot easier than
-setting up a text widget and scroll bar directly. The constructor is the same
-as that of the :class:`tkinter.Text` class.
+setting up a text widget and scroll bar directly.
The text widget and scrollbar are packed together in a :class:`Frame`, and the
methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired
@@ -25,12 +24,14 @@ be used directly to achieve most normal geometry management behavior.
Should more specific control be necessary, the following attributes are
available:
+.. class:: ScrolledText(master=None, **kw)
-.. attribute:: ScrolledText.frame
- The frame which surrounds the text and scroll bar widgets.
+ .. attribute:: frame
+ The frame which surrounds the text and scroll bar widgets.
-.. attribute:: ScrolledText.vbar
- The scroll bar widget.
+ .. attribute:: vbar
+
+ The scroll bar widget.
diff --git a/Misc/NEWS.d/next/Documentation/2018-06-02-12-55-23.bpo-25237.m8-JMu.rst b/Misc/NEWS.d/next/Documentation/2018-06-02-12-55-23.bpo-25237.m8-JMu.rst
new file mode 100644
index 000000000000..5778f377aeaf
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-06-02-12-55-23.bpo-25237.m8-JMu.rst
@@ -0,0 +1 @@
+Add documentation for tkinter modules
More information about the Python-checkins
mailing list