tkStuff v0.2¶

Gallery¶

Shown below are examples of the widgets currently provided with tkStuff.

Date¶

Date Entry Widget (See the DateEntry class)

Date Selection Dialog (See the DateDialog class)

Time¶

Time Entry Dialog (See the TimeEntry class)

The next 2 time selection dialog styles are chosen based on the Locale e.g. for the en_US locale a 12 hour dialog is displayed.

12 Hour Time Dialog Widget with AM/PM. (See the TimeDialog class)

24 Hour Time Dialog Widget with Separate Minute Selection (See the TimeDialog class)

Color¶

Color Entry Widget (See the ColorEntry class)

Color Selection Dialog (See the ColorDialog class)

Color Wheel Widget (See the ColorWheel class)

Color Slider Widget (See the ColorSlider class and subclasses)

Color Square Widget (See the ColorSquare class)

Color Palette Selector Widget (See the PaletteSelector class)

Tints and Shades Widgets (See the ColorTint and ColorShade classes)

Passwords¶

Password Entry Widget (See the PasswordEntry class)

Password Generation Dialog (See the PasswordDialog class)

Code Examples¶

A Date Entry¶

To display the date entry and dialog shown in the gallery the following code can be used.

try:
    import tkinter as tk
except ImportError:
    import Tkinter as tk

from tks.dates import DateEntry

if __name__ == '__main__':
    root = tk.Tk()
    root.title('Date Test')
    entry = DateEntry(root, locale='pt')
    entry.grid(row=0, column=0, sticky=tk.EW)
    root.columnconfigure(0, weight=1)
    root.mainloop()

A Time Entry¶

To display the time entry and dialog shown in the gallery the following code can be used.

try:
    import tkinter as tk
except ImportError:
    import Tkinter as tk

from tks.times import TimeEntry

if __name__ == '__main__':
    root = tk.Tk()
    root.title('Time Test')
    entry = TimeEntry(root, locale='en_US')
    entry.grid(row=0, column=0, sticky=tk.EW)
    root.columnconfigure(0, weight=1)
    root.mainloop()

A Color Entry¶

To display the color entry and dialog shown in the gallery the following code can be used.

try:
    import tkinter as tk
except ImportError:
    import Tkinter as tk

from tks.colors import ColorEntry

if __name__ == '__main__':
    root = tk.Tk()
    root.title('Color Test')
    entry = ColorEntry(root, start_color='#fedcba')
    entry.grid(row=0, column=0, sticky=tk.EW)
    root.columnconfigure(0, weight=1)
    root.mainloop()

Date Handling¶

tks.dates provides 4 classes to obtain a date from a user.

DateVar: A Tk variable which holds a date.
DateEntry: Displays entry boxes for year, month and day as well as a button to display a date selection dialog.
DateDialog: Displays a dialog window allowing the user to select a date.
DateSelector: A widget which contains the date selection machinery.

class tks.dates.DateVar(master=None, value=None, name=None)¶: A Tkinter variable which holds a datetime.date

class tks.dates.DateEntry(master, variable=None, locale='en', fonts=None)¶

A date entry widget

Creates a frame which contains entry boxes for Year, Month and Day and a button to display a date selection dialog.

Dates will always consist of a 4 digit year and 2 digit months and days only the order and separator are determined by the locale parameter

Parameters:

master (ttk.Frame) – The master frame
variable (tks.dates.DateVar) – The variable which hold the date to display in the entry boxes.
locale (str or babel.Locale) – Determines the order of the widgets in the entry. Either a locale name e.g. ‘en’ or a babel Locale instance. If babel is not installed ISO 8601 format will be used.
fonts (DefaultFonts) – Fonts to use.

value¶: The date represented by the entry.

class tks.dates.DateDialog(master, title, start_date=None, locale='en', target_type='circle', fonts=None, colors=None)¶

Display a dialog to obtain a date from the user

Parameters:

master (ttk.Frame) – The master frame
title (str) – Dialog title
start_date (datetime.date or datetime.datetime) – The date to display in the entry boxes or None for today’s date
locale (str or babel.Locale) – Determines how today’s name is displayed Either a locale name e.g. ‘en’ or a babel Locale instance. If babel is not installed ISO 8601 format will be used.
target_type (TargetShape) – TargetShape.Square, TargetShape.Rectangle or TargetShape.Circle
fonts (DefaultFonts) – Font definitions to use
colors (DefaultColors) – Colors to use.

