control

This module defines a Control class and several derivatives. A Control is a special-purpose GUI widget for setting a value such as a number or filename.

class Control(vartype=<type 'str'>, label='', option='', default='', help='', toggles=False, labelside='left', **kwargs)

A specialized GUI widget that controls a command-line option.

Control subclasses may have any number of sub-widgets such as labels, buttons or entry boxes; one of the sub-widgets should be linked to self.variable like so:

textbox = tk.Entry(self, textvariable=self.variable)

See the Control subclasses below for examples of how self.variable, get() and set() are used.

Create a Control for an option.

Arguments:

vartype

Python type of stored variable (str, bool, int, float, list, dict)

label

Label shown in the GUI for the Control

option

Command-line option associated with this Control, or empty to create a positional argument

default

Default value for the Control

help

Help text to show in a tooltip

toggles

Control widget may be toggled on/off

labelside

Position of label (‘left’ or ‘top’). It’s up to the derived Control class to use this appropriately.

kwargs

Keyword arguments of the form key1=arg1, key2=arg2

add_callback(callback)

Add a callback to this Control, which will be called anytime the Control’s value is modified. The callback will be called with a single argument: this Control instance. Callbacks will only be added once.

static by_option(option)

Return the Control instance for a given option string, or None if no Control has that option string.

draw(master)

Draw the control widgets in the given master.

Override this method in derived classes, and call the base class method:

Control.draw(self, master)

focus()

Set the focus to this Control. Override in subclasses if needed.

get()

Return the value of the Control’s variable.

get_args()

Return a list of arguments for passing this command-line option. draw must be called before this function.

post()

Post-draw initialization.

reset()

Reset the Control’s value to the default.

set(value)

Set the Control’s variable to the given value.

set_args(args)

Set control options from the given list of command-line arguments, and remove any successfully parsed options and arguments from args.

set_variable(variable)

Set the Control to reference the given Tkinter variable.

toggle()

Enable or disable the Control when self.check is toggled.

class Choice(label='Choices', option='', default='', help='', choices='A|B', style='radio', side='left', **kwargs)

Multiple-choice selector, with radiobutton or dropdown style.

Initialize Choice widget with the given label and list of choices.

label

Text label for the choices

option

Command-line option to set

default

Default choice, or empty to use first choice in list

help

Help text to show in a tooltip

choices

Available choices, in string form: one|two|three, list form ['one', 'two', 'three'], or as a list-of-lists [['a', "Use A"], ['b', "Use B"], ..]. A dictionary is also allowed, as long as you don’t care about preserving order.

style

radio for radiobuttons, dropdown for a drop-down list

side

left for horizontal, top for vertical arrangement

draw(master)

Draw control widgets in the given master.

class Color(label='Color', option='', default='', help='', **kwargs)

A color chooser that may have ‘#RRGGBB’ or ‘ColorName’ values.

Create a widget that opens a color-chooser dialog.

label

Text label describing the color to be selected

option

Command-line option to set

default

Default color (named color or hexadecimal RGB)

help

Help text to show in a tooltip

draw(master)

Draw control widgets in the given master.

hexcolor(color)

Return an 8-bit ‘#RRGGBB’ hex string for the given color. If a given color name is unknown, return ‘#FFFFFF’ (white).

indicate_color(bg_color)

Change the button background color to the given RGB hex value.

pick_color()

Event handler for the color picker button; choose and set a color.

set(color)

Set the current color to an RGB hex value or color name.

update_color(event=None)

Event handler to update the color preview.

class Filename(label='Filename', option='', default='', help='', action='load', desc='Select a file to load', filetypes='all', **kwargs)

Filename entry box with browse button.

Create a Filename with label, text entry, and browse button.

label

Text of label next to file entry box

option

Command-line option to set

default

Default filename

help

Help text to show in a tooltip

action

Do you intend to ‘load’ or ‘save’ this file?

desc

Brief description (shown in title bar of file browser dialog)

filetypes

Types of files to show in the file browser dialog. May be ‘all’ for all file types, or a list of ('label', '*.ext') tuples.

browse(event=None)

Event handler when browse button is pressed

draw(master)

Draw control widgets in the given master.

class Flag(label='Flag', option='', default=False, help='', enables=None, **kwargs)

Yes/no checkbox, for flag-type options.

Create a Flag widget with the given label and default value.

label

Text label for the flag

option

Command-line flag passed

default

Default value (True or False)

help

Help text to show in a tooltip

enables

Option or list of options to enable when the Flag is checked

draw(master)

Draw the Flag in the given master widget.

enabler()

Enable/disable related Controls based on Flag state.

get_args()

Return a list of arguments for passing this command-line option. draw must be called before this function.

class FlagOpt(label='Flag', option='', default=False, help='', control=None, **kwargs)

Like a normal Flag, but has an optional argument following it.

Create a FlagOpt widget; like a Flag, but has an optional argument which may be set using an associated Control.

label

Text label for the flag

option

Command-line flag passed

default

Default value (True or False)

help

Help text to show in a tooltip

control

Another Control, for setting the argument value (required)

draw(master)

Draw the Flag and associated Control in the given master.

enabler()

Enable or disable the arg Control when the flag changes.

get_args()

If the flag is enabled, return the flag and associated option.

