flexgui 1.0.0__tar.gz

flexgui-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlexGUI Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flexgui-1.0.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: flexgui
+Version: 1.0.0
+Summary: Thư viện GUI Python kéo-thả-thiết-kế trên tkinter — FlexGUI Studio tích hợp (design mode + mini VS Code cho trigger)
+Keywords: gui,tkinter,designer,drag-and-drop,visual-designer,no-code,vietnamese,flexgui
+Author: FlexGUI Team
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Natural Language :: Vietnamese
+License-File: LICENSE
+Requires-Dist: pyinstaller>=6.0 ; extra == "build"
+Project-URL: Documentation, https://github.com/your-name/flexgui#readme
+Project-URL: Homepage, https://github.com/your-name/flexgui
+Provides-Extra: build
+Import-Name: flexgui
+
+# FlexGUI
+
+**Thư viện GUI Python kéo-thả-thiết-kế trên tkinter** — viết code siêu gọn,
+thiết kế giao diện bằng chuột trong **FlexGUI Studio** (nền tối hiện đại),
+code trigger sửa được **ngay trong Studio hoặc VS Code**, đóng gói `.exe`
+một cú click.
+
+```bash
+pip install flexgui
+```
+
+---
+
+## 1. Viết code thuần (60 giây)
+
+```python
+import flexgui
+from flexgui import App, Label, Button, Input, Checkbox, Text
+
+app = App("Ứng dụng của tôi", 860, 560)
+
+Label("Xin chào!", 40, 30)            # label[1]
+Button("Bấm tôi", 40, 80)             # button[2]
+Input(40, 130, width=26)              # input[3]
+Checkbox("Đồng ý", 40, 180)           # checkbox[4]
+Text(40, 230, width=42, height=7)     # text[5]
+
+app.run()
+```
+
+Mọi widget định vị **tuyệt đối bằng `place(x, y)`** — đặt đâu nằm đó,
+chồng lớp tự do.
+
+## 2. Chế độ thiết kế — FlexGUI Studio
+
+Thêm **một dòng** vào file là mở được trình thiết kế:
+
+```python
+import flexgui
+
+flexgui.setup()      # hoặc:  from flexgui import design; design.mode = True
+```
+
+Chạy `python myapp.py` → **Studio tự mở giao diện trống** (hoặc nạp
+thiết kế đã lưu). Tính năng:
+
+- Kéo thả mượt (canvas item — không tàn ảnh), **snap lưới 10px** (bật/tắt)
+- **Resize 8 núm** quanh thành phần đang chọn
+- **Multi-select**: Ctrl/Shift + click, quét vùng chuột, kéo cả cụm
+- Đổi z-order (menu chuột phải), nhân bản `Ctrl+D`, undo/redo `Ctrl+Z/Y`
+- Bảng thuộc tính bên phải: chữ, tọa độ, kích thước **pixel WYSIWYG**,
+  màu chữ/nền, cỡ chữ, ẩn khi chạy, khoá...
+- **Xem trước F5** — chạy thử app thật + trigger thật ngay tại chỗ
+- **Build .exe** bằng PyInstaller (nút 📦 — tự cài nếu thiếu)
+- **Xuất .py** — 1 file tự chạy nhúng toàn bộ thiết kế + trigger
+
+`Ctrl+S` lưu 2 file cạnh `myapp.py`:
+
+| File | Nội dung |
+|---|---|
+| `myapp.flexgui.json` | bố cục + thuộc tính mọi thành phần |
+| `myapp.triggers.py` | **code trigger — file dùng chung** |
+
+## 3. Trigger — sửa ở Studio HOẶC VS Code đều được
+
+`myapp.triggers.py` là file Python thật: mở bằng **mini VS Code** trong
+Studio (nút ⌨ Triggers) **hoặc** VS Code ngoài — cả hai sửa cùng một file.
+
+```python
+# myapp.triggers.py — label/button/... đã có sẵn, không cần import
+
+def on_start():                       # chạy 1 lần khi app mở
+    label[1].set_text("Xin chào!")
+
+def on_button_2_click():              # bấm button[2]
+    import random                     # Python thật — import gì cũng được
+    label[1].set_text(f"Số: {random.randint(1, 99)}")
+
+def on_checkbox_4_toggle():           # tick/bỏ tick checkbox[4]
+    text[5].visible = checkbox[4].checked
+
+def on_input_3_enter():               # Enter trong input[3]
+    alert("Bạn vừa gõ: " + input[3].text)
+
+def on_text_5_change():               # gõ chữ trong text[5]
+    pass
+```
+
+Quy ước tên hàm: `on_<loại>_<id>_<sự kiện>`
+(`click` / `toggle` / `enter` / `change`). Studio tự sinh sườn hàm khi lưu.
+
+Kiểu **decorator** mạnh hơn (cũng viết trong file trigger):
+
+```python
+@on_click(button[2])
+def xu_ly(): ...
+
+@on_change(input[3])                  # gõ bất kỳ chữ nào
+def khi_go(): ...
+
+@when(lambda: checkbox[4].checked and input[3].text == "admin")
+def khi_du(): ...                     # điều kiện SAI → ĐÚNG mới chạy
+
+@every(1000)                          # lặp mỗi giây
+def dong_ho(): ...
+
+@on_init                              # = on_start
+def khoi_dong(): ...
+```
+
+## 4. Chạy thật
+
+Đổi 1 dòng trong `myapp.py`:
+
+```python
+import flexgui
+
+flexgui.run(__file__)    # nạp myapp.flexgui.json + myapp.triggers.py
+```
+
+Hoặc dùng cờ dòng lệnh quen thuộc: `python myapp.py --design`.
+
+## 5. Thuộc tính & lệnh điều khiển widget
+
+```python
+from flexgui import label, button, input, checkbox, text
+
+label[1].text = "Số đếm: 5"       # đọc/ghi trực tiếp
+label[1].set_text("...")          # tương đương
+label[1].get_text()
+label[1].x = 200                  # tọa độ pixel (đọc/ghi)
+label[1].color = "red"            # màu chữ
+label[1].bg = "#FFF3B0"           # màu nền
+label[1].font_size = 14
+label[1].visible = False          # tàng hình / hiện lại
+label[1].enabled = False          # khoá / mở
+label[1].place(120, 80)           # đặt lại vị trí tuyệt đối
+label[1].move(10, 0)              # dịch tương đối
+label[1].resize(220, 30)          # cỡ pixel WYSIWYG
+label[1].refresh()                # vẽ lại mọi thuộc tính đã lưu
+label[1].show() / .hide() / .focus()
+
+checkbox[4].checked = True        # (chỉ Checkbox)
+checkbox[4].toggle()
+button[2].command = ham_xu_ly     # gán lệnh bằng code
+
+# Lệnh app — gọi thẳng trong trigger
+refresh() · set_title("...") · set_size(1024, 640) · set_bg("black")
+alert("...") · confirm("...?") → True/False · prompt("Tên?") → str/None
+close_app()
+```
+
+Widget bị xóa thì `input[3]` trả **widget rỗng an toàn** — code cũ không
+bao giờ văng lỗi. ID **tái sử dụng**: xóa `input[3]` rồi thêm widget mới
+thì widget mới nhận lại đúng ID `[3]`.
+
+---
+
+## Đóng gói & chia sẻ
+
+- **Build .exe** (nút 📦 trong Studio): PyInstaller tự động — file nằm
+  trong `flexgui_build/dist/`.
+- **Xuất .py** (nút ▲): 1 file duy nhất nhúng thiết kế + trigger — chạy
+  bằng `python ten_file.py` (cần `pip install flexgui`).
+
+## Cấu trúc package
+
+```
+flexgui/
+├── __init__.py    # API công khai: App, 5 widget, run/setup/design...
+├── mode.py        # design.mode = True
+├── registry.py    # label[1] / button[2] ... + widget rỗng an toàn
+├── widgets.py     # Label/Button/Input/Checkbox/Text (pixel WYSIWYG)
+├── triggers.py    # engine trigger + decorator + lệnh app
+├── app.py         # cửa sổ App + ID tái sử dụng
+├── runtime.py     # run() / setup() / run_embedded()
+├── editor.py      # mini VS Code (tô màu Python, IME tiếng Việt an toàn)
+├── designer.py    # FlexGUI Studio (canvas Figma-style)
+└── builder.py     # xuất file đơn + PyInstaller
+```
+
+## Yêu cầu
+
+- Python 3.8+ (chỉ dùng thư viện chuẩn — **không cần cài thêm gì**)
+- Build `.exe` cần `pip install pyinstaller` (Studio tự cài nếu thiếu)
+
+## Đăng package lên PyPI (cho người phát hành)
+
+```bash
+pip install --upgrade build twine
+
+# 1. build sdist + wheel (ra thư mục dist/)
+python -m build
+
+# 2. đăng (cần tài khoản PyPI + API token tại pypi.org)
+twine upload dist/*
+```
+
+Sau đó mọi người cài chỉ với `pip install flexgui`.
+*Lưu ý: nếu tên `flexgui` đã bị ai chiếm trên PyPI, đổi `name` trong
+`pyproject.toml` (ví dụ `flexgui-vn`) rồi build lại.*
+
+## License
+
+MIT
+

