feat(theme): improve Windows UI defaults and add theme guide

- Change Button use_ttk_buttons default behavior to True on Windows when omitted

- Keep explicit use_ttk_buttons=True/False behavior unchanged

- Keep Windows default theme as vista and document theme usage/customization

- Add docs/theme.md and link it from docs/README.md

- Add tests/theme/ttk_button.py example and lint docstring fix

Author: kujirahand

TkEasyGUI/utils.py

@@ -259,8 +259,6 @@ def set_default_theme() -> None:
         set_theme("aqua")
     elif is_win():
         # ('winnative', 'clam', 'alt', 'default', 'classic', 'vista', 'xpnative')
-        # set_theme("winnative")
-        # set_theme("default")
         set_theme("vista")
     else:
         set_theme("clam")

TkEasyGUI/widgets.py

@@ -2371,14 +2371,15 @@ def __init__(
         expand_y: bool = False,
         pad: Optional[PadType] = None,
         # other
-        use_ttk_buttons: bool = False,
+        use_ttk_buttons: Optional[bool] = None,
         metadata: Optional[dict[str, Any]] = None,
         **kw,
     ) -> None:
         """Create a Button element."""
         key = button_text if (key is None) or (key == "") else key
         super().__init__("Button", "TButton", key, False, metadata, **kw)
-        self.use_ttk = use_ttk_buttons  # can select ttk or tk button
+        # On Windows, ttk buttons look more modern by default.
+        self.use_ttk = utils.is_win() if use_ttk_buttons is None else use_ttk_buttons
         self.disabled = False
         if disabled is not None:
             self.props["disabled"] = self.disabled = disabled

TkEasyGUI/widgets_window.py

@@ -52,6 +52,8 @@ def _create_root(self) -> tk.Tk:
             self._root.eval("tk::PlaceWindow . center")
             self._root.withdraw()
         if self._theme_name == "":
+            # windows: winnative, clam, alt, default, classic, vista, xpnative
+            # macOS: aqua, clam, alt, default, classic
             if _is_mac():
                 self.set_theme("aqua")
             elif _is_win():

docs/README.md

@@ -68,6 +68,7 @@ Here is a list of elements:
 ### TkEasyGUI Original features
 
 - [Custom Events](https://github.com/kujirahand/tkeasygui-python/blob/main/docs/custom_events.md)
+- [Theme Guide](https://github.com/kujirahand/tkeasygui-python/blob/main/docs/theme.md)
 
 ### Package developper
 

docs/theme.md

@@ -0,0 +1,107 @@
+# TkEasyGUI Theme Guide
+
+This document explains how to use themes and how to change theme-related defaults in TkEasyGUI.
+
+## Overview
+
+TkEasyGUI uses `ttk` themes for modern widget rendering.
+You can switch themes at runtime using `set_theme()` or `theme()`.
+
+Default theme by platform:
+
+- macOS: `aqua`
+- Windows: `vista`
+- Linux/others: `clam`
+
+## Basic theme usage
+
+### Change theme with `set_theme`
+
+```python
+import TkEasyGUI as eg
+
+eg.set_theme("clam")
+window = eg.Window("Theme sample", [[eg.Button("OK", use_ttk_buttons=True)]])
+window.read()
+window.close()
+```
+
+### Alias: `theme`
+
+`theme()` is an alias of `set_theme()`.
+
+```python
+import TkEasyGUI as eg
+
+eg.theme("default")
+```
+
+## List available themes
+
+Use `get_tnemes()` to inspect themes available in your current Tk runtime.
+
+```python
+import TkEasyGUI as eg
+
+print(eg.get_tnemes())
+```
+
+Note:
+- Function name is `get_tnemes()` in current API.
+
+## Change button style behavior
+
+`Button` can render with `ttk.Button` (modern) or `tk.Button` (classic).
+
+- `use_ttk_buttons=True`: use `ttk.Button`
+- `use_ttk_buttons=False`: use `tk.Button`
+- `use_ttk_buttons=None` (default): Windows uses `ttk`, other OS keep previous default behavior
+
+```python
+import TkEasyGUI as eg
+
+layout = [
+    [eg.Button("Modern", use_ttk_buttons=True)],
+    [eg.Button("Classic", use_ttk_buttons=False)],
+]
+window = eg.Window("Buttons", layout)
+window.read()
+window.close()
+```
+
+## How to customize defaults
+
+### Global theme default
+
+If you want to change the default theme for your app, call `set_theme()` before creating windows.
+
+```python
+import TkEasyGUI as eg
+
+eg.set_theme("winnative")
+```
+
+### Revert to old Windows look
+
+If you want behavior close to older Windows appearance:
+
+```python
+import TkEasyGUI as eg
+
+eg.set_theme("vista")
+layout = [[eg.Button("OK", use_ttk_buttons=False)]]
+window = eg.Window("Legacy look", layout)
+window.read()
+window.close()
+```
+
+## Recommended test scripts
+
+After changing theme defaults, validate with:
+
+```bash
+python tests/file_viewer.py
+python tests/theme/ttk_button.py
+python tests/ui_test.py
+python tests/many_buttons.py
+```

tests/theme/ttk_button.py

@@ -0,0 +1,18 @@
+"""Compare ttk and classic button rendering."""
+
+import TkEasyGUI as eg
+
+layout = [
+    [eg.Text("This is a modern button using ttk styles.")],
+    [eg.Button("Modern", use_ttk_buttons=True)],
+    [eg.HSeparator()],
+    [eg.Text("This is a classic button using Tkinter styles.")],
+    [eg.Button("Classic", use_ttk_buttons=False)],
+]
+window = eg.Window("Buttons", layout)
+for event, values in window.event_iter():
+    if event == "Modern":
+        eg.popup("You clicked the modern button!")
+    if event == "Classic":
+        eg.popup("You clicked the classic button!")
+window.close()