class Font(label='Font', option='', default='Helvetica', help='', **kwargs)

Font name chooser.

Create a widget that opens a font chooser dialog.

label

Text label for the font

option

Command-line option to set

default

Default font name

help

Help text to show in a tooltip

choose()

Open a font chooser to select a font.

draw(master)

Draw the Font selector in the given master widget.

class List(label='Text List', option='', default=None, help='', control=<libtovid.metagui.control.Text instance at 0x7ff9e06a91b8>, **kwargs)

A list of values, editable with a given Control.

Examples:

List('Filenames', '-files', control=Filename())
List('Colors', '-colors', control=Color())
List('Texts', '-texts', control=Text())
List('Choices', '-choices', control=Choice())

Create a control for a list-type option.

add()

Event handler for the “Add” button.

draw(master)

Draw the List and associated Control in the given master.

modify(control)

Event handler when the Control’s variable is modified.

refresh_control()

Enable the Control if there are items in the list, otherwise disable it.

remove()

Event handler for the “Remove” button.

select(index, value)

Select an item in the list and enable editing.

set(value_list)

Set all list values.

set_variable(variable)

Set the List to use the given ListVar as its variable.

class ListToOne(parent, label='ListToOne', option='', default=None, help='', control=<libtovid.metagui.control.Text instance at 0x7ff9e06a9758>, filter=<function <lambda> at 0x7ff9df9eab18>, side='left', **kwargs)

A List with one value for each value in a parent list.

This is like a regular List, except that it has a parent:child relationship of 1:1 (each parent item has a one child item).

Behavior:

• Each item in parent list maps to one item in the child list
• Parent copy and child list scroll in unison
• If item in child list is selected, parent item is selected also
• Drag/drop is allowed in parent list only

Assumptions:

• If item in parent is selected, child item/list is selected also
• It item is added to parent, new child item/list is added also
• If item in parent is deleted, child item/list is deleted also
• Child option string is only passed once

Create a list having a 1:1 mapping to another List.

parent

Parent List object, or the option string of the parent List control declared elsewhere

filter

A function that translates parent values into child values

side

Pack the parent to the ‘left’ of child or on ‘top’ of child

add_callbacks()

Add callback functions for add/remove in the parent Control.

draw(master)

Draw the parent copy and related list Control, side by side in the given master.

get_args()

Return a list of arguments for the contained list(s).

class ListToMany(parent, label='ListToMany', option='', default=None, help='', control=<libtovid.metagui.control.Text instance at 0x7ff9e06a9710>, filter=<function <lambda> at 0x7ff9df9ead70>, side='left', **kwargs)

A List with many values for each value in a parent list.

This is like a regular List, except that it has a parent:child relationship of 1:* (each parent item has a list of child items).

Behavior:

• Each item in parent list maps to a list of items in the child list
• Parent copy and child list scroll independently
• If item in child is selected, parent is unaffected
• Drag/drop is allowed in the child Control

Assumptions:

• If item in parent is selected, child item/list is selected also
• It item is added to parent, new child item/list is added also
• If item in parent is deleted, child item/list is deleted also
• Child option string is only passed once

Create a list having a 1:* mapping to another List.

parent

Parent List object, or the option string of the parent List control declared elsewhere

filter

A function that translates parent values into child values

side

Pack the parent to the ‘left’ of child or on ‘top’ of child

Keyword arguments:

index

True to pass an additional argument between the child list’s option and arguments with the 1-based index of the child list.

add_callbacks()

Add callback functions for add/remove in the parent Control.

draw(master)

Draw the parent copy and related list Control, side by side in the given master.

get_args()

Return a list of arguments for the contained list(s).

reset()

Reset the list values to empty.

set(items)

Append the given items to listvars.

class Number(label='Number', option='', default=0, help='', min=1, max=10, units='', style='spin', step=1, **kwargs)

Numeric entry box or slider.

Create a number-setting widget.

label

Text label describing the meaning of the number

option

Command-line option to set

default

Default value

help

Help text to show in a tooltip

min, max

Range of allowable numbers (inclusive)

units

Units of measurement (ex. ‘kbits/sec’), used as a label

style

‘spin’ for a spinbox, ‘scale’ for a slider, ‘popup’ for a slider in a popup window

step

For ‘scale’ style, the amount to increment or decrement when the slider is moved

The default/min/max may be integers or floats.

draw(master)

Draw the Number entry in the given master widget.

enable(enabled=True)

Enable or disable all sub-widgets.

class SpacedText(label='List', option='', default='', help='', **kwargs)

Text string interpreted as a space-separated list of strings

draw(master)

Draw SpacedText control in the given master widget.

get()

Get current text, split into a list of strings.

set(listvalue)

Set the text equal to the given list, joined with spaces and double-quoted. Double-quotes in list values are backslash-escaped.

class Text(label='Text', option='', default='', help='', width=None, **kwargs)

Text string entry box.

Create a text-entry control.

label

Label for the text

option

Command-line option to set

default

Default value of text widget

help

Help text to show in a tooltip

width

Width in characters of the text field, or None to maximize width in available space

draw(master)

Draw the Text control in the given master widget.

focus()

Highlight the text entry box for editing.

next_item(event)

Select the next item in the parent listbox.

set_parent(parent_list)

Set the parent List control.