Module tktools - Tk Convenience Functions

Overview

This module is not available to Knowbot Programs.

The tktools module contains assorted Tk-related subroutines used in some of the user interface tools. This module was borrowed from the Grail project, even though only a small fraction of the utilities are used for the KOE.

Use of tktools as a 'higher-level' toolkit, is a way of creating compound widgets using one or more of the generic Tk widgets in a consistent uniform way throughout all the graphical applications. Tktools provides functions that wrap many of the common and repeated idioms used when writing programs that use Tk.

Functions

install_keybindings(root)

Installs some common key bindings to various Tk widgets. Currently it only installs Control-U on an Entry to clear the field from the beginning of the field to the insertion point.

make_toplevel (master[, title[, class_]]) -> Toplevel instance

Create a Toplevel widget. This is a shortcut for a Toplevel() instantiation plus calls to set the title and icon name of the widget.

set_transient (widget, master, ... )

Make an existing toplevel widget transient for a master. The widget must exist but should not yet have been placed; in other words, this should be called after creating all the subwidgets but before letting the user see the window on the display.

widget: Tk Toplevel object to be made transient.
master: Tk Toplevel object which will become the master of the newly transient widget window.
relx=0.5: Relative X coordinate adjustment.
rely=0.3: Relative Y coordinate adjustment.
expose=1: Boolean indicating whether the newly transient window should be exposed before returning to the caller.

make_scrollbars (master, hbar, vbar, ... ) -> (hbar, vbar, Frame instance)

Subroutine to create a frame with scrollbars. This is used by make_text_box() and similar routines.

Note: the caller is responsible for setting the x/y scroll command properties (e.g., by calling set_scroll_commands()).

Return a tuple containing the hbar, the vbar, and the frame, where hbar and vbar are None if not requested.

master: Parent widget.
hbar: Boolean indicating whether the horizontal scrollbar should be made.
vbar: Boolean indicating whether the vertical scrollbar should be made.
pack=1: Boolean indicating whether the containing frame should be packed.
class_=None: Class name for the containing frame object. If omitted, the default value 'Frame' will be provided by Tk.
name=None: Name of the containing frame widget. If omitted, a generated name will be used.
takefocus=0: Tk boolean value of None. If None, the scrollbars will get the Tk default value for their takefocus parameter, otherwise the value passed to this make_scrollbars() will be used.

set_scroll_commands (widget, hbar, vbar)

Link a scrollable widget to its scroll bars. The scroll bars may be empty.

widget: Scrollable widget; this may be any widget which corresponds to the standard Tk scrolling protocol.
hbar: Horizontal scrollbar; if this is a false value, scrolling will no be configured, with the expectation being that false values are not widgets.
vbar: Vertical scrollbar; if a false value is passed, scrolling will not be configured.

make_text_box (master, ... ) -> (Text instance, Frame instance)

Creates a text box with optional horizontal and vertical scrollbars.

master: Parent widget.
width=0: Width of the text widget.
height=0: Height of the text widget created.
font=None: Font for the new text widget. The default uses the Tk default for the widget.
wrap=Tkinter.WORD: Word-wrapping setting for the created widget (CHAR, NONE, or WORD).
class_=None: Class name for the Frame object in which the text widget and scrollbars are packed. This can be used with X11 resources and the Tk "option" database.
name=None: Name of the Frame widget in which the text and scrollbar widgets are packed. The subwidgets are named text, hbar, and vbar.
takefocus=None: Value to be passed as the takefocus parameter for the set_scroll_commands() method when binding scroll commands for the widgets.
hbar=0: Boolean indicating whether the horizontal scrollbar should be created.
vbar=1: Boolean indicating whether the vertical scrollbar should be created.
pack=1: Boolean indicating whether the new widget should be packed.
fill=Tkinter.BOTH
expand=1: Packing options for the created widgets.

make_list_box (master, ... ) -> (Listbox instance, Frame instance)

Subroutine to create a list box. Like make_text_box(), but without support for the wrap keyword parameter.

make_canvas (master, ...) -> (Canvas instance, Frame instance)

Subroutine to create a canvas. Like make_text_box(), but without support for the wrap keyword parameter.

make_form_entry (master, label [, borderwidth]) -> (Entry instance, Frame instance)

Subroutine to create a form entry. This creates three widgets:

a horizontally filling and expanding frame, containing:
- a label on the left, and
- a text entry on the right.

master: Parent widget.
label: Text of the new label widget.
borderwidth=None: Width of the relief border for the new entry widget. If omitted, the Tk default is used.

make_labeled_form_entry (master, label, ... ) -> (Entry or Text instance, Frame instance, Label instance)

Another subroutine to create a form entry. This is a slightly modified version of make_form_entry(). This version does the proper alighnment of labels with their fields. It should probably eventually replace make_form_entry() altogether.

The one annoying bug is that the text entry field should be expandable while still aligning the colons. This doesn't work yet.

master: Parent widget.
label: Text of the new label widget. If this is not an empty string and the last character is not a colon (':'), a colon is added.
entrywidth=20: Width of the text entry box created.
entryheight=1: Height of the text entry box created. If 1, an Entry widget is created, otherwise a Text widget is created with both horizontal and vertical scrollbars using make_text_box().
labelwidth=0: Width of the label field.
borderwidth=None: Width of the relief border for the text entry box.
takefocus=None: Value to be passed as takefocus for make_text_box() when creating entries more than 1 line high.

make_double_frame ([master,] ...) -> (containing frame, display frame, bottom frame)

Create a pair of frames suitable for hosting a dialog. This method creates a group of nested frames which provide a simple, clean look & feel, dividing the parent frame into two main areas: the display frame and the control frame.

master=None: Parent widget. If None, the default root is used.
class_=None: Class name of the container frame if not 'Frame'.
name=None: Widget name of the container frame.
relief=Tkinter.RAISED: Border relief of the display frame.
borderwidth=1: Border width of the display frame.

The example dialog below shows a finished dialog created using make_double_frame(). The most interesting subframes are indicated by dashed lines.

make_group_frame (master, ... ) -> Frame instance

Create nested frames with a border and optional label. The outer frame is only used to provide the decorative border, to control packing, and to host the label. The inner frame is packed to fill the outer frame and should be used as the parent of all sub-widgets. Only the inner frame is returned.

master: Parent widget.
name=None: Widget name for the frame. If not specified, a generated name will be used.
label=None: If specified, text for a label at the top of the frame.
font=None: Font for the label specified by label. If not given, a small font will be used.
fill=Y
side=None
expand=None: Packing options for the resulting frame.

unify_button_widths ([*buttons])

Make buttons passed in all have the same width. Works for Label and other widgets with the 'text' parameter, so long as all values of the 'text' parameter contain only a single line.

flatten (msg) -> string

Turn a list or tuple into a single string recursively.

boolean (s) -> boolean

Test whether the string s is a valid Tcl boolean value. Raises TypeError if s is not a string.