flexgui-1.0.0/README.md

@@ -0,0 +1,205 @@
+# FlexGUI
+
+**Thư viện GUI Python kéo-thả-thiết-kế trên tkinter** — viết code siêu gọn,
+thiết kế giao diện bằng chuột trong **FlexGUI Studio** (nền tối hiện đại),
+code trigger sửa được **ngay trong Studio hoặc VS Code**, đóng gói `.exe`
+một cú click.
+
+```bash
+pip install flexgui
+```
+
+---
+
+## 1. Viết code thuần (60 giây)
+
+```python
+import flexgui
+from flexgui import App, Label, Button, Input, Checkbox, Text
+
+app = App("Ứng dụng của tôi", 860, 560)
+
+Label("Xin chào!", 40, 30)            # label[1]
+Button("Bấm tôi", 40, 80)             # button[2]
+Input(40, 130, width=26)              # input[3]
+Checkbox("Đồng ý", 40, 180)           # checkbox[4]
+Text(40, 230, width=42, height=7)     # text[5]
+
+app.run()
+```
+
+Mọi widget định vị **tuyệt đối bằng `place(x, y)`** — đặt đâu nằm đó,
+chồng lớp tự do.
+
+## 2. Chế độ thiết kế — FlexGUI Studio
+
+Thêm **một dòng** vào file là mở được trình thiết kế:
+
+```python
+import flexgui
+
+flexgui.setup()      # hoặc:  from flexgui import design; design.mode = True
+```
+
+Chạy `python myapp.py` → **Studio tự mở giao diện trống** (hoặc nạp
+thiết kế đã lưu). Tính năng:
+
+- Kéo thả mượt (canvas item — không tàn ảnh), **snap lưới 10px** (bật/tắt)
+- **Resize 8 núm** quanh thành phần đang chọn
+- **Multi-select**: Ctrl/Shift + click, quét vùng chuột, kéo cả cụm
+- Đổi z-order (menu chuột phải), nhân bản `Ctrl+D`, undo/redo `Ctrl+Z/Y`
+- Bảng thuộc tính bên phải: chữ, tọa độ, kích thước **pixel WYSIWYG**,
+  màu chữ/nền, cỡ chữ, ẩn khi chạy, khoá...
+- **Xem trước F5** — chạy thử app thật + trigger thật ngay tại chỗ
+- **Build .exe** bằng PyInstaller (nút 📦 — tự cài nếu thiếu)
+- **Xuất .py** — 1 file tự chạy nhúng toàn bộ thiết kế + trigger
+
+`Ctrl+S` lưu 2 file cạnh `myapp.py`:
+
+| File | Nội dung |
+|---|---|
+| `myapp.flexgui.json` | bố cục + thuộc tính mọi thành phần |
+| `myapp.triggers.py` | **code trigger — file dùng chung** |
+
+## 3. Trigger — sửa ở Studio HOẶC VS Code đều được
+
+`myapp.triggers.py` là file Python thật: mở bằng **mini VS Code** trong
+Studio (nút ⌨ Triggers) **hoặc** VS Code ngoài — cả hai sửa cùng một file.
+
+```python
+# myapp.triggers.py — label/button/... đã có sẵn, không cần import
+
+def on_start():                       # chạy 1 lần khi app mở
+    label[1].set_text("Xin chào!")
+
+def on_button_2_click():              # bấm button[2]
+    import random                     # Python thật — import gì cũng được
+    label[1].set_text(f"Số: {random.randint(1, 99)}")
+
+def on_checkbox_4_toggle():           # tick/bỏ tick checkbox[4]
+    text[5].visible = checkbox[4].checked
+
+def on_input_3_enter():               # Enter trong input[3]
+    alert("Bạn vừa gõ: " + input[3].text)
+
+def on_text_5_change():               # gõ chữ trong text[5]
+    pass
+```
+
+Quy ước tên hàm: `on_<loại>_<id>_<sự kiện>`
+(`click` / `toggle` / `enter` / `change`). Studio tự sinh sườn hàm khi lưu.
+
+Kiểu **decorator** mạnh hơn (cũng viết trong file trigger):
+
+```python
+@on_click(button[2])
+def xu_ly(): ...
+
+@on_change(input[3])                  # gõ bất kỳ chữ nào
+def khi_go(): ...
+
+@when(lambda: checkbox[4].checked and input[3].text == "admin")
+def khi_du(): ...                     # điều kiện SAI → ĐÚNG mới chạy
+
+@every(1000)                          # lặp mỗi giây
+def dong_ho(): ...
+
+@on_init                              # = on_start
+def khoi_dong(): ...
+```
+
+## 4. Chạy thật
+
+Đổi 1 dòng trong `myapp.py`:
+
+```python
+import flexgui
+
+flexgui.run(__file__)    # nạp myapp.flexgui.json + myapp.triggers.py
+```
+
+Hoặc dùng cờ dòng lệnh quen thuộc: `python myapp.py --design`.
+
+## 5. Thuộc tính & lệnh điều khiển widget
+
+```python
+from flexgui import label, button, input, checkbox, text
+
+label[1].text = "Số đếm: 5"       # đọc/ghi trực tiếp
+label[1].set_text("...")          # tương đương
+label[1].get_text()
+label[1].x = 200                  # tọa độ pixel (đọc/ghi)
+label[1].color = "red"            # màu chữ
+label[1].bg = "#FFF3B0"           # màu nền
+label[1].font_size = 14
+label[1].visible = False          # tàng hình / hiện lại
+label[1].enabled = False          # khoá / mở
+label[1].place(120, 80)           # đặt lại vị trí tuyệt đối
+label[1].move(10, 0)              # dịch tương đối
+label[1].resize(220, 30)          # cỡ pixel WYSIWYG
+label[1].refresh()                # vẽ lại mọi thuộc tính đã lưu
+label[1].show() / .hide() / .focus()
+
+checkbox[4].checked = True        # (chỉ Checkbox)
+checkbox[4].toggle()
+button[2].command = ham_xu_ly     # gán lệnh bằng code
+
+# Lệnh app — gọi thẳng trong trigger
+refresh() · set_title("...") · set_size(1024, 640) · set_bg("black")
+alert("...") · confirm("...?") → True/False · prompt("Tên?") → str/None
+close_app()
+```
+
+Widget bị xóa thì `input[3]` trả **widget rỗng an toàn** — code cũ không
+bao giờ văng lỗi. ID **tái sử dụng**: xóa `input[3]` rồi thêm widget mới
+thì widget mới nhận lại đúng ID `[3]`.
+
+---
+
+## Đóng gói & chia sẻ
+
+- **Build .exe** (nút 📦 trong Studio): PyInstaller tự động — file nằm
+  trong `flexgui_build/dist/`.
+- **Xuất .py** (nút ▲): 1 file duy nhất nhúng thiết kế + trigger — chạy
+  bằng `python ten_file.py` (cần `pip install flexgui`).
+
+## Cấu trúc package
+
+```
+flexgui/
+├── __init__.py    # API công khai: App, 5 widget, run/setup/design...
+├── mode.py        # design.mode = True
+├── registry.py    # label[1] / button[2] ... + widget rỗng an toàn
+├── widgets.py     # Label/Button/Input/Checkbox/Text (pixel WYSIWYG)
+├── triggers.py    # engine trigger + decorator + lệnh app
+├── app.py         # cửa sổ App + ID tái sử dụng
+├── runtime.py     # run() / setup() / run_embedded()
+├── editor.py      # mini VS Code (tô màu Python, IME tiếng Việt an toàn)
+├── designer.py    # FlexGUI Studio (canvas Figma-style)
+└── builder.py     # xuất file đơn + PyInstaller
+```
+
+## Yêu cầu
+
+- Python 3.8+ (chỉ dùng thư viện chuẩn — **không cần cài thêm gì**)
+- Build `.exe` cần `pip install pyinstaller` (Studio tự cài nếu thiếu)
+
+## Đăng package lên PyPI (cho người phát hành)
+
+```bash
+pip install --upgrade build twine
+
+# 1. build sdist + wheel (ra thư mục dist/)
+python -m build
+
+# 2. đăng (cần tài khoản PyPI + API token tại pypi.org)
+twine upload dist/*
+```
+
+Sau đó mọi người cài chỉ với `pip install flexgui`.
+*Lưu ý: nếu tên `flexgui` đã bị ai chiếm trên PyPI, đổi `name` trong
+`pyproject.toml` (ví dụ `flexgui-vn`) rồi build lại.*
+
+## License
+
+MIT

