Thanks to visit codestin.com
Credit goes to github.com

Skip to content
/ tkface Public

A multilingual GUI extension library for Tkinter with enhanced dialogs, calendar widgets, and Windows-specific features.

License

Notifications You must be signed in to change notification settings

mashu3/tkface

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Tkface

License: MIT PyPI - Python Version GitHub Release PyPi Version Downloads Tests codecov CodeFactor

Restore the "face" to your Tkinter!

A multilingual GUI extension library for Tkinter (tkinter) - bringing back the "face" (interface) that Tkinter left behind. Built with zero external dependencies, using only Python's standard library.


πŸ“– Overview

Tkface is a Python library designed to restore and enhance the "face" (user interface) of Tkinter. While Tkinter is a powerful toolkit, its dialogs and user-facing components are minimal and lack friendly interfaces. Tkface fills this gap with multilingual dialogs, advanced message boxes, and Windows-specific features. The library is built entirely with Python's standard library, requiring no external dependencies.

  • Completing the Interface: Tkinter stands for "Tk interface," providing a powerful core for building GUIs. Tkface is designed to complement it by providing the user-facing componentsβ€”the "face"β€”that are essential for a polished user experience but not built into the standard library. It extends Tkinter with ready-to-use, multilingual dialogs and widgets, letting you build sophisticated, user-friendly applications with less effort.
  • Vibe Coding: Developed with a "Vibe Coding" approach-prioritizing developer joy, rapid prototyping, and a sense of fun. The codebase is hackable, readable, and easy to extendβ€”and so is this document.

πŸ”§ Requirements

  • Python 3.7+
  • Tkinter (included with Python)
  • Zero external dependencies - Uses only Python standard library

πŸ“¦ Installation

Install the latest version from PyPI:

pip install tkface

Or install from the GitHub repository for the latest changes:

pip install git+https://github.com/mashu3/tkface.git

πŸš€ Usage

Message Boxes

import tkface

# Simple information dialog
tkface.messagebox.showinfo("Operation completed successfully!")

# Multilingual support
tkface.messagebox.showerror("An error has occurred!", language="ja")

# With system sound (Windows only)
tkface.messagebox.showerror("An error has occurred!", bell=True)

# Confirmation dialog
if tkface.messagebox.askyesno("Do you want to save?"):
    # Handle save operation
    tkface.messagebox.showinfo("File saved successfully!")

Screenshots

Dialog Type Windows macOS
Warning Warning Dialog Warning Dialog
Error Error Dialog Error Dialog
Information Info Dialog Info Dialog
Question Question Dialog Question Dialog

Input Dialogs

import tkface

# String input
name = tkface.simpledialog.askstring("Enter your name:")

# Integer input with validation
age = tkface.simpledialog.askinteger("Enter your age:", minvalue=0, maxvalue=120)

# List selection dialog
color = tkface.simpledialog.askfromlistbox("Choose a color:", choices=["Red", "Green", "Blue"])

# Multiple selection dialog
colors = tkface.simpledialog.askfromlistbox("Choose colors:", choices=["Red", "Green", "Blue"], multiple=True)

File and Directory Selection Dialogs

import tkface

# Select a single file
file_path = tkface.pathchooser.askopenfile(
    title="Select a File",
    filetypes=[("Text files", "*.txt"), ("Python files", "*.py")]
)

# Select multiple files
file_paths = tkface.pathchooser.askopenfiles(
    title="Select Multiple Files",
    filetypes=[("Text files", "*.txt"), ("All files", "*.*")]
)

# Select a directory
directory = tkface.pathchooser.askdirectory(
    title="Select a Directory"
)

# Advanced file/directory selection
paths = tkface.pathchooser.askpath(
    select="both",           # "file", "dir", or "both"
    multiple=True,           # Allow multiple selection
    initialdir="/path/to/start",
    filetypes=[("Text files", "*.txt"), ("Log files", "*.log")]
)

Features:

  • Directory Tree: Hierarchical folder navigation with icons
  • File List: Details view with size, modification date, and file type
  • View Modes: Switch between list and details view
  • File Filtering: Filter by file type with dropdown
  • Path Navigation: Direct path entry with Go button
  • Refresh: Refresh current directory (F5 or Ctrl+R)
  • Multiple Selection: Select multiple files/directories
  • Keyboard Shortcuts: Enter (OK), Escape (Cancel), F5 (Refresh)

Note: All file dialog functions return a list of selected paths. If cancelled, an empty list is returned.

DatePicker Widgets

Screenshots

Widget Type Windows macOS
DateFrame DateFrame Widget DateFrame Widget

Usage Examples

Initial Date Behavior: When no year and month parameters are specified, both DateEntry and DateFrame automatically use the current date as the initial value. You can also explicitly set the initial date using the year and month parameters.

Navigation Features: The calendar widgets include intuitive navigation features:

  • Click on the year/month header to switch to year selection mode (3x4 month grid)
  • Click on a month in year selection mode to switch to that month
  • Use arrow buttons to navigate between months/years
  • All navigation maintains the selected date and theme settings
import tkinter as tk
import tkface

root = tk.Tk()
root.title("DateEntry Demo")

# Basic DateEntry (uses current date by default)
date_entry = tkface.DateEntry(root)
date_entry.pack(padx=10, pady=10)

# DateFrame with custom button text
date_frame = tkface.DateFrame(root, button_text="πŸ“…")
date_frame.pack(padx=10, pady=10)

