Reference

Module

Colors

class ttkbootstrap.Colors(primary, secondary, success, info, warning, danger, bg, fg, selectbg, selectfg, border, inputfg, inputbg, light='#ddd', dark='#333')

Bases: object

A class that contains the theme colors as well as several helper methods for manipulating colors.

This class is attached to the Style object at run-time for the selected theme, and so is available to use with Style.colors. The colors can be accessed via dot notation or get method:

# dot-notation
Colors.primary

# get method
Colors.get('primary')

This class is an iterator, so you can iterate over the main style color labels (primary, secondary, success, info, warning, danger):

for color_label in Colors:
    color = Colors.get(color_label)
    print(color_label, color)

If, for some reason, you need to iterate over all theme color labels, then you can use the Colors.label_iter method. This will include all theme colors, including border, fg, bg, etc…

for color_label in Colors.label_iter():
    color = Colors.get(color_label)
    print(color_label, color)

Parameters

• primary (str) – the primary theme color; used by default for all widgets.

• secondary (str) – an accent color; commonly of a grey hue.

• success (str) – an accent color; commonly of a green hue.

• info (str) – an accent color; commonly of a blue hue.

• warning (str) – an accent color; commonly of an orange hue.

• danger (str) – an accent color; commonly of a red hue.

• bg (str) – background color.

• fg (str) – default text color.

• selectfg (str) – the color of selected text.

• selectbg (str) – the background color of selected text.

• border (str) – the color used for widget borders.

• inputfg (str) – the text color for input widgets: ie. Entry, Combobox, etc…

• inputbg (str) – the text background color for input widgets.

• light (str) – a light color

• dark (str) – a dark color

get(color_label)

Lookup a color property

Parameters

color_label (str) – a color label corresponding to a class propery (primary, secondary, success, etc…)

Returns

a hexadecimal color value.

Return type

str

static hex_to_rgb(color)

Convert hexadecimal color to rgb color value

Parameters

color (str) – param str color: hexadecimal color value

Returns

rgb color value.

Return type

tuple[int, int, int]

static label_iter()

Iterate over all color label properties in the Color class

Returns

an iterator representing the name of the color properties

Return type

iter

static rgb_to_hex(r, g, b)

Convert rgb to hexadecimal color value

Parameters

• r (int) – red

• g (int) – green

• b (int) – blue

Returns

a hexadecimal colorl value

Return type

str

set(color_label, color_value)

Set a color property

Parameters

• color_label (str) – the name of the color to be set (key)

• color_value (str) – a hexadecimal color value

Example

static update_hsv(color, hd=0, sd=0, vd=0)

Modify the hue, saturation, and/or value of a given hex color value.

Parameters

• color (str) – the hexadecimal color value that is the target of hsv changes.

• hd (float) – % change in hue

• sd (float) – % change in saturation

• vd (float) – % change in value

Returns

a new hexadecimal color value that results from the hsv arguments passed into the function

Return type

str

Style

class ttkbootstrap.Style(theme='flatly', themes_file=None, *args, **kwargs)

Bases: tkinter.ttk.Style

A class for setting the application style.

Sets the theme of the tkinter.Tk instance and supports all ttkbootstrap and ttk themes provided. This class is meant to be a drop-in replacement for ttk.Style and inherits all of it’s methods and properties. Creating a Style object will instantiate the tkinter.Tk instance in the Style.master property, and so it is not necessary to explicitly create an instance of tkinter.Tk. For more details on the ttk.Style class, see the python documentation.

# instantiate the style with default theme *flatly*
style = Style()

# instantiate the style with another theme
style = Style(theme='superhero')

# instantiate the style with a theme from a specific themes file
style = Style(theme='custom_name', themes_file='C:/example/my_themes.json')

# available themes
for theme in style.theme_names():
    print(theme)

Parameters

• theme (str) – the name of the theme to use at runtime; flatly by default.

• themes_file (str) – Path to a user-defined themes file. Defaults to the themes file set in ttkcreator.

