Core

These are the foundational classes that every myTk application uses.

App

app.py — Main base application class using myTk framework.

This module defines the App class, which serves as the main controller of a Tkinter application built with the myTk framework.

It handles window creation, menu setup, platform-specific quirks, and help/documentation integration.

Classes:

• App: The main application object, integrating window, menu, and lifecycle management.

Typical usage:

from mytk.app import App

class MyApp(App):

def save(self):

…

def preferences(self):

…

app = MyApp(geometry=”800x600”, name=”MyApp”) app.mainloop()

class mytk.app.App(*args, geometry=None, auto_position='center', name='myTk App', help_url=None, bring_to_front=False, no_window=False, **kwargs)

Bases: Bindable, EventCapable

Main application class for a myTk-based GUI.

This class integrates the Window, Bindable, and EventCapable behaviors into a single application controller. It manages the main window, menu bar, help system, and platform-specific requirements.

app

Class-level reference to the current App instance.

Type:

App

name

Application name.

Type:

str

help_url

Optional URL to the help/documentation site.

Type:

str

window

The main application window.

Type:

Window

property widget

Returns the root Tk widget.

Returns:

The root Tk window.

Return type:

tk.Tk

property root

Returns the root window widget.

Returns:

The application’s root window.

Return type:

tk.Tk

property is_running

Indicates whether the application is currently running.

Returns:

True if the window exists; False otherwise.

Return type:

bool

check_requirements()

Warns the user if Python version is too old for the current macOS.

Helps avoid click event issues on macOS Sonoma and older Python versions.

mainloop()

Enters the Tkinter main event loop.

schedule_on_main_thread(fct, args=None, kwargs=None)

Schedules a function call to be executed on the main thread.

Parameters:

• fct (callable) – The function to call.

• args (list, optional) – Positional arguments for the function.

• kwargs (dict, optional) – Keyword arguments for the function.

run_main_queue()

Processes all pending tasks in the main thread queue.

create_menu()

Creates the application menu bar with File, Edit, and Help items.

reveal_path(path)

Reveals the file or directory path in the system’s file browser.

Parameters:

path (str) – The path to reveal.

save()

Saves application data; must be overridden in subclasses.

preferences()

Shows preferences UI; must be overridden in subclasses.

about(timeout=3000)

Displays an About dialog with app information.

Parameters:

timeout (int) – Optional time before auto-close in milliseconds.

help()

Opens the documentation help URL in a browser if available.

Falls back to an info dialog if no help URL has been configured.

quit()

Quits the application gracefully and destroys the root window.

Cancels any scheduled tasks before teardown.

Base

Base module for custom Tkinter widget behavior.

This module defines a Base class that extends Bindable to provide a unified interface for managing Tkinter widget state, dynamic geometry placement, event binding, and lifecycle scheduling.

Includes support for property observation, variable binding, and diagnostic output.

class mytk.base.BaseNotification(*values)

Bases: Enum

Enum for core notification messages emitted by Base-derived classes.

class mytk.base.Base(*args, **kwargs)

Bases: _BaseWidget, Bindable, EventCapable

Composite base class combining widget management, binding, and event capabilities.

bind_textvariable(variable)

Binds a textvariable (e.g., StringVar) to the widget.

Parameters:

variable (tk.Variable) – The variable to bind.

bind_variable(variable)

Binds a general-purpose variable (e.g., BooleanVar, IntVar).

Parameters:

variable (tk.Variable) – The variable to bind.

Bindable

Property-Observer and Binding Mechanism for Python/Tkinter.

This class implements a Property-Value-Observer pattern, which allows objects to observe changes in specific attributes of other objects. It supports both traditional Python attributes and Tkinter Variable instances, making it suitable for reactive GUI programming in Tkinter.

It enables: 1. Observing changes in object properties, with optional context. 2. Automatically synchronizing (binding) two properties so that changing one updates the other.

This is inspired by macOS’s Key-Value-Observing (KVO) pattern, and can be used to build reactive MVC-style architectures in Python/Tkinter applications.

Classes:

• Bindable: Base class that supports observing and binding properties.

Usage Example:

class Model(Bindable):

def __init__(self):

super().__init__() self.name = tk.StringVar()

def observed_property_changed(self, observed, property_name, new_value, context):

print(f”{property_name} changed to {new_value}”)

model = Model() view = SomeWidget(…) model.bind_property_to_widget_value(“name”, view)

class mytk.bindable.ObserverInfo(observer, observed_property_name, context)

Bases: tuple

context

Alias for field number 2

observed_property_name

Alias for field number 1

observer

Alias for field number 0

class mytk.bindable.Bindable(*args, **kwargs)

Bases: object

A class to observe changes in variables and optionally bind variables together.

In general, this is called a “one-to-one” pattern because an observer registers specifically for a change in a specific object. To notify one-to-many, use the NotificationCenter.

It is also called a Property-Value-Observer pattern, identical to the Key-Value-Observer pattern on macOS.

It implements two functionalities:

1. a callback method to notify a specific object that a change occurred in another object. 2. a binding mechanism so that two properties are always synchronized, regardless of which one changed

add_observer(observer, my_property_name, context=None)

Register an observer for changes to a named property of this object.

When the property “my_property_name” of object “self” changes, the method “observed_property_changed” of object “observer” will be called. You must implement the following method signature in “observer”:

observer.observed_property_changed (observed_object, observed_property_name, new_value, context)

