TimeLine

class ttkwidgets.TimeLine(master=None, **kwargs)

Bases: ttk.Frame

A Frame containing a Canvas and various buttons to manage a timeline that can be marked with certain events, allowing the binding of commands to hovering over certain elements and creating texts inside the elements.

Each marker is pretty much a coloured rectangle with some optional text, that can be assigned tags. Tags may specify the colors of the marker, but tags can also be assigned callbacks that can be called with the identifier of the tag as well as a Tkinter event instance that was generated upon clicking. For example, the markers may be moved, or the user may want to add a menu that shows upon right-clicking. See the create_marker() function for more details on the markers.

The markers are put into a Canvas, which contains rows for each category. The categories are indicated by Labels and separated by black separating lines. Underneath the rows of categories, there is a second Canvas containing markers for the ticks of the time unit. Some time units get special treatment, such as “h” and “m”, displayed in an appropriate H:M and M:S format respectively.

The height of the row for each category is automatically adjusted to the height of its respective Label to give a uniform appearance. All markers are redrawn if draw_timeline() is called, and therefore it should be called after any size change. Depending on the number of markers to draw, it may take a long time.

The TimeLine can be scrolled in two ways: horizontally (with _scrollbar_timeline) and vertically (with _scrollbar_timeline_v), which both use a class function as a proxy to allow for other functions to be called upon scrolling. The horizontal scrollbar makes a small pop-up window appear to indicate the time the cursor is currently pointing at on the timeline.

The markers can be retrieved from the class using the markers property, and they can be saved and then the markers can be recreated by calling create_marker() again for each marker. This functionality is not built into the class, if the user wants to do something like this, he or she should write the code required, as it can be done in different ways.

Some of the code has been inspired by the ItemsCanvas, as that is also a Canvas that supports the manipulation of items, but as this works in a fundamentally different way, the classes do not share any common parent class.

Warning

This widget is absolutely not thread-safe, and it was not designed as such. It may work in some situations, but nothing is guaranteed when using this widget from multiple threads, even with Tkinter compiled with thread-safe flags or when using mtTkinter for Python 2.

Note

Some themes may conflict with this widget, for example because it makes the default font bigger for the category Labels. This should be fixed by the user by modifying the “TimeLine.T(Widget)” style.

__init__(master=None, **kwargs)

Create a TimeLine widget

The style of the buttons can be modified by using the “TimeLine.TButton” style. The style of the surrounding Frame can be modified by using the “TimeLine.TFrame” style, or by specifying another style in the keyword arguments. The style of the category Labels can be modified by using the “TimeLine.TLabel” style.

Base TimeLine Widget Options

Parameters:

• width (int) – Width of the timeline in pixels
• height (int) – Height of the timeline in pixels
• extend (bool) – Whether to extend when an item is moved out of range
• start (float) – Value to start the timeline at
• finish (float) – Value to end the timeline at
• resolution (int) – Amount of time per pixel [s/pixel]
• tick_resolution (int) – Amount of time between ticks on the timeline
• unit (str) – Unit of time. Some units have predefined properties, such as minutes (‘m’) and hours (‘h’), which make the tick markers have an appropriate format.
• zoom_enabled (bool) – Whether to allow zooming on the timeline using the zoom buttons
• categories (dict[Any, dict]) – A dictionary with the names of the categories as the keys and the keyword argument dictionaries as values. Use an OrderedDict in order to preserve category order.
• background (str) – Background color for the Canvas widget
• style (str) – Style to apply to the Frame widget
• zoom_factors (tuple[float]) – Tuple of allowed zoom levels. For example: (1.0, 2.0, 5.0). The order of zoom levels is preserved.
• zoom_default (float) – Default zoom level to apply to the timeline
• snap_margin (int) – Amount of pixels between start and/or finish of a marker and a tick on the timeline before the marker is snapped into place
• menu (tk.Menu) – Menu to show when a right-click is performed somewhere on the TimeLine without a marker being active
• autohidescrollbars (bool) – whether to use AutoHideScrollbar or ttk.Scrollbar for the scrollbars

Marker Default Options

Parameters:

• marker_font (tuple) – Font tuple to specify the default font for the markers
• marker_background (str) – Default background color for markers
• marker_foreground (str) – Default foreground color for markers
• marker_outline (str) – Default outline color for the markers
• marker_border (int) – Border width in pixels
• marker_move (bool) – Whether markers are allowed to move by default
• marker_change_category (bool) – Whether markers are allowed to change category by being dragged vertically
• marker_allow_overlap (bool) – Whether the markers are allowed to overlap. This setting is only enforced on the marker being moved. This means that when inserting markers, no errors will be raised, even with overlaps, and when an overlap-allowing marker is moved over an overlap-disallowing marker and overlap will still occur.
• marker_snap_to_ticks – Whether the markers should snap to the ticks when moved close to ticks automatically

active

Currently selected marker

Return type:str

static calculate_text_coords(rectangle_coords)

Calculate Canvas text coordinates based on rectangle coords

call_callbacks(iid, type, args)

Call the available callbacks for a certain marker

Parameters:

• iid (str) – marker identifier
• type (str) – type of callback (key in tag dictionary)
• args (tuple) – arguments for the callback

Returns:

amount of callbacks called

Return type:

int

cget(item)

Return the value of an option

static check_kwargs(kwargs)

Check the type and values of keyword arguments to __init__()

Parameters:kwargs (dict[str, Any]) – Dictionary of keyword arguments Raises:TypeError, ValueError

check_marker_kwargs(kwargs)

Check the types of the keyword arguments for marker creation

Parameters:kwargs (dict) – dictionary of options for marker creation Raises:TypeError, ValueError

clear_timeline()

