tkface 0.0.6

A comprehensive multilingual GUI extension library for Tkinter with enhanced message boxes, calendar widgets, theme system, and Windows-specific features

Tkface

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("Success", "Operation completed successfully!")

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

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

# Confirmation dialog
if tkface.messagebox.askyesno("Confirm", "Do you want to save?"):
    save_file()

Screenshots

Dialog Type	Windows	macOS
Warning
Error
Information
Question

Input Dialogs

import tkface

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

# Integer input with validation
age = tkface.simpledialog.askinteger("Age", "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)

Calendar Widget

Screenshots

Widget Type	Windows	macOS
DateEntry

Usage Examples

import tkinter as tk
import tkface

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

# Basic DateEntry
date_entry = tkface.DateEntry(root, year=2025, month=8)
date_entry.pack(padx=10, pady=10)

# Advanced DateEntry with features
date_entry = tkface.DateEntry(
    root,
    year=2025,
    month=8,
    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
)
date_entry.pack(padx=10, pady=10)

# Get selected date
selected_date = date_entry.get_date()
print(f"Selected date: {selected_date}")

root.mainloop()

Windows-Specific Features

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()
tkface.win.dpi(root)         # Enable DPI awareness (Windows only)
tkface.win.unround(root)     # Disable corner rounding (Windows 11 only)
tkface.win.bell("error")     # Play Windows system sound (Windows only)

# Windows-specific flat button styling
button = tkface.Button(root, text="Flat Button", command=callback)  # Flat styling on Windows
root.mainloop()

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
• 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_calendar.py - Calendar widget 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