Based on either parameters, you can determine what to do: observed_property_name may be sufficient if you have only registered the observer for one thing, but you can also provide “context” when with anything you want and can be an indicator of what to do (e.g., context=”object_needs_refresh”).

We treat Tk.Variable() differently. We do not observe for a change in the actual value_variable (i.e. the Variable()): we observe if the Variable() changes its value. We really need this to integrate this observer pattern with Tk and generalize it to any property. To do so, we register à-la-TkVariable with trace_add and redirect the call with our observed_property_changed mechanism.

traced_tk_variable_changed(var, index, mode)

This function is called by tk when a Tk.Variable value is changed.

This is a hook function into our Property-Value-Observing mechanism. We do not observe for a change in the actual value_variable (i.e. the Variable()): we observe if the tk.Variable() changes its value. We need this to integrate this Property-Observer Pattern with Tk and generalize it to any property. To do so, we register à-la-TkVariable with trace_add (see above) and call our property_value_did_change mechanism.

property_value_did_change(property_name)

Notify all observers that a property value has changed.

Recovers all the parameters of the observer (who is observing and what is the context that was provided when registering) before calling the observer callback. Tk.Variables need special treatment because we are looking at their values, not the Tk.Variable object itself.

observed_property_changed(observed_object, observed_property_name, new_value, context)

Handle a property change notification in the observer.

But the binding mechanism uses the same Property-Value-Observing mechanism, and we can treat it without having the user do anything. Therefore, by default, we check to see if it is a binding, and if it is, we treat it, the subclass will not have anything to do. The context will be a dictionary and will have the key “binding”. If it does not, then it’s not a binding and that’s it. But if it is, we set the property (stored in context{‘binding’:variable_name}) of self to the new_value. Again, we treat Tk.Variable differently: we do not change the property that holds the Tk.Variable, we change its value.

If you are using the basic Property-Value-Observing pattern to be notified of a change in a property, then your class needs to override this observed_property_changed() and should perform whatever it wants to do based on the context, and then call super().observed_property_changed to benefit of property binding management.

bind_properties(this_property_name, other_object, other_property_name)

Bind two properties for two-way synchronization between objects.

Makes use of the Property-Value-Observing mechanism and uses the context to indicate that it is actually “a binding”. Changing one property will notify the other, which will be changed, and vice-versa.

bind_property_to_widget_value(property_name: str, control_widget: Base)

Binds an object property to the value_variable of a widget-like object.

The control_widget must define a value_variable attribute (typically a Tkinter Variable) which will remain synchronized with the given property of this object. This allows direct model-view bindings in Tkinter.

Window

window.py — Main application window class using Tkinter.

This module defines the Window class, which extends the custom Base class and creates a top-level Tkinter window using tk.Tk.

The Window class is the main entry point for GUI applications built with this framework. It supports geometry initialization, window title configuration, and resizability control.

Typical usage from the MyApp class:

from mytk.window import Window

main_window = Window(geometry=”800x600+100+100”, title=”My App”) main_window.widget.mainloop()

Classes:

• Window: Represents the main Tkinter application window.

class mytk.window.Window(*args, geometry=None, auto_position=None, title='Untitled', withdraw=False, **kwargs)

Bases: Base

A top-level application window.

Inherits from Base and wraps a tk.Tk instance to represent a main application window. Provides control over window geometry, title, and resizability.

widget

The main Tkinter window object.

Type:

tk.Tk

create_widget(master, **kwargs)

Creates the Tk root widget or raises if already created.

property title

Gets the current title of the window.

Returns:

The current title string.

Return type:

str

property resizable

Checks whether the window is resizable in either width or height.

Returns:

True if resizable in width or height; False otherwise.

Return type:

bool

Views

This module defines basic container widgets for layout composition in a Tkinter UI framework.

Classes:

• View: A generic frame for layout grouping.

• Box: A labeled frame for grouping related widgets, with an optional label and fixed size.

class mytk.views.View(width=None, height=None, *args, **kwargs)

Bases: Base

A generic frame container used to group widgets together.

Inherits from Base and wraps a ttk.Frame. Can be used to structure layouts or as a logical container.

Parameters:

• width (int) – Desired width of the frame.

• height (int) – Desired height of the frame.

• *args – Additional positional arguments passed to Base.

• **kwargs – Additional keyword arguments passed to Base.

create_widget(master, **kwargs)

Creates the underlying ttk.Frame widget.

Parameters:

• master (tk.Widget) – The parent widget.

• **kwargs – Additional keyword arguments (unused).

property is_disabled

Whether the view and its children are disabled.

class mytk.views.Box(*args, label='', width=None, height=None, **kwargs)

Bases: Base

A labeled frame (ttk.LabelFrame) used to visually group widgets with an optional title and fixed size.

Parameters:

• label (str) – The title displayed on the box.

• width (int, optional) – The width of the box in pixels.

• height (int, optional) – The height of the box in pixels.

• *args – Additional positional arguments passed to Base.

• **kwargs – Additional keyword arguments passed to Base.

create_widget(master, **kwargs)

Creates the underlying ttk.LabelFrame widget.

Parameters:

• master (tk.Widget) – The parent widget.

• **kwargs – Additional keyword arguments (unused).

property is_disabled

Whether the box and its children are disabled.

property label

Gets or sets the label text of the Box.

Returns:

The current label text.

Return type:

str