tkface 0.0.7

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)

DatePicker Widgets

Screenshots

Widget Type	Windows	macOS
DateFrame

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.

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.pack(padx=10, pady=10)

# Get selected date
selected_date = date_entry.get_date()
print(f"Selected date: {selected_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

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