# Advanced DateEntry with features
date_entry = tkface.DateEntry(
    root,
    show_week_numbers=True,      # Show week numbers
    week_start="Monday",         # Start week on Monday
    day_colors={                 # Color weekends
        "Sunday": "lightcoral",
        "Saturday": "lightblue"
    },
    holidays={                   # Highlight holidays
        "2025-08-15": "red",     # Custom holiday
        "2025-08-30": "blue"     # Another holiday
    },
    theme="light",               # Light theme
    language="ja"                # Japanese language
)

# DateEntry with specific initial date
date_entry_with_date = tkface.DateEntry(
    root,
    year=2025,                   # Set initial year
    month=8,                     # Set initial month
    date_format="%YεΉ΄%m月%dζ—₯"    # Japanese date format
)
date_entry_with_date.pack(padx=10, pady=10)

# Get selected date
selected_date = date_entry.get_date()
# Process the selected date as needed
if selected_date:
    # Handle the selected date
    pass

# Get selected date from specific date entry
selected_date_with_date = date_entry_with_date.get_date()

root.mainloop()

Key Parameters

Parameter Type Default Description
year int None (current year) Initial year to display
month int None (current month) Initial month to display
date_format str "%Y-%m-%d" Date format string
button_text str "πŸ“…" Button text (DateFrame only)
theme str "light" Theme: "light" or "dark"
language str "en" Language: "en" or "ja"

DateFrame vs DateEntry

  • DateFrame: Customizable button text, more flexible layout
  • DateEntry: Combobox-style appearance, standard system look

Windows-Specific Features

Tkface provides Windows-specific enhancements that automatically detect the platform and gracefully degrade on non-Windows systems. These features include DPI awareness, Windows 11 corner rounding control, and system sound integration.

DPI Awareness and Scaling

import tkinter as tk
import tkface

root = tk.Tk()

# Enable DPI awareness and automatic scaling
tkface.win.dpi(root)  # Enable DPI awareness

# Window geometry is automatically adjusted for DPI
root.geometry("600x400")  # Will be scaled appropriately

# UI elements are automatically scaled
button = tkface.Button(root, text="Scaled Button")
button.pack()

root.mainloop()

Other Windows Features

import tkinter as tk
import tkface

root = tk.Tk()
root.title("Windows Features Demo")

# Enable DPI awareness and automatic scaling
tkface.win.dpi(root)         # Enable DPI awareness (Windows only)

# Set window geometry
root.geometry("600x400")

# Create your widgets here
def on_button_click():
    tkface.messagebox.showinfo("Info", "Button clicked!")

button = tkface.Button(root, text="Flat Button", command=on_button_click)  # Flat styling on Windows
button.pack()

# Disable corner rounding (Windows 11 only) - call after all widgets are created
tkface.win.unround(root)     # Disable corner rounding (Windows 11 only)

# Play Windows system sound (Windows only)
tkface.win.bell("error")     # Play Windows system sound (Windows only)

root.mainloop()

Important: Call tkface.win.unround(root) after creating all widgets but before mainloop() to ensure the window is fully initialized.

Note: All Windows-specific features gracefully degrade on non-Windows platforms.

Language Management

import tkface
import tkinter as tk

root = tk.Tk()
tkface.lang.set("ja", root)  # Set language manually
tkface.lang.set("auto", root)  # Auto-detect system language

# Register custom translations
custom_translations = {
    "ja": {
        "Choose an option:": "γ‚ͺγƒ—γ‚·γƒ§γƒ³γ‚’ιΈζŠž:",
        "Option 1": "γ‚ͺプション1",
        "Option 2": "γ‚ͺプション2", 
        "Option 3": "γ‚ͺプション3"
    }
}
tkface.simpledialog.askfromlistbox(
    "Choose an option:",
    choices=["Option 1", "Option 2", "Option 3"],
    custom_translations=custom_translations,
    language="ja"
)

🧩 Features

  • Zero Dependencies: Built entirely with Python's standard library - no external packages required
  • Multilingual Support: Automatic language detection, English/Japanese built-in, custom dictionaries
  • Enhanced Message Boxes: All standard and advanced dialogs, custom positioning, keyboard shortcuts, tab navigation
  • Enhanced Input Dialogs: String/integer/float input, validation, password input, list selection, custom positioning
  • File and Directory Selection: Advanced file browser with directory tree, file filtering, multiple selection support
  • Calendar Widget: Multi-month display, week numbers, holiday highlighting, customizable colors, language support
  • Windows Features:
    • DPI Awareness: Automatic scaling for high-resolution displays
    • Windows 11 Corner Rounding Control: Modern UI appearance
    • Windows System Sounds: Platform-specific audio feedback
    • Flat Button Styling: Modern appearance without shadows
    • All features gracefully degrade on other OS

πŸ“ Examples

See the examples/ directory for complete working examples:

  • demo_messagebox.py - Message box demonstrations
  • demo_simpledialog.py - Input dialog demonstrations
  • demo_pathchooser.py - File and directory selection demonstrations
  • demo_calendar.py - Calendar widget demonstrations
  • demo_windows_features.py - Windows-specific features demonstrations

Note: Test files are not included in the public release. For testing, see the development repository.


🌐 Supported Languages

  • English (en): Default, comprehensive translations
  • Japanese (ja): Complete Japanese translations

You can add support for any language by providing translation dictionaries:

custom_translations = {
    "fr": {
        "ok": "OK",
        "cancel": "Annuler",
        "yes": "Oui",
        "no": "Non",
        "Error": "Erreur",
        "Warning": "Avertissement"
    }
}

πŸ“ License

This project is licensed under the MIT License. See the LICENSE file for details.


πŸ‘¨β€πŸ’» Author

mashu3

Authors

About

A multilingual GUI extension library for Tkinter with enhanced dialogs, calendar widgets, and Windows-specific features.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages