CustomTkinter/Readme.md

119 lines
4.6 KiB
Markdown
Raw Normal View History

2022-11-28 00:28:48 +03:00
<p align="center">
2022-11-28 00:38:03 +03:00
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./documentation_images/CustomTkinter_logo_dark.png">
<img src="./documentation_images/CustomTkinter_logo_light.png">
</picture>
2022-11-28 00:34:28 +03:00
</p>
<div align="center">
2022-11-28 00:28:48 +03:00
2021-05-08 13:52:44 +03:00
![PyPI](https://img.shields.io/pypi/v/customtkinter)
![PyPI - Downloads](https://img.shields.io/pypi/dm/customtkinter?color=green&label=downloads)
![Downloads](https://static.pepy.tech/personalized-badge/customtkinter?period=total&units=international_system&left_color=grey&right_color=green&left_text=downloads)
2021-05-08 13:52:44 +03:00
![PyPI - License](https://img.shields.io/pypi/l/customtkinter)
2021-11-07 17:12:09 +03:00
![Total lines](https://img.shields.io/tokei/lines/github.com/tomschimansky/customtkinter?color=green&label=total%20lines)
2022-11-28 00:34:28 +03:00
</div>
2022-01-22 21:16:58 +03:00
2022-11-30 03:21:01 +03:00
---
2022-11-28 00:28:48 +03:00
2022-03-10 22:27:01 +03:00
CustomTkinter is a python UI-library based on Tkinter, which provides new, modern and
fully customizable widgets. They are created and used like normal Tkinter widgets and
can also be used in combination with normal Tkinter elements. The widgets
and the window colors either adapt to the system appearance or the manually set mode
2022-05-30 15:35:33 +03:00
('light', 'dark'), and all CustomTkinter widgets and windows support HighDPI scaling
(Windows, macOS). With CustomTkinter you'll get a consistent and modern look across all
2022-03-10 22:27:01 +03:00
desktop platforms (Windows, macOS, Linux).
2021-03-04 21:10:12 +03:00
2022-11-30 03:13:44 +03:00
![](documentation_images/complex_example_dark_Windows.png)
| _`complex_example.py` on Windows 11 with dark mode and 'blue' theme_
![](documentation_images/complex_example_light_macOS.png)
| _`complex_example.py` on macOS in light mode and standard 'blue' theme_
###
2021-05-08 13:35:32 +03:00
2022-03-10 22:27:01 +03:00
## Installation
Install the module with pip:
2021-05-08 13:35:32 +03:00
```
2021-08-25 18:33:44 +03:00
pip3 install customtkinter
2021-05-08 13:35:32 +03:00
```
2021-10-15 14:57:38 +03:00
**Update existing installation:** ```pip3 install customtkinter --upgrade```\
2022-03-10 22:27:01 +03:00
(update as often as possible because this library is under active development)
2021-10-15 14:57:38 +03:00
2022-03-10 22:27:01 +03:00
## Documentation
2022-03-08 01:00:50 +03:00
2022-09-15 17:18:56 +03:00
The **official** documentation can be found in the Wiki Tab here:
**--> [Documentation](https://github.com/TomSchimansky/CustomTkinter/wiki)**.
2021-05-08 13:35:32 +03:00
2022-03-10 22:27:01 +03:00
## Example Program
2021-05-08 13:35:32 +03:00
To test customtkinter you can try this simple example with only a single button:
2021-03-05 02:05:34 +03:00
```python
import tkinter
2022-03-10 22:27:01 +03:00
import customtkinter
customtkinter.set_appearance_mode("System") # Modes: system (default), light, dark
customtkinter.set_default_color_theme("blue") # Themes: blue (default), dark-blue, green
2021-03-05 02:32:17 +03:00
app = customtkinter.CTk() # create CTk window like you do with the Tk window
app.geometry("400x240")
2021-03-05 02:05:34 +03:00
def button_function():
print("button pressed")
2021-03-05 02:32:17 +03:00
# Use CTkButton instead of tkinter Button
button = customtkinter.CTkButton(master=app, text="CTkButton", command=button_function)
2021-03-05 02:05:34 +03:00
button.place(relx=0.5, rely=0.5, anchor=tkinter.CENTER)
app.mainloop()
2021-03-05 02:05:34 +03:00
```
2022-11-30 03:27:38 +03:00
which results in the following window on macOS:
2021-03-14 17:45:02 +03:00
2022-11-30 03:30:21 +03:00
<img src="documentation_images/single_button_macOS.png" width="400"/>
2021-03-14 17:45:02 +03:00
2022-03-10 22:27:01 +03:00
In the [examples folder](https://github.com/TomSchimansky/CustomTkinter/tree/master/examples), you
can find more example programs and in the [Documentation](https://github.com/TomSchimansky/CustomTkinter/wiki)
2022-11-30 03:27:38 +03:00
you can find further information on the appearance mode, scaling, themes and all widgets.
2021-03-05 22:27:34 +03:00
2022-03-10 22:27:01 +03:00
## More Examples and Showcase
2021-03-05 22:27:34 +03:00
2022-11-30 02:53:58 +03:00
### Appearance mode change and scaling change
2021-03-05 22:27:34 +03:00
2022-11-30 03:10:25 +03:00
CustomTkinter can adapt to the Windows 10/11 light or dark mode:
2022-11-30 02:53:58 +03:00
https://user-images.githubusercontent.com/66446067/204672968-6584f360-4c52-434f-9c16-25761341368b.mp4
2022-03-10 22:42:28 +03:00
2022-11-30 02:53:58 +03:00
| _`complex_example.py` on Windows 11 with system appearance mode change and standard 'blue' theme_
2022-03-10 22:42:28 +03:00
###
2022-11-30 02:53:58 +03:00
On macOS you either need python3.10 or higher or the anaconda python
version to get a dark window header (Tcl/Tk >= 8.6.9 required):
https://user-images.githubusercontent.com/66446067/204673854-b6cbcfda-d9a1-4425-92a3-5b57d7f2fd6b.mp4
2022-01-08 02:50:31 +03:00
2022-11-30 02:53:58 +03:00
| _`complex_example.py` on macOS with system appearance mode change, user-scaling change and standard 'blue' theme_
2022-03-10 22:37:54 +03:00
###
2021-11-11 01:18:04 +03:00
2022-03-10 22:27:01 +03:00
### Button with images
It's possible to put an image on a CTkButton. You just have to
2022-03-10 22:44:40 +03:00
pass a PhotoImage object to the CTkButton with the ``image`` argument.
If you want no text at all you have to set ``text=""`` or you specify
how to position the text and image at once with the ``compound`` option:
2021-03-08 20:17:36 +03:00
2022-12-01 01:09:42 +03:00
![](documentation_images/image_example_dark_Windows.png)
2022-12-01 01:12:37 +03:00
| _`image_example.py` on Windows 11_
2022-03-10 22:37:54 +03:00
###
2021-03-08 20:17:36 +03:00
2022-01-02 17:29:50 +03:00
### Integration of TkinterMapView widget
In the following example I used a TkinterMapView which integrates
well with a CustomTkinter program. It's a tile based map widget which displays
OpenStreetMap or other tile based maps:
2022-11-30 03:10:25 +03:00
https://user-images.githubusercontent.com/66446067/204675835-1584a8da-5acc-4993-b4a9-e70f06fa14b0.mp4
| _`examples/map_with_customtkinter.py` from TkinterMapView repository on Windows 11_
2021-03-05 23:05:53 +03:00
2022-12-01 02:00:20 +03:00
You can find the TkinterMapView library and example program here:
2022-01-02 17:29:50 +03:00
https://github.com/TomSchimansky/TkinterMapView