flexgui-1.0.0/flexgui/__init__.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""
+FlexGUI — thư viện GUI Python kéo-thả-thiết-kế trên nền tkinter.
+
+    pip install flexgui
+
+ĐỒNG GÓI 2 PHẦN TRONG 1 THƯ VIỆN:
+
+  (A) THƯ VIỆN RUNTIME — cú pháp gọn, định vị tuyệt đối bằng place(x, y):
+
+        import flexgui
+        from flexgui import App, Label, Button, Input, Checkbox, Text
+
+        app = App("Ứng dụng của tôi", 860, 560)
+        Label("Xin chào!", 40, 30)
+        Button("Bấm tôi", 40, 80)
+        Input(40, 130, width=26)
+        Checkbox("Đồng ý", 40, 180)
+        Text(40, 230, width=42, height=7)
+        app.run()
+
+  (B) CHẾ ĐỘ THIẾT KẾ (FlexGUI Studio) — mở bằng MỘT trong các cách:
+
+        import flexgui
+        flexgui.setup()               # cách 1 — mở Studio ngay
+
+        from flexgui import design    # cách 2 — tương đương
+        design.mode = True
+
+        python myapp.py --design      # cách 3 — cờ dòng lệnh
+
+      → Chạy file ở design mode: Studio tự tạo GIAO DIỆN TRỐNG (hoặc nạp
+        myapp.flexgui.json đã lưu). Kéo thả thành phần, chỉnh thuộc tính,
+        viết trigger bằng mini VS Code ngay trong Studio HOẶC mở file
+        myapp.triggers.py bằng VS Code thật — cả hai sửa CÙNG một file.
+
+      → Chạy thật: đổi setup() thành flexgui.run(__file__) rồi chạy lại.
+
+Truy cập widget theo ID (tự động, tái sử dụng ID khi xóa):
+        from flexgui import label, button, input, checkbox, text
+        label[1].set_text("Xin chào!")     # đọc/ghi thuộc tính trực tiếp
+
+Chi tiết: README.md đi kèm package.
+"""
+
+from .mode import design
+from .registry import label, button, input, checkbox, text
+from .triggers import (
+    on_click, on_change, on_enter, when, every, on_init,
+    refresh, set_title, set_size, set_bg, alert, confirm, prompt, close_app,
+)
+from .widgets import Label, Button, Input, Checkbox, Text
+from .app import App
+from .runtime import run, setup, run_embedded
+
+__version__ = "1.0.0"
+__author__ = "FlexGUI Team"
+
+__all__ = [
+    # cửa sổ & widget
+    "App", "Label", "Button", "Input", "Checkbox", "Text",
+    # vùng tên theo ID
+    "label", "button", "input", "checkbox", "text",
+    # chế độ thiết kế & chạy
+    "design", "setup", "run", "run_embedded",
+    # decorator trigger
+    "on_click", "on_change", "on_enter", "when", "every", "on_init",
+    # lệnh app
+    "refresh", "set_title", "set_size", "set_bg",
+    "alert", "confirm", "prompt", "close_app",
+]