class tks.dates.DateSelector(master, start_date, locale='en', target_type='circle', fonts=None, colors=None)¶

A date selection widget

Parameters:

master (ttk.Frame) – The master frame
start_date (datetime.date or datetime.datetime) – The date to display in the entry boxes or None for today’s date
locale (str or babel.Locale) – Determines how today’s name is displayed Either a locale name e.g. ‘en’ or a babel Locale instance. If babel is not installed ISO 8601 format will be used.
target_type (TargetShape) – TargetShape.Square, TargetShape.Rectangle or TargetShape.Circle
fonts (tks.DefaultFonts) – Font definitions to use
colors (DefaultColors) – Colors to use.

class tks.dates.TargetShape¶: How to draw the target round a date

Time Handling¶

tks.times provides 4 classes to obtain a time from a user.

TimeVar: A Tk variable which holds a time.
TimeEntry: Displays entry boxes for hours, minutes and optionally seconds and an AM/PM selector. Also contains a button to display a time selection dialog.
TimeDialog: Displays a dialog window allowing the user to select a time.
TimeSelector: A widget which contains the time selection machinery.

class tks.times.TimeVar(master=None, value=None, name=None)¶: A Tkinter variable which holds a datetime.time

class tks.times.TimeEntry(master, variable=None, locale='en', fonts=None, show_seconds=False)¶

A time entry widget

Parameters:

master (ttk.Frame) – The master frame
variable (tks.times.TimeVar) – The variable which hold the date to display in the entry boxes.
locale (str or babel.Locale) – Determines the widgets in the entry. Either a locale name e.g. ‘en’ or a babel Locale instance. If babel is not installed ISO 8601 format will be used i.e. 24 hours (no am/pm) and ‘:’ as a separator.
fonts (DefaultFonts) – Fonts to use
show_seconds (bool) – If True a seconds value can be entered.

value¶: The time represented by the entry.

class tks.times.TimeDialog(master, title, start_time=None, locale='en', time_position='top', show_seconds=False, ampm=None, fonts=None)¶

Display a dialog to obtain a time from the user

Parameters:

master (ttk.Frame) – The master frame
title (str) – Window title.
start_time (datetime.time) – The time to display in the entry boxes. If not provided or None then today’s date will be used.
locale (str or babel.Locale) – Determines the widgets in the entry. Either a locale name e.g. ‘en’ or a babel Locale instance. If babel is not installed ISO 8601 format will be used i.e. 24 hours (no am/pm) and ‘:’ as a separator.
time_position –
Controls if and where a text representation of the time is displayed. Can be one of the following

None - Don’t display tk.TOP - Display above the clock face tk.BOTTOM - Display below the clock face
show_seconds (bool) – If True a seconds value can be entered.
ampm – If not None display a 12 hour clock face with am/pm selection where the 1st element of the tuple is the text for AM and the 2nd element for PM.
fonts (DefaultFonts) – Fonts definitions to use

class tks.times.TimeSelector(master, start_time, locale='en', ampm=None, time_position='top', show_seconds=False, fonts=None, colors=None)¶

A time selection widget.

Parameters:

master (ttk.Frame) – The master frame
locale (str or babel.Locale) – Determines the widgets in the entry. Either a locale name e.g. ‘en’ or a babel Locale instance. If babel is not installed ISO 8601 format will be used i.e. 24 hours (no am/pm) and ‘:’ as a separator.
ampm – If not None display a 12 hour clock face with am/pm selection where the 1st element of the tuple is the text for AM and the 2nd element for PM.
time_position (str) – Controls where to display the selected time. I None the time is not displayed. If tk.TOP then it is displayed above the clock dial, if tk.BOTTOM then below.
show_seconds (bool) – If True then the selector can also be used to set seconds.
fonts (DefaultFonts) – Font definitions to use
colors (DefaultColors) – Colors to use.

Used by the TimeDialog class but can be used independently.

time¶: The selected time

Color Handling¶

tks.colors provides 3 classes to obtain a color from a user.

ColorVar: A Tk variable which holds an RGB color.
ColorEntry: Displays an entry box to enter a color as well as a button to display a color selection dialog.
ColorDialog: Displays a dialog window allowing the user to select a color using a color wheel or sliders.

class tks.colors.ColorVar(master=None, value=None, name=None)¶

A Tkinter Variable subclass to store an RGB color tuple.

set(value)¶: Set the color tuple to be stored.

class tks.colors.ColorEntry(master, variable=None, color_format='rgbhex', fonts=None, colors=None)¶

Displays an entry to enter color information and a button to display a selection dialog.

Parameters:	master – Tk master widget variable (`tks.colors.ColorVar`) – The variable which hold the color to display in the entry box. color_format (str) – How to display the color in the entry box. One of the following `rgbhex`, `rgb`, `hsv` or `hls` fonts – Fonts to use

rgb¶: RGB representation of the selected color

hsv¶: HSV representation of the selected color

hls¶: HLS representation of the selected color

class tks.colors.ColorDialog(master, title, start_color=(0.5, 0.5, 0.5), fonts=None)¶

Display a dialog to obtain an RGB value.

The color is returned as an (R, G, B) tuple where each component is between 0.0 and 1.0

Parameters:	master – The master widget title (str) – The window title start_color (tuple) – The initial (R, G, B) tuple to display. If any element of the tuple is greater than 1.0 then it is assumed that all values need to be scaled by 255.0 both when setting and obtaining the color value.

tks.color_wheel¶

Implements a color wheel with an outer ring to select a hue and a triangle within that where saturation and value can be selected

class tks.color_wheel.ColorWheel(master, variable=None, radius=125)¶: Displays an HSV color wheel.

tks.color_slider¶

3 element sliders to change RGB, HSV and HLS variables

class tks.color_slider.RGBSlider(master, variable=None, fonts=None)¶

Bases: tks.color_slider.ColorSlider

An RGB Color Slider

class tks.color_slider.HSVSlider(master, variable=None, fonts=None)¶

Bases: tks.color_slider.ColorSlider

An HSV Color Slider

class tks.color_slider.HLSSlider(master, variable=None, fonts=None)¶

Bases: tks.color_slider.ColorSlider

An HLS Color Slider

class tks.color_slider.ColorSlider(master, variable=None, fonts=None)¶

Color slider base class.

from_rgb(rgb)¶: Convert from RGB

to_rgb(value)¶: Convert to RGB

tks.color_square¶

ColorSquare displays a solid square which changes color depending on the value of a variable. Also displays textual color information below.

class tks.color_square.ColorSquare(master, variable=None, mode='rw', color_info=('rgbhex', ), dnd_target=True, dnd_source=True, fonts=None)¶

Displays a colored rectangle and a text description of the color below it. A popup menu is provided to copy the hex, RGB, HSV and HLS representations of the color.

Parameters:

variable (ColorVar) – The RGB color to display
mode (str) – One of r, w, rw. If r is specified then the widget responds to changes in the variable. If w is specified then the color is written to the variable on a left mouse click.
color_info –
The color information to display under the square as a text representation of the color. The elements are specified as a tuple where the following strings can be provided.

rgbhex, rgb, hsv, hls
dnd_target (bool) – If True then the square responds to colors being dropped on it.
dnd_source (bool) – If True the square works as a drag and drop source.

rgb¶: The RGB tuple to display. If None the the rectangle is cleared and the text set to the empty string.

dnd_accept(source, event)¶: Indicate that we can handle a drag and drop operation.

dnd_enter(source, event)¶: Called by the drag and drop machinery when the mouse enters the canvas.

dnd_motion(source, event)¶: Called by the drag and drop machinery when the mouse moves within the canvas.

dnd_leave(source, event)¶: Called by the drag and drop machinery when the mouse leaves the canvas.

dnd_commit(source, event)¶: Called by the drag and drop machinery when the mouse is released over the canvas.

dnd_end(target, event)¶: Called by the drag and drop machinery to end the operation.

tks.color_tints_and_shades¶

Display tints and shades of a base color. This module provides 2 classes both of which display a number of ColorSquares enclosed in a LabelFrame along with a scale to adjust the percent between the colors.

ColorTint: Displays a set of tints
ColorShade: Displays a set of shades

class tks.color_tints_and_shades.ColorTint(master, variable, count=5, percent=(1, 5))¶

Displays a sequence of tints.

Parameters:	variable (`tks.vars.ColorVar`) – The RGB color to produce a set of tints from count (int) – The number of tints to display percent (tuple) – Determines the percent between the tints specified as a min and a max range.

class tks.color_tints_and_shades.ColorShade(master, variable, count=5, percent=(1, 5))¶

Displays a sequence of shades.

Parameters:	variable (`tks.vars.ColorVar`) – The RGB color to produce a set of shades from count (int) – The number of shades to display percent (tuple) – Determines the percentage percent between the shades specified as a min and a max range.

tks.color_palette¶

A Tkinter widget to select colors from a palette of colors

class tks.color_palette.PaletteSelector(master, variable=None, height=400)¶: A widget to display a set of colors from a palette.

Filesystem Entry Handling¶

Allows selection of filesystem entries (directories and files).

DirEntry: Displays a text box and a button to select a directory using the system defined selection method.
FileEntry: Displays a text box and a button to select a file using the system defined selection method.

class tks.fs.DirEntry(master, variable=None, **options)¶: Entry box and a button to select a directory.

class tks.fs.FileEntry(master, variable=None, **options)¶: Entry box and a button to select a file.

Password Handling¶

tks.passwords provides 2 classes to obtain a password from a user

PasswordEntry: Displays a widget which allows the user to enter a password
PasswordDialog: Displays a dialog which allows the user to generate a random password.

class tks.passwords.PasswordEntry(master, variable=None, show_hide=True, compare=True, generate=True, fonts=None, colors=None)¶

A password entry widget

Creates a frame which contains an entry box for a password and optionally

A checkbox to show and hide the password
A second entry box to make sure the password was entered as the user thought.
A button which displays a dialog to generate a random password.

Parameters:

master (ttk.Frame) – The master frame
variable (StringVar) – The variable which hold the date to display in the entry boxes.
show_hide (bool) – If True a show/hide checkbox is added to show the actual characters.
compare (bool) – If True a second entry box is shown to as a comparison.
generate (bool) – If True a button is shown which displays a password generator when clicked.
fonts (DefaultFonts) – Fonts to use.
colors (DefaultColors) – Fonts to use.

class tks.passwords.PasswordDialog(master, title, fonts=None, colors=None)¶

A Password Generator Dialog

Parameters:	master (`ttk.Frame`) – The master frame title (str) – Dialog title

Miscellaneous Stuff¶

The tks Module¶

tkStuff - A collection of Tk widgets

class tks.DefaultColors¶: A container for color names.

class tks.DefaultFonts¶: A container for font information.

class tks.PickleVar(master=None, value=None, name=None)¶: A Tkinter variable which stores values as pickled objects.

tks.load_colors()¶: Load color definitions from the .tksrc file

tks.load_fonts()¶: Load font definitions from the .tksrc file

tks.parse_geometry(geom)¶: Return a width, height, x, y tuple from a Tk geometry.

tks.rect_at(point, size, size_y=-1)¶: Returns a rectangle centred at point. If only size is provided then the rectangle will be a square. The dimensions will be size * 2.

tks.rect_center(rect)¶: Return the centre of a rectangle as an (x, y) tuple.

Color Functions (tks.color_funcs)¶

Various functions to manipulate RGB hex, RGB, HSV and HLS colors.

tks.color_funcs.clamp(value)¶: Clamp a float between 0.0 and 1.0

tks.color_funcs.clamped_tuple(value)¶: Clamps the values in a tuple between 0.0 and 1.0

tks.color_funcs.color_string_to_color(value, allow_short_hex=True)¶: Convert a color string to a (color format, value) tuple where the color format is one of rgbhex, rgb, hsv or hls

tks.color_funcs.color_string_to_rgb(value)¶: Return an RGB tuple from a color string.

tks.color_funcs.color_string_to_tuple(value)¶: Convert a color string to a tuple of floats.

tks.color_funcs.contrast_color(rgb)¶: Return either white or black whichever provides the most contrast

tks.color_funcs.hex_string_to_rgb(value, allow_short=True)¶

Convert from a hex color string of the form #abc or #abcdef to an RGB tuple.

Parameters:	value (str) – The value to convert allow_short (bool) – If True then the short of form of an hex value is accepted e.g. #fff

tks.color_funcs.luminosity_transform(color, luminosity=0.05)¶

Transform an RGB color by a luminosity.

If luminosity is a tuple then the 3 elements are used to transform the red, green and blue values individually. If a float then the same value is used to transform all 3 elements.

tks.color_funcs.rgb_intensity(rgb)¶: Convert an RGB color to its intensity

tks.color_funcs.rgb_shade(rgb, percent=5)¶

Create a shade of the RGB color

Parameters:	rgb (tuple) – The RGB value for which to calculate the tint percent (int) – Determines the percent between the specified color and the shade

tks.color_funcs.rgb_shades(rgb, base_percent, count, linear=True)¶

Produce a list of shades from the base color

Parameters:	rgb (tuple) – The RGB value for which to calculate the shades base_percent (float) – Determines the factor between the returned colors count (int) – The number of shades to return

tks.color_funcs.rgb_tint(rgb, percent=5)¶

Create a tinted version of the RGB color

Parameters:	rgb (tuple) – The RGB value for which to calculate the tint percent (int) – Determines the percent between the specified color and the tint

tks.color_funcs.rgb_tints(rgb, base_percent, count, linear=True)¶

Produce a list of tints from the base color

Parameters:	rgb (tuple) – The RGB value for which to calculate the tints base_percent (float) – Determines the factor between the returned colors count (int) – The number of tints to return

tks.color_funcs.rgb_to_hex_string(value)¶

Convert from an (R, G, B) tuple to a hex color.

Parameters:	value (tuple) – The RGB value to convert

R, G and B should be in the range 0.0 - 1.0

tks.color_funcs.rgb_to_hls_string(value, dp=3)¶

Convert from an (R, G, B) tuple to an HLS string.

Parameters:	value (tuple) – The RGB value to convert dp (int) – Number of decimal places in the string

R, G and B should be in the range 0.0 - 1.0

tks.color_funcs.rgb_to_hsv_string(value, dp=3)¶

Convert from an (R, G, B) tuple to an HSV string.

Parameters:	value (tuple) – The RGB value to convert dp (int) – Number of decimal places in the string

R, G and B should be in the range 0.0 - 1.0

tks.color_funcs.rgb_to_rgb_string(value, dp=3)¶

Convert from an (R, G, B) tuple to an RGB string.

Parameters:	value (tuple) – The RGB value to convert dp (int) – Number of decimal places in the string

R, G and B should be in the range 0.0 - 1.0

Icon Functions (tks.icon)¶

tks.icon.set_icon_from_data(root, image_data)¶

Set the icon for a root window from image data.

Parameters:	root – Toplevel window for which to set the icon. image_data (bytes) – The image data to use

tks.icon.set_icon_from_file(root, filename)¶

Set the icon for a root window from a file.

Parameters:	root – Toplevel window for which to set the icon. filename (str) – The filename to read the image data from

tks.icon.set_icon_from_resource(root, package, resource)¶

Set the icon for a root window to a resource

Parameters:	root – Toplevel window for which to set the icon. package (str) – The package in which to find the resource resource (str) – The name of the resource

tkStuff is a collection of Tkinter widgets for dates, times and colors.

For each of these there is an entry widget and a dialog for obtaining values from the user.

For colors, each element of the dialog is also exposed as a class (classes exist for a color wheel, 3 element sliders, a color information square.)

A color palette widget is also provided access to the set of colors defined by X11 and CSS3.

Finally there are 2 widgets to display tints and shades of a color.

Examples of these can be seen in the Gallery and some code examples in the Code Examples section.

License¶

This module is licensed under the terms of the Apache V2.0 license.

Dependencies¶

tkStuff has one required dependency and an optional one. Either Pillow or PIL are required and Babel is optional.

PIL is used to generate the color wheel.
Babel is used to provide improved date and time handling and if Babel not present dates are limited to the ISO 8601 YYYY-MM-DD format and times are limited to a 24 hour clock.

Installation¶

Installation is performed from PyPi via pip

pip install tks

This doesn’t automatically install Babel. To do this either install it separately or use the following command for the improved date/time handling

pip install tks[idth]

Contact¶

Simon Kennedy <sffjunkie+code@gmail.com>

Version History¶

Version	Description
0.2	Added `Entry` classes for files, directories and passwords. Added functions to set a Tk window icon. `Entry` classes now take a Tk variable subclass instead of a value. Colors and fonts to be used for interface elements can be specified using an rc file. Added a decimal places parameter to the color to string conversion functions.
0.1	Initial release

tkStuff v0.2¶

Gallery¶

Date¶

Time¶

Color¶

Passwords¶

Code Examples¶

A Date Entry¶

A Time Entry¶

A Color Entry¶

A Color Palette Widget¶

Date Handling¶

Time Handling¶

Color Handling¶

tks.color_wheel¶

tks.color_slider¶

tks.color_square¶

tks.color_tints_and_shades¶

tks.color_palette¶

Filesystem Entry Handling¶

Password Handling¶

Miscellaneous Stuff¶

The tks Module¶

Color Functions (tks.color_funcs)¶

Icon Functions (tks.icon)¶

License¶

Dependencies¶

Installation¶

Contact¶

Version History¶