TK - Tools Documentation: Jason R. Jones
TK - Tools Documentation: Jason R. Jones
Jason R. Jones
1 Installation 1
1.1 Pip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Setup.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Widget Groups 3
2.1 LabelGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 EntryGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 ButtonGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 KeyValueEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.5 Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 MultiSlotFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.7 SevenSegment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Canvas Widgets 11
3.1 RotaryScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Gauge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3 Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.4 LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4 Smart Widgets 17
4.1 SmartOptionMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2 SmartSpinBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3 SmartCheckbutton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.4 SmartListBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.5 BinaryLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.6 ByteLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5 Tool Tips 23
5.1 ToolTip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6 Introduction 25
7 Tkinter Setup 27
Index 31
i
ii
CHAPTER 1
Installation
1.1 Pip
To install, simply pip install tk_tools. All images and other source material are included as packages within
python, so you shouldn’t have to do any funky workarounds even when using this package in pyinstaller or other static
execution environments. Some environments may require some basic modification to this, such as the use of pip3
instead of pip.
1.2 Setup.py
Clone the git repository, navigate to the cloned directory, and python3 setup.py install.
1.3 Dependencies
The tk_tools package is written with Python 3.5+ in mind! It uses type hints so that your IDE - such as PyCharm - can
easily identify potential issues with your code as you write it. If you want this to support a different python version,
create an issue and I’m sure that we can work something out easily enough.
1
tk_tools Documentation
2 Chapter 1. Installation
CHAPTER 2
Widget Groups
2.1 LabelGrid
3
tk_tools Documentation
2.2 EntryGrid
2.3 ButtonGrid
2.4 KeyValueEntry
class groups.KeyValueEntry(parent, keys: list, defaults: list = None, unit_labels: list = None, en-
ables: list = None, title: str = None, on_change_callback: callable =
None, **options)
Creates a key-value input/output frame.
Parameters
• parent – the parent frame
• keys – the keys represented
• defaults – default values for each key
• unit_labels – unit labels for each key (to the right of the value)
• enables – True/False for each key
• title – The title of the block
• on_change_callback – a function callback when any element is changed
• options – frame tk options
add_row(key: str, default: str = None, unit_label: str = None, enable: bool = None)
Add a single row and re-draw as necessary
Parameters
• key – the name and dict accessor
• default – the default value
• unit_label – the label that should be applied at the right of the entry
• enable – the ‘enabled’ state (defaults to True)
2.4. KeyValueEntry 5
tk_tools Documentation
Returns
change_enables(enables_list: list)
Enable/disable inputs.
Parameters enables_list – list containing enables for each key
Returns None
get()
Retrieve the GUI elements for program use.
Returns a dictionary containing all of the data from the key/value entries
load(data: dict)
Load values into the key/values via dict.
Parameters data – dict containing the key/values that should be inserted
Returns None
reset()
Clears all entries.
Returns None
2.5 Calendar
locale.setlocale(locale.LC_ALL, 'deu_deu')
Parameters
• parent – the parent frame
• callback – the callable to be executed on selection
• kw – tkinter.frame keyword arguments
add_callback(callback: callable)
Adds a callback to call when the user clicks on a date
Parameters callback – a callable function
Returns None
class datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo ]]]]])
The year, month and day arguments are required. tzinfo may be None, or an instance of a tzinfo subclass.
The remaining arguments may be ints.
astimezone()
tz -> convert to local time in new timezone tz
combine()
date, time -> datetime with same date and time fields
ctime()
Return ctime() style string.
date()
Return date object with same year, month and day.
dst()
Return self.tzinfo.dst(self).
fromisoformat()
string -> datetime from datetime.isoformat() output
fromtimestamp()
timestamp[, tz] -> tz’s local time from POSIX timestamp.
isoformat()
[sep] -> string in ISO 8601 format, YYYY-MM-DDT[HH[:MM[:SS[.mmm[uuu]]]]][+HH:MM]. sep
is used to separate the year from the time, and defaults to ‘T’. timespec specifies what components
of the time to include (allowed values are ‘auto’, ‘hours’, ‘minutes’, ‘seconds’, ‘milliseconds’, and
‘microseconds’).
now()
Returns new datetime object representing current time local to tz.
tz Timezone object.
If no tz is specified, uses local timezone.
replace()
Return datetime with new specified fields.
strptime()
string, format -> new datetime parsed from a string (like time.strptime()).
time()
Return time object with same time but with tzinfo=None.
timestamp()
Return POSIX timestamp as float.
timetuple()
Return time tuple, compatible with time.localtime().
timetz()
Return time object with same time and tzinfo.
tzname()
Return self.tzinfo.tzname(self).
2.5. Calendar 7
tk_tools Documentation
utcfromtimestamp()
Construct a naive UTC datetime from a POSIX timestamp.
utcnow()
Return a new datetime representing UTC day and time.
utcoffset()
Return self.tzinfo.utcoffset(self).
utctimetuple()
Return UTC time tuple, compatible with time.localtime().
selection
Return a datetime representing the current selected date.
class timedelta
Difference between two datetime values.
timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)
All arguments are optional and default to 0. Arguments may be integers or floats, and may be positive or
negative.
days
Number of days.
microseconds
Number of microseconds (>= 0 and less than 1 second).
seconds
Number of seconds (>= 0 and less than 1 day).
total_seconds()
Total seconds in the duration.
2.6 MultiSlotFrame
Parameters
2.7 SevenSegment
Parameters
• parent – the tk parent frame
• height – the widget height (defaults to 50)
• digit_color – the digit color (ex: ‘black’, ‘#ff0000’)
• background – the background color (ex: ‘black’, ‘#ff0000’)
2.7. SevenSegment 9
tk_tools Documentation
Parameters
• parent – the tk parent frame
• height – the widget height (defaults to 50)
• digit_color – the digit color (ex: ‘black’, ‘#ff0000’)
• background – the background color (ex: ‘black’, ‘#ff0000’)
Canvas Widgets
These widgets provide visual feedback to the user using the canvas.
3.1 RotaryScale
class canvas.RotaryScale(parent, max_value: (<class ’float’>, <class ’int’>) = 100.0, size: (<class
’float’>, <class ’int’>) = 100, unit: str = None, img_data: str = None,
needle_color=’blue’, needle_thickness=0, **options)
Shows a rotary scale, much like a speedometer.:
rs.set_value(10)
Parameters
• parent – tkinter parent frame
• max_value – the value corresponding to the maximum value on the scale
• size – the size in pixels
• options – the frame options
11
tk_tools Documentation
3.2 Gauge
class canvas.Gauge(parent, width: int = 200, height: int = 100, min_value=0.0, max_value=100.0,
label=”, unit=”, divisions=8, yellow=50, red=80, yellow_low=0, red_low=0,
bg=’lightgrey’)
Shows a gauge, much like the RotaryGauge.:
gauge = tk_tools.Gauge(root, max_value=100.0,
label='speed', unit='km/h')
gauge.grid()
gauge.set_value(10)
Parameters
• parent – tkinter parent frame
• width – canvas width
3.3 Graph
class canvas.Graph(parent, x_min: float, x_max: float, y_min: float, y_max: float, x_tick: float, y_tick:
float, **options)
Tkinter native graph (pretty basic, but doesn’t require heavy install).:
graph = tk_tools.Graph(
parent=root,
x_min=-1.0,
x_max=1.0,
y_min=0.0,
y_max=2.0,
x_tick=0.2,
(continues on next page)
3.3. Graph 13
tk_tools Documentation
graph.grid(row=0, column=0)
Parameters
• parent – the parent frame
• x_min – the x minimum
• x_max – the x maximum
• y_min – the y minimum
• y_max – the y maximum
• x_tick – the ‘tick’ on the x-axis
• y_tick – the ‘tick’ on the y-axis
• options – additional valid tkinter.canvas options
draw_axes()
Removes all existing series and re-draws the axes.
Returns None
static frange(start, stop, step, digits_to_round=3)
Works like range for doubles
Parameters
• start – starting value
• stop – ending value
• step – the increment_value
• digits_to_round – the digits to which to round (makes floating-point numbers much
easier to work with)
Returns generator
plot_line(points: list, color=’black’, point_visibility=False)
Plot a line of points
Parameters
• points – a list of tuples, each tuple containing an (x, y) point
• color – the color of the line
• point_visibility – True if the points should be individually visible
Returns None
3.4 LED
class canvas.Led(parent, size: int = 100, on_click_callback: callable = None, toggle_on_click: bool =
False, **options)
Create an LED-like interface for the user.:
led.to_red()
led.to_green(on=True)
The user also has the option of adding an on_click_callback function. When the button is clicked, the button will
change state and the on-click callback will be executed. The callback must accept a single boolean parameter,
on, which indicates if the LED was just turned on or off.
Parameters
• parent – the parent frame
• size – the size in pixels
• on_click_callback – a callback which accepts a boolean parameter ‘on’
• options – the frame options
to_green(on: bool = False)
Change the LED to green (on or off).
Parameters on – True or False
Returns None
to_grey(on: bool = False)
Change the LED to grey.
Parameters on – Unused, here for API consistency with the other states
Returns None
to_red(on: bool = False)
Change the LED to red (on or off) :param on: True or False :return: None
to_yellow(on: bool = False)
Change the LED to yellow (on or off) :param on: True or False :return: None
3.4. LED 15
tk_tools Documentation
Smart Widgets
Smart widgets consist of existing widgets with improved API. In most cases, these widgets will simply incorporate the
appropriate type of xVar for the widget type. For instance, imaging providing for an OptionMenu without having
to use a StringVar. These widgets generally appear the same as their ordinary counterparts that are already present
within the library.
4.1 SmartOptionMenu
Parameters
• data – the tk parent frame
• options – a list containing the drop down options
• initial_value – the initial value of the dropdown
• callback – a function
17
tk_tools Documentation
4.2 SmartSpinBox
Parameters
• parent – the tk parent frame
• entry_type – ‘str’, ‘int’, ‘float’
• callback – python callable
• options – any options that are valid for tkinter.SpinBox
4.3 SmartCheckbutton
Parameters
• parent – the tk parent frame
• callback – python callable
• options – any options that are valid for tkinter.Checkbutton
4.4 SmartListBox
Parameters
• parent – the tk parent frame
• options – any options that are valid for tkinter.Checkbutton
• on_select_callback – python callable
• selectmode – the selector mode (supports “browse” and “multiple”)
add_callback(callback: callable)
Associates a callback function when the user makes a selection.
Parameters callback – a callable function
4.5 BinaryLabel
Parameters
• parent – the tk parent frame
• value – the initial value, default is 0
• options – prefix string for identifiers
clear_bit(position: int)
Clears the value at position
Parameters position – integer between 0 and 7, inclusive
Returns None
4.5. BinaryLabel 19
tk_tools Documentation
clear_lsb()
Clears the least significant bit :return: None
clear_msb()
Clears the most significant bit :return: None
get()
Return the current value
Returns the current integer value
get_bit(position: int)
Returns the bit value at position
Parameters position – integer between 0 and <width>, inclusive
Returns the value at position as a integer
get_lsb()
Returns the least significant bit as an integer :return: the LSB
get_msb()
Returns the most significant bit as an integer :return: the MSB
set(value: int)
Set the current value
Parameters value –
Returns None
set_bit(position: int)
Sets the value at position
Parameters position – integer between 0 and 7, inclusive
Returns None
set_lsb()
Sets the least significant bit :return: None
set_msb()
Sets the most significant bit :return: None
toggle_bit(position: int)
Toggles the value at position
Parameters position – integer between 0 and 7, inclusive
Returns None
toggle_lsb()
Toggles the least significant bit :return:
toggle_msb()
Changes the most significant bit :return: None
4.6 ByteLabel
4.6. ByteLabel 21
tk_tools Documentation
Tool Tips
5.1 ToolTip
entry = tk.Entry(root)
entry.grid()
# createst a tooltip
tk_tools.ToolTip(entry, 'enter a value between 1 and 10')
Parameters
• widget – the widget on which to hover
• text – the text to display
• time – the time to display the text, in milliseconds
23
tk_tools Documentation
Introduction
The tk_tools package exists in a space like other packages. In many cases, the tkinter interface leaves some
API to be desired while, in other cases, it leaves out some room for fairly standard visualizations. This is a collection
of widgets and tools that have been developed over the course of creating GUI elements as a means to simplify and
enhance the process and results.
There are three categories of widgets:
• groups of widgets that are useful as a group
• visual aids using the canvas
• useful improvements on existing widgets
25
tk_tools Documentation
26 Chapter 6. Introduction
CHAPTER 7
Tkinter Setup
Each of the code examples assumes a structure similar to the below in order to setup the root environment.:
import tkinter as tk
import tk_tools
root = tk.Tk()
# -----------------------------------
# ----- your GUI widget(s) here -----
# -----------------------------------
root.mainloop()
27
tk_tools Documentation
• genindex
29
tk_tools Documentation
A fromisoformat() (groups.Calendar.datetime
add() (groups.MultiSlotFrame method), 9 method), 7
add_callback() (groups.Calendar method), 6 fromtimestamp() (groups.Calendar.datetime
add_callback() (widgets.SmartListBox method), 19 method), 7
add_row() (groups.ButtonGrid method), 5
add_row() (groups.EntryGrid method), 4 G
add_row() (groups.KeyValueEntry method), 5 Gauge (class in canvas), 12
add_row() (groups.LabelGrid method), 3 get() (groups.KeyValueEntry method), 6
astimezone() (groups.Calendar.datetime method), 7 get() (groups.MultiSlotFrame method), 9
get() (widgets.BinaryLabel method), 20
B get_bit() (widgets.BinaryLabel method), 20
BinaryLabel (class in widgets), 19 get_lsb() (widgets.BinaryLabel method), 20
ButtonGrid (class in groups), 4 get_msb() (widgets.BinaryLabel method), 20
ByteLabel (class in widgets), 20 Graph (class in canvas), 13
C I
Calendar (class in groups), 6 isoformat() (groups.Calendar.datetime method), 7
Calendar.datetime (class in groups), 7
Calendar.timedelta (class in groups), 8 K
change_enables() (groups.KeyValueEntry method), KeyValueEntry (class in groups), 5
6
clear() (groups.MultiSlotFrame method), 9 L
clear_bit() (widgets.BinaryLabel method), 19 LabelGrid (class in groups), 3
clear_lsb() (widgets.BinaryLabel method), 19 Led (class in canvas), 15
clear_msb() (widgets.BinaryLabel method), 20 load() (groups.KeyValueEntry method), 6
combine() (groups.Calendar.datetime method), 7
ctime() (groups.Calendar.datetime method), 7 M
microseconds (groups.Calendar.timedelta attribute),
D 8
date() (groups.Calendar.datetime method), 7 MultiSlotFrame (class in groups), 8
days (groups.Calendar.timedelta attribute), 8
draw_axes() (canvas.Graph method), 14 N
dst() (groups.Calendar.datetime method), 7 now() (groups.Calendar.datetime method), 7
E P
EntryGrid (class in groups), 4 plot_line() (canvas.Graph method), 14
plot_point() (canvas.Graph method), 14
F
frange() (canvas.Graph static method), 14
31
tk_tools Documentation
R
read() (groups.EntryGrid method), 4
replace() (groups.Calendar.datetime method), 7
reset() (groups.KeyValueEntry method), 6
RotaryScale (class in canvas), 11
S
seconds (groups.Calendar.timedelta attribute), 8
selection (groups.Calendar attribute), 8
set() (widgets.BinaryLabel method), 20
set_bit() (widgets.BinaryLabel method), 20
set_lsb() (widgets.BinaryLabel method), 20
set_msb() (widgets.BinaryLabel method), 20
set_value() (canvas.RotaryScale method), 11
SevenSegment (class in groups), 9
SevenSegmentDigits (class in groups), 9
SmartCheckbutton (class in widgets), 18
SmartListBox (class in widgets), 18
SmartOptionMenu (class in widgets), 17
SmartSpinBox (class in widgets), 18
strptime() (groups.Calendar.datetime method), 7
T
time() (groups.Calendar.datetime method), 7
timestamp() (groups.Calendar.datetime method), 7
timetuple() (groups.Calendar.datetime method), 7
timetz() (groups.Calendar.datetime method), 7
to_green() (canvas.Led method), 15
to_grey() (canvas.Led method), 15
to_red() (canvas.Led method), 15
to_yellow() (canvas.Led method), 15
toggle_bit() (widgets.BinaryLabel method), 20
toggle_lsb() (widgets.BinaryLabel method), 20
toggle_msb() (widgets.BinaryLabel method), 20
ToolTip (class in tooltips), 23
total_seconds() (groups.Calendar.timedelta
method), 8
tzname() (groups.Calendar.datetime method), 7
U
utcfromtimestamp() (groups.Calendar.datetime
method), 7
utcnow() (groups.Calendar.datetime method), 8
utcoffset() (groups.Calendar.datetime method), 8
utctimetuple() (groups.Calendar.datetime
method), 8
32 Index