configure(style, query_opt=None, **kw)

Query or sets the default value of the specified option(s) in style.

Each key in kw is an option and each value is either a string or a sequence identifying the value for that option.

element_create(elementname, etype, *args, **kw)

Create a new element in the current theme of given etype.

element_names()

Returns the list of elements defined in the current theme.

element_options(elementname)

Return the list of elementname’s options.

layout(style, layoutspec=None)

Define the widget layout for given style. If layoutspec is omitted, return the layout specification for given style.

layoutspec is expected to be a list or an object different than None that evaluates to False if you want to “turn off” that style. If it is a list (or tuple, or something else), each item should be a tuple where the first item is the layout name and the second item should have the format described below:

LAYOUTS

A layout can contain the value None, if takes no options, or a dict of options specifying how to arrange the element. The layout mechanism uses a simplified version of the pack geometry manager: given an initial cavity, each element is allocated a parcel. Valid options/values are:

side: whichside

Specifies which side of the cavity to place the element; one of top, right, bottom or left. If omitted, the element occupies the entire cavity.

sticky: nswe

Specifies where the element is placed inside its allocated parcel.

children: [sublayout… ]

Specifies a list of elements to place inside the element. Each element is a tuple (or other sequence) where the first item is the layout name, and the other is a LAYOUT.

lookup(style, option, state=None, default=None)

Returns the value specified for option in style.

If state is specified it is expected to be a sequence of one or more states. If the default argument is set, it is used as a fallback value in case no specification for option is found.

map(style, query_opt=None, **kw)

Query or sets dynamic values of the specified option(s) in style.

Each key in kw is an option and each value should be a list or a tuple (usually) containing statespecs grouped in tuples, or list, or something else of your preference. A statespec is compound of one or more states and then a value.

register_theme(definition)

Registers a theme definition for use by the Style class.

This makes the definition and name available at run-time so that the assets and styles can be created.

Parameters

definition (ThemeDefinition) – an instance of the ThemeDefinition class

theme_create(themename, parent=None, settings=None)

Creates a new theme.

It is an error if themename already exists. If parent is specified, the new theme will inherit styles, elements and layouts from the specified parent theme. If settings are present, they are expected to have the same syntax used for theme_settings.

theme_names()

Returns a list of all known themes.

theme_settings(themename, settings)

Temporarily sets the current theme to themename, apply specified settings and then restore the previous theme.

Each key in settings is a style and each value may contain the keys ‘configure’, ‘map’, ‘layout’ and ‘element create’ and they are expected to have the same format as specified by the methods configure, map, layout and element_create respectively.

theme_use(themename=None)

Changes the theme used in rendering the application widgets.

If themename is None, returns the theme in use, otherwise, set the current theme to themename, refreshes all widgets and emits a <<ThemeChanged>> event.

Only use this method if you are changing the theme during runtime. Otherwise, pass the theme name into the Style constructor to instantiate the style with a theme.

Keyword Arguments

themename (str) – the theme to apply when creating new widgets

StylerTTK

class ttkbootstrap.StylerTTK(style, definition)

Bases: object

A class to create a new ttk theme.

Create a new ttk theme by using a combination of built-in themes and some image-based elements using pillow. A theme is generated at runtime and is available to use with the Style class methods. The base theme of all ttkbootstrap themes is clam. In many cases, widget layouts are re-created using an assortment of elements from various styles such as clam, alt, default, etc…

theme_images

theme assets used for various widgets.

Type

dict

settings

settings used to build the actual theme using the theme_create method.

Type

dict

styler_tk

an object used to style tkinter widgets (not ttk).

Type

StylerTk

theme

the theme settings defined in the themes.json file.

Type

ThemeDefinition

Parameters

• style (Style) – an instance of ttk.Style.

• definition (ThemeDefinition) – an instance of ThemeDefinition; used to create the theme settings.

create_theme()

Create and style a new ttk theme. A wrapper around internal style methods.

update_ttk_theme_settings()

