Dialogs

This page contains things for asking the user things like file names and colors. If you want to display a custom dialog, create a Window, add some stuff to it and use wait_window().

Note

All functions documented on this page take a parent keyword argument. Use that whenever you are calling the functions from a program that has another window. This way the dialog will look like it belongs to that parent window.

Message Boxes

These functions call tk_messageBox(3tk). Options are passed to tk_messageBox(3tk) so that this code…

teek.dialog.ok_cancel("Question", "Do you want that?")

…does a Tcl call like this:

tk_messageBox -type okcancel -title "Question" -message "Do you want that?" -icon question

teek.dialog.info(title, message, detail=None, **kwargs)

teek.dialog.warning(title, message, detail=None, **kwargs)

teek.dialog.error(title, message, detail=None, **kwargs)

Each of these functions shows a message box that has an “ok” button. The icon option is 'info', 'warning' or 'error' respectively. These functions always return None.

teek.dialog.ok_cancel(title, message, detail=None, **kwargs)

Shows a message box with “ok” and “cancel” buttons. The icon is 'question' by default, but you can change it by passing a keyword argument, e.g. icon='warning'. Returns True if “ok” is clicked, and False if “cancel” is clicked.

teek.dialog.retry_cancel(title, message, detail=None, **kwargs)

Like ok_cancel(), but with a “retry” button instead of an “ok” button and 'warning' as the default icon.

teek.dialog.yes_no(title, message, detail=None, **kwargs)

Shows a message box with “yes” and “no” buttons. The icon is 'question' by default. Returns True for “yes” and False for “no”.

teek.dialog.yes_no_cancel(title, message, detail=None, **kwargs)

Shows a message box with “yes”, “no” and “cancel” buttons. The icon is 'question' by default. Returns one of the strings 'yes', 'no' or 'cancel'.

teek.dialog.abort_retry_ignore(title, message, detail=None, **kwargs)

Like yes_no_cancel(), but with different buttons and return value strings. The icon is 'error' by default.

File and Directory Dialogs

Keyword arguments work as usual. Note that paths are returned as strings of absolute paths, not e.g. pathlib.Path objects.

teek.dialog.open_file(**kwargs)

Ask the user to choose an existing file. Returns the path.

This calls tk_getOpenFile(3tk) without -multiple. None is returned if the user cancels.

teek.dialog.open_multiple_files(**kwargs)

Ask the user to choose one or more existing files. Returns a list of paths.

This calls tk_getOpenFile(3tk) with -multiple set to true. An empty list is returned if the user cancels.

teek.dialog.save_file(**kwargs)

Ask the user to choose a path for a new file. Return the path.

This calls tk_getSaveFile(3tk), and returns None if the user cancels.

teek.dialog.directory(**kwargs)

Asks the user to choose a directory, and return a path to it.

This calls tk_chooseDirectory(3tk), and returns None if the user cancels.

Note

By default, the user can choose a directory that doesn’t exist yet. This behaviour is documented in tk_chooseDirectory(3tk). If you want the user to choose an existing directory, use mustexist=True.

Other Dialogs

teek.dialog.color(**kwargs)

Calls tk_chooseColor(3tk).

The color selected by the user is returned, or None if the user cancelled the dialog.