# 🏗️ CTkBuilder: A JSON-Driven CustomTkinter GUI Builder
## 📜 Description
CTkBuilder is a customizable framework built on top of CustomTkinter, allowing users to define widgets and layouts using JSON files. The builder automates the process of window configuration, widget creation, layout management, and applying specific settings for different operating systems like Windows.
## ⭐ Features
- Widget layout and properties are defined using JSON.
- Automatically binds commands and event handlers to widgets.
- Supports multiple widget types like buttons, labels, frames, sliders, etc.
- Flexible layout with both grid and absolute positioning.
- Easy to extend with new widgets or custom commands.
- Update theme for all widgets dynamically.
- Themes profiles can be defined using JSON
## 🛠 Installation
- Clone the repository:
```bash
git clone https://github.com/mst4cks/CTkBuilder.git
cd ctkbuilder
pip install -r requirements.txt
```
- Install with pip:
``` bash
pip install ctkbuilder
```
## 📦 Usage
- Widgets json configuration example (for example `widgets.json`):
```json
{
"widgets": [
{
"type": "button",
"name": "submit_button",
"text": "Submit",
"row": 0,
"column": 1,
"command": "submit_form"
},
{
"type": "label",
"name": "welcome_label",
"text": "Welcome to CTkBuilder",
"row": 0,
"column": 0
}
]
}
```
- Main App json configuration example :
```json
{
"geometry": "800x600",
"title": "My Application",
"resize_width": true,
"resize_height": true,
"opacity": 0.8
}
```
- Themes json configuration example:
```json
{
"themes": [
{
"name": "light_theme",
"bg_color": "#ffffff",
"fg_color": "#000000",
"hover_color": "#cccccc",
"text_color": "#333333"
},
{
"name": "dark_theme",
"bg_color": "#333333",
"fg_color": "#ffffff",
"hover_color": "#555555",
"text_color": "#cccccc"
},
{
"name": "blue_theme",
"bg_color": "#e0f7fa",
"fg_color": "#00796b",
"hover_color": "#80deea",
"text_color": "#004d40"
}
]
}
```
- App example:
```python
from ctkbuilder import CTkBuilder
import customtkinter as ctk
def test_command():
print("Button pressed!")
app = ctk.CTk()
builder = CTkBuilder(app, 'config.json')
builder.build_widgets()
builder.apply_theme('dark', 'themes.json') # set a custom global theme
app.mainloop()
```
## 🪟 Advanced Configuration for Windows
- **minimize_status**: Control the minimize button's behavior.
- **maximize_status**: Control the maximize button's behavior.
- **opacity**: Set window opacity (0 to 1).
- **bar_color**: Set the color of the title bar.
- **border_color**: Set the color of the window border.
- **title_style**: Customize the title text style.
## 🛠️ Key Methods for Application Development
The following methods are essential for creating and customizing applications using the `CTkBuilder` class:
1. **`build_widgets(self)`**
This method creates all the widgets defined in the JSON file and adds them to the graphical interface. It is fundamental for building the UI.
2. **`create_widget(self, widget_info)`**
Creates an individual widget based on the details provided in the JSON (widget type, positioning, and configuration options). It is used by `build_widgets` to handle each widget.
3. **`toggle_widget_state(self, widget_name, state)`**
Changes the state of widgets (e.g., enabled or disabled). This is useful for dynamically controlling the interface based on user interaction or application state.
4. **`preconfig_app(self, json_config)`**
Pre-configures the application settings, such as window size, title, and resizing options, using a JSON file. This is useful for initial window setup.
5. **`apply_theme(self, theme_name, theme_file)`**
Applies a custom theme to the interface. This allows dynamic changes to the UI styles (colors, text styles, etc.) from a JSON file that defines the themes.
6. **`save_state(self)`**
Saves the current states of the widgets, such as text in `Entry` fields or the state of `CheckBox` and `Switch` widgets. Useful for applications that need to preserve user input between sessions.
7. **`load_state(self)`**
Loads the saved states of widgets, allowing the restoration of the interface to a previously saved state. This can restore form inputs, selections, and other widget data.
## 🐛 Issues
If you encounter any problems while using the project, please report them on the [Issues](https://github.com/mst4cks/CTkBuilder/issues) page of this repository.
## 💬 Contributions
If you'd like to contribute to the project, please fork the repository, create a feature branch, and submit a pull request with your improvements.
## 🌀 Other
The project is still under development!
## ⚖️ License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/mst4cks/CTkBuilder",
"name": "ctkbuilder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": "mst4ck",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/94/06/4c5b380c6e5e835c5a724893427572dfb3c7a000883b553bda3885290a52/ctkbuilder-1.0.0.tar.gz",
"platform": null,
"description": "# \ud83c\udfd7\ufe0f CTkBuilder: A JSON-Driven CustomTkinter GUI Builder\r\n\r\n## \ud83d\udcdc Description\r\nCTkBuilder is a customizable framework built on top of CustomTkinter, allowing users to define widgets and layouts using JSON files. The builder automates the process of window configuration, widget creation, layout management, and applying specific settings for different operating systems like Windows.\r\n\r\n## \u2b50 Features\r\n- Widget layout and properties are defined using JSON.\r\n- Automatically binds commands and event handlers to widgets.\r\n- Supports multiple widget types like buttons, labels, frames, sliders, etc.\r\n- Flexible layout with both grid and absolute positioning.\r\n- Easy to extend with new widgets or custom commands.\r\n- Update theme for all widgets dynamically.\r\n- Themes profiles can be defined using JSON\r\n\r\n## \ud83d\udee0 Installation\r\n- Clone the repository:\r\n```bash\r\n git clone https://github.com/mst4cks/CTkBuilder.git\r\n cd ctkbuilder\r\n pip install -r requirements.txt\r\n ```\r\n\r\n- Install with pip:\r\n``` bash\r\n pip install ctkbuilder\r\n ``` \r\n\r\n## \ud83d\udce6 Usage\r\n\r\n- Widgets json configuration example (for example `widgets.json`):\r\n```json\r\n {\r\n \"widgets\": [\r\n {\r\n \"type\": \"button\",\r\n \"name\": \"submit_button\",\r\n \"text\": \"Submit\",\r\n \"row\": 0,\r\n \"column\": 1,\r\n \"command\": \"submit_form\"\r\n },\r\n {\r\n \"type\": \"label\",\r\n \"name\": \"welcome_label\",\r\n \"text\": \"Welcome to CTkBuilder\",\r\n \"row\": 0,\r\n \"column\": 0\r\n }\r\n ]\r\n }\r\n ```\r\n\r\n- Main App json configuration example :\r\n```json\r\n {\r\n \"geometry\": \"800x600\",\r\n \"title\": \"My Application\",\r\n \"resize_width\": true,\r\n \"resize_height\": true,\r\n \"opacity\": 0.8\r\n }\r\n```\r\n\r\n- Themes json configuration example:\r\n```json\r\n {\r\n \"themes\": [\r\n {\r\n \"name\": \"light_theme\",\r\n \"bg_color\": \"#ffffff\",\r\n \"fg_color\": \"#000000\",\r\n \"hover_color\": \"#cccccc\",\r\n \"text_color\": \"#333333\"\r\n },\r\n {\r\n \"name\": \"dark_theme\",\r\n \"bg_color\": \"#333333\",\r\n \"fg_color\": \"#ffffff\",\r\n \"hover_color\": \"#555555\",\r\n \"text_color\": \"#cccccc\"\r\n },\r\n {\r\n \"name\": \"blue_theme\",\r\n \"bg_color\": \"#e0f7fa\",\r\n \"fg_color\": \"#00796b\",\r\n \"hover_color\": \"#80deea\",\r\n \"text_color\": \"#004d40\"\r\n }\r\n ]\r\n}\r\n \r\n```\r\n- App example:\r\n ```python\r\n from ctkbuilder import CTkBuilder\r\n import customtkinter as ctk\r\n\r\n def test_command():\r\n print(\"Button pressed!\")\r\n\r\n app = ctk.CTk()\r\n builder = CTkBuilder(app, 'config.json')\r\n builder.build_widgets()\r\n builder.apply_theme('dark', 'themes.json') # set a custom global theme\r\n app.mainloop()\r\n ```\r\n\r\n## \ud83e\ude9f Advanced Configuration for Windows\r\n\r\n- **minimize_status**: Control the minimize button's behavior.\r\n- **maximize_status**: Control the maximize button's behavior.\r\n- **opacity**: Set window opacity (0 to 1).\r\n- **bar_color**: Set the color of the title bar.\r\n- **border_color**: Set the color of the window border.\r\n- **title_style**: Customize the title text style.\r\n\r\n\r\n## \ud83d\udee0\ufe0f Key Methods for Application Development\r\n\r\nThe following methods are essential for creating and customizing applications using the `CTkBuilder` class:\r\n\r\n1. **`build_widgets(self)`** \r\n This method creates all the widgets defined in the JSON file and adds them to the graphical interface. It is fundamental for building the UI.\r\n\r\n2. **`create_widget(self, widget_info)`** \r\n Creates an individual widget based on the details provided in the JSON (widget type, positioning, and configuration options). It is used by `build_widgets` to handle each widget.\r\n\r\n3. **`toggle_widget_state(self, widget_name, state)`** \r\n Changes the state of widgets (e.g., enabled or disabled). This is useful for dynamically controlling the interface based on user interaction or application state.\r\n\r\n4. **`preconfig_app(self, json_config)`** \r\n Pre-configures the application settings, such as window size, title, and resizing options, using a JSON file. This is useful for initial window setup.\r\n\r\n5. **`apply_theme(self, theme_name, theme_file)`** \r\n Applies a custom theme to the interface. This allows dynamic changes to the UI styles (colors, text styles, etc.) from a JSON file that defines the themes.\r\n\r\n6. **`save_state(self)`** \r\n Saves the current states of the widgets, such as text in `Entry` fields or the state of `CheckBox` and `Switch` widgets. Useful for applications that need to preserve user input between sessions.\r\n\r\n7. **`load_state(self)`** \r\n Loads the saved states of widgets, allowing the restoration of the interface to a previously saved state. This can restore form inputs, selections, and other widget data.\r\n\r\n\r\n## \ud83d\udc1b Issues\r\n\r\nIf you encounter any problems while using the project, please report them on the [Issues](https://github.com/mst4cks/CTkBuilder/issues) page of this repository.\r\n\r\n\r\n## \ud83d\udcac Contributions\r\n\r\nIf you'd like to contribute to the project, please fork the repository, create a feature branch, and submit a pull request with your improvements.\r\n\r\n## \ud83c\udf00 Other\r\nThe project is still under development!\r\n\r\n## \u2696\ufe0f License\r\n\r\nThis project is licensed under the MIT License.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A JSON-driven customtkinter GUI builder",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/mst4cks/CTkBuilder"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a9daf4968e9fdb1393ff4ed26ec856374f1cdc0b7419f357cd8f457bfd1a366",
"md5": "fd3b6e538e5fca89e50a60f3772db2b9",
"sha256": "7fc5f9e015b5dd8d0f6e94bbae8c2224f6383cca7c7d409c68a05da1571a691a"
},
"downloads": -1,
"filename": "ctkbuilder-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd3b6e538e5fca89e50a60f3772db2b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 7237,
"upload_time": "2024-10-07T23:42:04",
"upload_time_iso_8601": "2024-10-07T23:42:04.792158Z",
"url": "https://files.pythonhosted.org/packages/9a/9d/af4968e9fdb1393ff4ed26ec856374f1cdc0b7419f357cd8f457bfd1a366/ctkbuilder-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94064c5b380c6e5e835c5a724893427572dfb3c7a000883b553bda3885290a52",
"md5": "11404f9f0fcdf002524941c6c8adc241",
"sha256": "afd4101d5f6f2fa32bc7e7ede6d1b07d347ab68b63c67d7506fab300fecab0e8"
},
"downloads": -1,
"filename": "ctkbuilder-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "11404f9f0fcdf002524941c6c8adc241",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 8990,
"upload_time": "2024-10-07T23:42:06",
"upload_time_iso_8601": "2024-10-07T23:42:06.264880Z",
"url": "https://files.pythonhosted.org/packages/94/06/4c5b380c6e5e835c5a724893427572dfb3c7a000883b553bda3885290a52/ctkbuilder-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-07 23:42:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mst4cks",
"github_project": "CTkBuilder",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "customtkinter",
"specs": []
},
{
"name": "hPyT",
"specs": []
}
],
"lcname": "ctkbuilder"
}
JSON