Update the settings dictionary that is used to create a theme. This is a wrapper on all the _style_widget methods which define the layout, configuration, and styling mapping for each ttk widget.

StylerTK

class ttkbootstrap.StylerTK(styler_ttk)

Bases: object

A class for styling tkinter widgets (not ttk).

Several ttk widgets utilize tkinter widgets in some capacity, such as the popdownlist on the ttk.Combobox. To create a consistent user experience, standard tkinter widgets are themed as much as possible with the look and feel of the ttkbootstrap theme applied. Tkinter widgets are not the primary target of this project; however, they can be used without looking entirely out-of-place in most cases.

master

the root window.

Type

Tk

theme

the color settings defined in the themes.json file.

Type

ThemeDefinition

Parameters

styler_ttk (StylerTTK) – an instance of the StylerTTK class.

style_tkinter_widgets()

A wrapper on all widget style methods. Applies current theme to all standard tkinter widgets

ThemeDefinition

class ttkbootstrap.ThemeDefinition(name='default', themetype='light', font='helvetica', colors=None)

Bases: object

A class to provide defined name, colors, and font settings for a ttkbootstrap theme.

Parameters

• name (str) – the name of the theme; default is ‘default’.

• themetype (str) – the type of theme: light or dark; default is ‘light’.

• font (str) – the default font to use for the application; default is ‘helvetica’.

• colors (Colors) – an instance of the Colors class. One is provided by default.

Widgets

Button

class ttkbootstrap.widgets.Button(parent=None, **kwargs)

Bases: tkinter.ttk.Button

Ttk button widget, displays as a textual label and/or image, and evaluates a command when pressed.

Parameters

parent (Widget) – The parent widget.

Keyword Arguments

• class (str) – Specifies the window class. The class is used when querying the option database for the window’s other options, to determine the default bindtags for the window, and to select the widget’s default layout and style. This is a read-only option; it may only be specified when the window is created, and may not be changed with the configure widget command.

• compound (str) – Specifies if the widget should display text and bitmaps/images at the same time, and if so, where the bitmap/image should be placed relative to the text. Must be one of the values none, bottom, top, left, right, or center. For example, the (default) value none specifies that the bitmap or image should (if defined) be displayed instead of the text, the value left specifies that the bitmap or image should be displayed to the left of the text, and the value center specifies that the bitmap or image should be displayed underneath the text.

• cursor (str) – Specifies the mouse cursor to be used for the widget. Names and values will vary according to your operating system. Examples can be found here: https://anzeljg.github.io/rin2/book2/2405/docs/tkinter/cursors.html