Clear the contents of the TimeLine Canvas

Does not modify the actual markers dictionary and thus after redrawing all markers are visible again.

config(cnf={}, **kwargs)

Update options of the TimeLine widget

configure(cnf={}, **kwargs)

Update options of the TimeLine widget

create_marker(category, start, finish, marker=None, **kwargs)

Create a new marker in the TimeLine with the specified options

Parameters:

• category (Any) – Category identifier, key as given in categories dictionary upon initialization
• start (float) – Start time for the marker
• finish (float) – Finish time for the marker
• marker (dict[str, Any]) – marker dictionary (replaces kwargs)

Marker Options

Options can be given either in the marker dictionary argument, or as keyword arguments. Given keyword arguments take precedence over tag options, which take precedence over default options.

Parameters:

• text (str) – Text to show in the marker. Text may not be displayed fully if the zoom level does not allow the marker to be wide enough. Updates when resizing the marker.
• background (str) – Background color for the marker
• foreground (str) – Foreground (text) color for the marker
• outline (str) – Outline color for the marker
• border (int) – The width of the border (for which outline is the color)
• font (tuple) – Font tuple to set for the marker
• iid (str) – Unique marker identifier to use. A marker is generated if not given, and its value is returned. Use this option if keeping track of markers in a different manner than with auto-generated iid’s is necessary.
• tags (tuple[str]) – Set of tags to apply to this marker, allowing callbacks to be set and other options to be configured. The option precedence is from the first to the last item, so the options of the last item overwrite those of the one before, and those of the one before that, and so on.
• move (bool) – Whether the marker is allowed to be moved

Additionally, all the options with the marker_ prefix from __init__(), but without the prefix, are supported. Active state options are also available, with the active_ prefix for background, foreground, outline, border. These options are also available for the hover state with the hover_ prefix.

Returns:identifier of the created marker Return type:str Raises:ValueError – One of the specified arguments is invalid

create_scroll_region()

Setup the scroll region on the Canvas

current

Currently active item on the _timeline Canvas

Return type:str

current_iid

Currently active item’s iid

Return type:str

delete_marker(iid)

Delete a marker from the TimeLine

Parameters:iid (str) – marker identifier

draw_categories()

Draw the category labels on the Canvas

draw_markers()

Draw all created markers on the TimeLine Canvas

draw_separators()

Draw the lines separating the categories on the Canvas

draw_ticks()

Draw the time tick markers on the TimeLine Canvas

draw_time_marker()

Draw the time marker on the TimeLine Canvas

draw_timeline()

Draw the contents of the whole TimeLine Canvas

get_position_time(position)

Get time for x-coordinate

Parameters:position (int) – X-coordinate position to determine time for Returns:Time for the given x-coordinate Return type:float

get_time_position(time)

Get x-coordinate for given time

Parameters:time (float) – Time to determine x-coordinate on Canvas for Returns:X-coordinate for the given time Return type:int Raises:ValueError

static get_time_string(time, unit)

Create a properly formatted string given a time and unit

Parameters:

• time (float) – Time to format
• unit (str) – Unit to apply format of. Only supports hours (‘h’) and minutes (‘m’).

Returns:

A string in format ‘{whole}:{part}’

Return type:

str

grid_widgets()

Configure all widgets using the grid geometry manager

Automatically called by the __init__() method. Does not have to be called by the user except in extraordinary cases.

itemconfigure(iid, rectangle_options, text_options)

Configure options of items drawn on the Canvas

Low-level access to the individual elements of markers and other items drawn on the timeline Canvas. All modifications are overwritten when the TimeLine is redrawn.

marker_options

List of available options to create_marker

marker_tags(iid)

Generator for all the tags of a certain marker

markers

Return a dictionary with categories as keys

Return type:dict[str, dict[str, Any]]

options

List of available options to __init__()

pixel_width

Width of the whole TimeLine in pixels

Return type:int

static range(start, finish, step)

Like built-in range(), but with float support

set_time(time)

Set the time marker to a specific time

Parameters:time (float) – Time to set for the time marker on the TimeLine

set_zoom_factor(factor)

Manually set a custom zoom factor

Parameters:factor (float) – Custom zoom factor

tag_configure(tag_name, **kwargs)

Create a marker tag

Parameters:

• tag_name – Identifier for the tag
• move_callback (callable) – Callback to be called upon moving a marker. Arguments to callback: (iid: str, (old_start: float, old_finish: float), (new_start: float, new_finish: float))
• left_callback (callable) – Callback to be called upon left clicking a marker. Arguments to callback: (iid: str, x_coord: int, y_coord: int)
• right_callback (callable) – Callback to be called upon right clicking a marker. Arguments to callback: (iid: str, x_coord: int, y_coord: int)
• menu (tk.Menu) – A Menu widget to show upon right click. Can be used with the right_callback option simultaneously.

In addition, supports all options supported by markers. Note that tag options are applied to markers upon marker creation, and thus is a tag is updated, the markers are not automatically updated as well.

time

Current value the time marker is pointing to

Return type:float

update_active()

Update the active marker on the marker Canvas

update_marker(iid, **kwargs)

Change the options for a certain marker and redraw the marker

Parameters:

• iid (str) – identifier of the marker to change
• kwargs (dict) – Dictionary of options to update

Raises:

ValueError

update_state(iid, state)

Set a custom state of the marker

Parameters:

• iid (str) – identifier of the marker to set the state of
• state (str) – supports “active”, “hover”, “normal”

zoom_factor

Return the current zoom factor

Return type:float

zoom_in()

Increase zoom factor and redraw TimeLine

zoom_out()

Decrease zoom factor and redraw TimeLine

zoom_reset()

Reset the zoom factor to default and redraw TimeLine