bpo-25237: Documentation for tkinter modules (GH-1870)

This commit is contained in:
Nikhil 2019-09-10 01:55:34 -07:00 committed by Julien Palard
parent 0711642eec
commit 80428ed4e1
10 changed files with 481 additions and 17 deletions

230
Doc/library/dialog.rst Normal file
View File

@ -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`

View File

@ -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

BIN
Doc/library/tk_msg.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 19 KiB

View File

@ -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

View File

@ -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`

View File

@ -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.

View File

@ -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)

View File

@ -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.

View File

@ -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:
.. attribute:: ScrolledText.frame
The frame which surrounds the text and scroll bar widgets.
.. class:: ScrolledText(master=None, **kw)
.. attribute:: ScrolledText.vbar
.. attribute:: frame
The scroll bar widget.
The frame which surrounds the text and scroll bar widgets.
.. attribute:: vbar
The scroll bar widget.

View File

@ -0,0 +1 @@
Add documentation for tkinter modules