• image (PhotoImage or str) – Specifies an image to display in the widget, which must have been created with tk.PhotoImage or TkPhotoImage` if using pillow. Can also be a string representing the name of the photo if the photo has been given a name using the name parameter. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget, though this is controlled by the compound option; the image option may be reset to an empty string to re-enable a bitmap or text display.

• state (str) – May be set to normal or disabled to control the disabled state bit. This is a write-only option; setting it changes the widget state, but the state widget command does not affect the state option.

• style (str) – May be used to specify a custom widget style.

• takefocus (bool) – Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). To remove the widget from focus traversal, use takefocus=False.

• text (str) – Specifies a string to be displayed inside the widget.

• textvariable (StringVar or str) – Specifies the name of a variable. Use the StringVar or the string representation if the variable has been named. The value of the variable is a text string to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value.

• underline (int) – Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on.

• width (int) – If the label is text, this option specifies the absolute width of the text area on the button, as a number of characters; the actual width is that number multiplied by the average width of a character in the current font. For image labels, this option is ignored. The option may also be configured in a style.

• command (func) – A callback function to evaluate when the widget is invoked.

invoke()

Invokes the command associated with the button.

Calendar

Classes and functions that enable the user to select a date.

ask_date

ttkbootstrap.widgets.calendar.ask_date(parent=None, startdate=None, firstweekday=6, style='TCalendar')

Generate a popup date chooser and return the selected date

Parameters

• parent (Widget) – The parent widget; the popup will appear to the bottom-right of the parent widget. If no parent is provided, the widget is centered on the screen.

• firstweekday (int) – Specifies the first day of the week. 0 is Monday, 6 is Sunday (the default).

• startdate (datetime) – The date to be in focus when the widget is displayed; defaults to the current date.

• style (str) – The ttk style used to render the widget.

Returns

The date selected; the current date if no date is selected.

DateChooserPopup

class ttkbootstrap.widgets.calendar.DateChooserPopup(parent=None, firstweekday=6, startdate=None, style='TCalendar')

Bases: object

A custom ttkbootstrap widget that displays a calendar and allows the user to select a date which is returned as a datetime object for the date selected.

The widget displays the current date by default unless a startdate is provided. The month can be changed by clicking on the chevrons to the right and left of the month-year title which is displayed on the top-center of the widget. A “left-click” will move the calendar one month. A “right-click” will move the calendar one year.

A “right-click” on the month-year title will reset the calendar widget to the starting date.

The starting weekday can be changed with the firstweekday parameter for geographies that do not start the week on Sunday, which is the widget default.

The widget grabs focus and all screen events until released. If you want to cancel a date selection, you must click on the “X” button at the top-right hand corner of the widget.

Styles can be applied to the widget by using the TCalendar style with the optional colors: ‘primary’, ‘secondary’, ‘success’, ‘info’, ‘warning’, and ‘danger’. By default, the primary.TCalendar style is applied.

Parameters

• parent (Widget) – The parent widget; the popup is displayed to the bottom-right of the parent widget.

• startdate (datetime) – The date to be in focus when the calendar is displayed. Current date is default.

• firstweekday (int) – Specifies the first day of the week. 0 is Monday, 6 is Sunday (the default).

• style (str) – The ttk style used to render the widget.

• **kw –

draw_calendar()

Create the days of the week elements

draw_titlebar()

Create the title bar

generate_widget_styles()

Generate all the styles required for this widget from the base_style.

on_date_selected(index)

Callback for selecting a date.

Assign the selected date to the date_selected property and then destroy the toplevel widget.

Parameters

index (Tuple[int]) – a tuple containing the row and column index of the date selected to be found in the monthdates property.

on_next_month()

Callback for changing calendar to next month

on_next_year(*args)

Callback for changing calendar to next year

on_prev_month()

Callback for changing calendar to previous month

on_prev_year(*args)

Callback for changing calendar to previous year

on_reset_date(*args)

Callback for clicking the month-year title; reset the date to the start date

set_geometry()

Adjust the window size based on the number of weeks in the month

setup()

Setup the calendar widget

weekday_header()

Creates and returns a list of weekdays to be used as a header in the calendar based on the firstweekday. The order of the weekdays is based on the firstweekday property.

Returns

a list of weekday headers

Return type

List

DateEntry

class ttkbootstrap.widgets.calendar.DateEntry(master=None, dateformat='%Y-%m-%d', firstweekday=6, startdate=None, style='TCalendar', **kw)

Bases: tkinter.ttk.Frame

A date entry widget that combines a ttk.Combobox and a ttk.Button`` with a callback attached to the ask_date function.

When pressed, displays a date chooser popup and then inserts the returned value into the combobox.

Optionally set the startdate of the date chooser popup by typing in a date that is consistent with the format that you have specified with the dateformat parameter. By default this is %Y-%m-%d.

Change the style of the widget by using the TCalendar style, with the colors: ‘primary’, ‘secondary’, ‘success’, ‘info’, ‘warning’, ‘danger’. By default, the primary.TCalendar style is applied.

Change the starting weekday with the firstweekday parameter for geographies that do not start the week on Sunday, which is the widget default.

Parameters

• master (Widget) – The parent widget.

• dateformat (str) – The format string used to render the text in the entry widget. Default is ‘%Y-%m-%d’. For more information on date formats, see the python documentation or https://strftime.org/.

• firstweekday (int) – Specifies the first day of the week. 0 is Monday, 6 is Sunday (the default).

• startdate (datetime) – The date to be in focus when the calendar is displayed. Current date is default.

• **kw – Optional keyword arguments to be passed to containing frame widget.

convert_system_color(systemcolorname)

Convert a system color name to a hexadecimal value

Parameters

systemcolorname (str) – a system color name, such as SystemButtonFace

draw_button_image(color)

Draw a calendar button image of the specified color

Image reference: https://www.123rf.com/photo_117523637_stock-vector-modern-icon-calendar-button-applications.html

Parameters

color (str) – the color to draw the image foreground.

Returns

the image created for the calendar button.

Return type

PhotoImage

generate_widget_styles()

Generate all the styles required for this widget from the base_style.

Returns

the styles to be used for entry and button widgets.

Return type

Tuple[str]

on_date_ask()

A callback for the date push button.

Try to grab the initial date from the entry if possible. However, if this date is not valid, use the current date and print a warning message to the console.

Floodgauge

class ttkbootstrap.widgets.Floodgauge(master=None, cursor=None, font=None, length=None, maximum=100, mode='determinate', orient='horizontal', style='TFloodgauge', takefocus=False, text=None, value=0, **kw)

Bases: tkinter.ttk.Progressbar

A Floodgauge widget shows the status of a long-running operation with an optional text indicator.

Similar to the ttk.Progressbar, this widget can operate in two modes: determinate mode shows the amount completed relative to the total amount of work to be done, and indeterminate mode provides an animated display to let the user know that something is happening.

Variable are generated automatically for this widget and can be linked to other widgets by referencing them via the textvariable and variable attributes.

The text and value properties allow you to easily get and set the value of these variables without the need to call the get and set methods of the related tkinter variables. For example: Floodgauge.value or Floodgauge.value = 55 will get or set the amount used on the widget.

Parameters

• master (Widget) – Parent widget

• cursor (str) – The cursor that will appear when the mouse is over the progress bar.

• font (Font or str) – The font to use for the progress bar label.

• length (int) – Specifies the length of the long axis of the progress bar (width if horizontal, height if vertical); defaults to 300.

• maximum (float) – A floating point number specifying the maximum value. Defaults to 100.

• mode (str) – One of determinate or indeterminate. Use indeterminate if you cannot accurately measure the relative progress of the underlying process. In this mode, a rectangle bounces back and forth between the ends of the widget once you use the .start() method. Otherwise, use determinate if the relative progress can be calculated in advance. This is the default mode.

• orient (str) – Specifies the orientation of the widget; either horizontal or vertical.

• style (str) – The style used to render the widget; TFloodgauge by default.

• takefocus (bool) – This widget is not included in focus traversal by default. To add the widget to focus traversal, use takefocus=True.

• text (str) – A string of text to be displayed in the progress bar. This is assigned to the textvariable StringVar which is automatically generated on instantiation. This value can be get and set using the Floodgauge.text property without having to directly call the textvariable.

• value – The current value of the progressbar. In determinate mode, this represents the amount of work completed. In indeterminate mode, it is interpreted modulo maximum; that is, the progress bar completes one “cycle” when the value increases by maximum.

• **kw – Other configuration options from the option database.

start(interval=None)

Begin autoincrement mode: schedules a recurring timer event that calls method step every interval milliseconds.

interval defaults to 50 milliseconds (20 steps/second) if omitted.

step(amount=None)

Increments the value option by amount.

amount defaults to 1.0 if omitted.

stop()

Stop autoincrement mode: cancels any recurring timer event initiated by start.

Meter

class ttkbootstrap.widgets.Meter(master=None, arcrange=None, arcoffset=None, amounttotal=100, amountused=0, interactive=False, labelfont='Helvetica 10 bold', labelstyle='secondary.TLabel', labeltext=None, metersize=200, meterstyle='TMeter', metertype='full', meterthickness=10, showvalue=True, stripethickness=0, textappend=None, textfont='Helvetica 25 bold', textprepend=None, wedgesize=0, **kw)

Bases: tkinter.ttk.Frame

A radial meter that can be used to show progress of long running operations or the amount of work completed; can also be used as a Dial when set to interactive=True.

This widget is very flexible. There are two primary meter types which can be set with the metertype parameter: ‘full’ and ‘semi’, which show the arc of the meter in a full or semi-circle. You can also customize the arc of the circle with the arcrange and arcoffset parameters.

The progress bar indicator can be displayed as a solid color or with stripes using the stripethickness parameter. By default, the stripethickness is 0, which results in a solid progress bar. A higher stripethickness results in larger wedges around the arc of the meter.

Various text and label options exist. The center text and progressbar is formatted with the meterstyle parameter and uses the TMeter styles. You can prepend or append text to the center text using the textappend and textprepend parameters. This is most commonly used for ‘$’, ‘%’, or other such symbols.

Variable are generated automatically for this widget and can be linked to other widgets by referencing them via the amountusedvariable and amounttotalvariable attributes.

The variable properties allow you to easily get and set the value of these variables. For example: Meter.amountused or Meter.amountused = 55 will get or set the amount used on the widget without having to call the get or set methods of the tkinter variable.

Parameters

• master (Widget) – Parent widget

• arcoffset (int) – The amount to offset the arc’s starting position in degrees; 0 is at 3 o’clock.

• arcrange (int) – The range of the arc in degrees from start to end.

• amounttotal (int) – The maximum value of the meter.

• amountused (int) – The current value of the meter; displayed if showvalue=True.

• interactive (bool) – Enables the meter to be adjusted with mouse interaction.

• labelfont (Font or str) – The font of the supplemental label.

• labelstyle (str) – The ttk style used to render the supplemental label.

• labeltext (str) – Supplemental label text that appears below the center text.

• metersize (int) – The size of the meter; represented by one side length of a square.

• meterstyle (str) – The ttk style used to render the meter and center text.

• metertype (str) – One of full or semi; displays a full-circle or semi-circle.

• meterthickness (int) – The thickness of the meter’s progress bar.

• showvalue (bool) – Show the meter’s value in the center text; default = True.

• stripethickness (int) – The meter’s progress bar can be displayed in solid or striped form. If the value is greater than 0, the meter’s progress bar changes from a solid to striped, where the value is the thickness of the stripes.

• textappend (str) – A short string appended to the center text.

• textfont (Font or str) – The font of the center text.

• textprepend (str) – A short string prepended to the center text.

• wedgesize (int) – If greater than zero, the width of the wedge on either side of the current meter value.

convert_system_color(systemcolorname)

Convert a system color name to a hexadecimal value

Parameters

systemcolorname (str) – a system color name, such as SystemButtonFace

draw_base_image()

Draw the base image to be used for subsequent updates

draw_meter(*args)

Draw a meter

Parameters

*args – if triggered by a trace, will be variable, index, mode.

draw_solid_meter(draw)

Draw a solid meter

Parameters

draw (ImageDraw.Draw) – an object used to draw an arc on the meter

draw_striped_meter(draw)

Draw a striped meter

Parameters

draw (ImageDraw.Draw) – an object used to draw an arc on the meter

lookup(style, option)

Wrapper around the tcl style lookup command

Parameters

• style (str) – the name of the style used for rendering the widget.

• option (str) – the option to lookup from the style option database.

Returns

the value of the option looked up.

Return type

any

meter_value()

Calculate the meter value

Returns

the value to be used to draw the arc length of the progress meter

Return type

int

on_dial_interact(e)

Callback for mouse drag motion on indicator

Parameters

e (Event) – event callback for drag motion.

step(delta=1)

Increase the indicator value by delta.

The default increment is 1. The indicator will reverse direction and count down once it reaches the maximum value.

Keyword Arguments

delta (int) – the amount to change the indicator.