bpo-25237: Documentation for tkinter modules (GH-1870)
This commit is contained in:
parent
0711642eec
commit
80428ed4e1
|
@ -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`
|
|
@ -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
|
Binary file not shown.
After Width: | Height: | Size: 19 KiB |
|
@ -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
|
|
@ -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`
|
|
@ -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.
|
|
@ -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)
|
|
@ -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.
|
|
@ -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.
|
||||
|
|
|
@ -0,0 +1 @@
|
|||
Add documentation for tkinter modules
|
Loading…
Reference in New Issue