From 8642f781ae27a499b679fb470fba1a06dd9b4348 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 21 Jun 2026 17:42:41 +0300 Subject: [PATCH] gh-86726: Document tkinter.simpledialog query options and Dialog.result --- Doc/library/dialog.rst | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst index 952fd1f0783671c..402cfcfe75369f8 100644 --- a/Doc/library/dialog.rst +++ b/Doc/library/dialog.rst @@ -15,16 +15,31 @@ 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) +.. function:: askfloat(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None) + askinteger(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None) + askstring(title, prompt, *, initialvalue=None, show=None, parent=None) - The above three functions provide dialogs that prompt the user to enter a value - of the desired type. + Prompt the user to enter a value of the desired type and return it, or + ``None`` if the dialog is cancelled. + + *title* is the dialog title and *prompt* the message shown above the entry. + *initialvalue* is the value initially placed in the entry. + *parent* is the window over which the dialog is shown. + :func:`askinteger` and :func:`askfloat` also accept *minvalue* and + *maxvalue*, which bound the accepted value. + :func:`askstring` also accepts *show*, a character used to mask the entered + text, for example ``'*'`` to hide a password. .. class:: Dialog(parent, title=None) The base class for custom dialogs. + Instantiating it shows the dialog modally and returns once the user closes + it; the entered value is then available in the :attr:`!result` attribute. + + .. attribute:: result + + The value produced by :meth:`apply`, or ``None`` if the dialog was + cancelled. .. method:: body(master) @@ -46,7 +61,8 @@ functions for creating simple modal dialogs to get a value from the user. .. method:: apply() - Process the data entered by the user. + Process the data entered by the user, for example by storing it in the + :attr:`!result` attribute. Called after :meth:`validate` succeeds and just before the dialog is destroyed. The default implementation does nothing; override it to act on or store