dokibox 1.0.0__tar.gz

dokibox-1.0.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: dokibox
+Version: 1.0.0
+Summary: A fan-made Python library for Doki Doki Literature Club!, providing DDLC-style character dialogs, choice menus, and typewriter effects. Only support Windows system.
+Author-email: windows99-hue <ninezkh@qq.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# dokibox
+
+A fan-made Python library for *Doki Doki Literature Club*, implementing various in-game prompt boxes using `tkinter`.
+
+> ### ⚠️ Credit & IP Guidelines
+> `dokibox` is a fan derivative work based on *Doki Doki Literature Club* (DDLC) and is not officially affiliated with Team Salvato. The original game can be downloaded [here](https://ddlc.moe/) or from the [Steam store page](https://store.steampowered.com/app/698780/Doki_Doki_Literature_Club/).
+>
+> Any user creating derivative works with this library **must** strictly follow the [official IP guidelines](https://teamsalvato.com/ip-guidelines).
+>
+> Special thanks to Joseph from Team Salvato for his support and responses via email!
+
+## Installation
+
+Install from PyPI:
+
+~~~bash
+pip install dokibox
+~~~
+
+## Import
+
+```python
+import dokibox
+```
+
+---
+
+### ynbox — Yes/No Dialog
+
+<img width="2560" height="1392" alt="image" src="https://github.com/user-attachments/assets/d40c9881-14bd-4876-877c-1d2008805c06" />
+
+```python
+dokibox.ynbox(msg="Delete?", tooltip=False) → bool
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | str | `""` | Message text |
+| `tooltip` | bool | `False` | Tooltip text |
+| `btn_texts` | tuple | None | Confirm button prompt. When set to None, `dokibox` will automatically detect the system language. To modify, please pass in a tuple, replacing "Yes" with the first parameter and "No" with the second parameter. English is used by default when the language is unknown. |
+
+Return value: clicking "Yes" returns `True`; clicking "No" or pressing Esc returns `False`.
+
+```python
+if dokibox.ynbox("Delete?"):
+    print("User clicked Yes")
+```
+
+---
+
+### msgbox — Message Box
+
+<img width="2560" height="1392" alt="image" src="https://github.com/user-attachments/assets/da5064d3-8d90-47ec-9b9e-20e87faf0fdc" />
+
+```python
+dokibox.msgbox(msg="Operation successful!", tooltip=False) → True
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | str | `""` | Message text |
+| `tooltip` | bool | `False` | Tooltip text |
+
+Single OK button. Closes on click, Enter, or Esc; returns `True`.
+
+```python
+dokibox.msgbox("Saved successfully!")
+```
+
+---
+
+### choicebox — Multiple Choice Dialog
+
+<img width="2560" height="1392" alt="image" src="https://github.com/user-attachments/assets/a33088b1-363b-48f5-8509-44a5d3ef5f4d" />
+
+```python
+dokibox.choicebox(msg="", choices=None, tooltip=False, force=None) → str | None
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | str | `""` | Prompt text; hidden when empty |
+| `choices` | list | `None` | List of choices |
+| `tooltip` | bool | `False` | Tooltip text |
+| `force` | int | `None` | Force-select an index (0-based); cursor moves to the center of that choice |
+
+Return value: the selected text content; Esc returns `None`.
+
+```python
+char = dokibox.choicebox("Choose a character", ["Sayori", "Yuri", "Natsuki"], force=1)
+print(char)  # "Yuri"
+```
+
+---
+
+### dialogbox — Bottom Dialog Box
+
+<img width="2560" height="1392" alt="image" src="https://github.com/user-attachments/assets/3817a140-66eb-496d-988d-7b728289a1ca" />
+
+```python
+dokibox.dialogbox(msg="", w=None, h=220, name=None, typewriter=True, speed=50, bold=False)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | str | `""` | Message text |
+| `w` | int | `None` | Width (default 60% of screen width) |
+| `h` | int | `220` | Height |
+| `name` | str | `None` | Character name tag (white rounded label protruding above the dialog) |
+| `typewriter` | bool | `True` | Typewriter mode |
+| `chardelay` | int | `50` | Typewriter interval per character (ms) |
+| `bold` | bool | `False` | Bold black stroke on text |
+| `overflow_mode` | string | `wrap` | Has three parameters: `wrap`, `overflow`, and `hide`. `wrap` enables automatic line wrapping, `overflow` causes content to overflow the screen, and `hide` hides the content that goes off-screen.|
+
+In typewriter mode:
+- Text appears character by character
+- First click → reveals full text instantly
+- Second click → closes
+
+```python
+dokibox.dialogbox("You're actually Administrator, right?", name="Monika")
+dokibox.dialogbox("Slower...", speed=80, bold=True)
+dokibox.dialogbox("All at once", typewriter=False)
+```
+
+## Finally
+
+This project is licensed under the `MIT` license. When using it, please **strictly** comply with Team Salvato's relevant fan work IP creation guidelines.
+
+> Sayori is my favorite!🎀

dokibox-1.0.0/README.md

@@ -0,0 +1,130 @@
+# dokibox
+
+A fan-made Python library for *Doki Doki Literature Club*, implementing various in-game prompt boxes using `tkinter`.
+
+> ### ⚠️ Credit & IP Guidelines
+> `dokibox` is a fan derivative work based on *Doki Doki Literature Club* (DDLC) and is not officially affiliated with Team Salvato. The original game can be downloaded [here](https://ddlc.moe/) or from the [Steam store page](https://store.steampowered.com/app/698780/Doki_Doki_Literature_Club/).
+>
+> Any user creating derivative works with this library **must** strictly follow the [official IP guidelines](https://teamsalvato.com/ip-guidelines).
+>
+> Special thanks to Joseph from Team Salvato for his support and responses via email!
+
+## Installation
+
+Install from PyPI:
+
+~~~bash
+pip install dokibox
+~~~
+
+## Import
+
+```python
+import dokibox
+```
+
+---
+
+### ynbox — Yes/No Dialog
+
+<img width="2560" height="1392" alt="image" src="https://github.com/user-attachments/assets/d40c9881-14bd-4876-877c-1d2008805c06" />
+
+```python
+dokibox.ynbox(msg="Delete?", tooltip=False) → bool
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | str | `""` | Message text |
+| `tooltip` | bool | `False` | Tooltip text |
+| `btn_texts` | tuple | None | Confirm button prompt. When set to None, `dokibox` will automatically detect the system language. To modify, please pass in a tuple, replacing "Yes" with the first parameter and "No" with the second parameter. English is used by default when the language is unknown. |
+
+Return value: clicking "Yes" returns `True`; clicking "No" or pressing Esc returns `False`.
+
+```python
+if dokibox.ynbox("Delete?"):
+    print("User clicked Yes")
+```
+
+---
+
+### msgbox — Message Box
+
+<img width="2560" height="1392" alt="image" src="https://github.com/user-attachments/assets/da5064d3-8d90-47ec-9b9e-20e87faf0fdc" />
+
+```python
+dokibox.msgbox(msg="Operation successful!", tooltip=False) → True
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | str | `""` | Message text |
+| `tooltip` | bool | `False` | Tooltip text |
+
+Single OK button. Closes on click, Enter, or Esc; returns `True`.
+
+```python
+dokibox.msgbox("Saved successfully!")
+```
+
+---
+
+### choicebox — Multiple Choice Dialog
+
+<img width="2560" height="1392" alt="image" src="https://github.com/user-attachments/assets/a33088b1-363b-48f5-8509-44a5d3ef5f4d" />
+
+```python
+dokibox.choicebox(msg="", choices=None, tooltip=False, force=None) → str | None
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | str | `""` | Prompt text; hidden when empty |
+| `choices` | list | `None` | List of choices |
+| `tooltip` | bool | `False` | Tooltip text |
+| `force` | int | `None` | Force-select an index (0-based); cursor moves to the center of that choice |
+
+Return value: the selected text content; Esc returns `None`.
+
+```python
+char = dokibox.choicebox("Choose a character", ["Sayori", "Yuri", "Natsuki"], force=1)
+print(char)  # "Yuri"
+```
+
+---
+
+### dialogbox — Bottom Dialog Box
+
+<img width="2560" height="1392" alt="image" src="https://github.com/user-attachments/assets/3817a140-66eb-496d-988d-7b728289a1ca" />
+
+```python
+dokibox.dialogbox(msg="", w=None, h=220, name=None, typewriter=True, speed=50, bold=False)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | str | `""` | Message text |
+| `w` | int | `None` | Width (default 60% of screen width) |
+| `h` | int | `220` | Height |
+| `name` | str | `None` | Character name tag (white rounded label protruding above the dialog) |
+| `typewriter` | bool | `True` | Typewriter mode |
+| `chardelay` | int | `50` | Typewriter interval per character (ms) |
+| `bold` | bool | `False` | Bold black stroke on text |
+| `overflow_mode` | string | `wrap` | Has three parameters: `wrap`, `overflow`, and `hide`. `wrap` enables automatic line wrapping, `overflow` causes content to overflow the screen, and `hide` hides the content that goes off-screen.|
+
+In typewriter mode:
+- Text appears character by character
+- First click → reveals full text instantly
+- Second click → closes
+
+```python
+dokibox.dialogbox("You're actually Administrator, right?", name="Monika")
+dokibox.dialogbox("Slower...", speed=80, bold=True)
+dokibox.dialogbox("All at once", typewriter=False)
+```
+
+## Finally
+
+This project is licensed under the `MIT` license. When using it, please **strictly** comply with Team Salvato's relevant fan work IP creation guidelines.
+
+> Sayori is my favorite!🎀

dokibox-1.0.0/dokibox/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""dokibox -- DDLC-style dialog library made by 99"""
+from dokibox.ynbox import ynbox
+from dokibox.choicebox import choicebox
+from dokibox.msgbox import msgbox
+from dokibox.dialogbox import dialogbox
+from dokibox.garbled import garbled

dokibox-1.0.0/dokibox/_base.py

@@ -0,0 +1,150 @@
+# -*- coding: utf-8 -*-
+"""dokibox internal base class -- window / gradient border / stroked text / dragging"""
+import tkinter as tk
+import math
+
+
+# --- default colors ---
+BORDER_COLOR = "#FFBBE3"
+BODY_COLOR = "#FEE6F4"
+
+
+def _get_dpi_scale():
+    try:
+        import ctypes
+        hdc = ctypes.windll.user32.GetDC(0)
+        dpi = ctypes.windll.gdi32.GetDeviceCaps(hdc, 88)
+        ctypes.windll.user32.ReleaseDC(0, hdc)
+        return dpi / 96.0
+    except Exception:
+        return 1.0
+
+
+# --- shared Tk root (NEVER destroyed, for Python 3.9 compat) ---
+_root_instance = None
+
+
+def _get_root():
+    global _root_instance
+    if _root_instance is None:
+        _root_instance = tk.Tk()
+        _root_instance.withdraw()
+    return _root_instance
+
+
+class _DokiBase:
+    """Dialog base class. Subclasses only need to implement _calc_size / _draw_content / _on_click"""
+
+    BORDER_W = 12
+
+    def __init__(self, msg, title="", pinned=True):
+        self.result = None
+        self._px = 0
+        self._py = 0
+        self._ox = 0
+        self._oy = 0
+
+        self.root = tk.Toplevel(_get_root())
+        self.root.overrideredirect(True)
+        self.root.attributes('-topmost', pinned)
+
+        self.w, self.h = self._calc_size(msg)
+        sw = self.root.winfo_screenwidth()
+        sh = self.root.winfo_screenheight()
+        x = (sw - self.w) // 2
+        y = (sh - self.h) // 2
+        self.root.geometry(f"{self.w}x{self.h}+{x}+{y}")
+
+        self.cv = tk.Canvas(
+            self.root, width=self.w, height=self.h,
+            bg=BODY_COLOR, highlightthickness=0
+        )
+        self.cv.pack()
+
+        self._draw_gradient_border()
+        self._draw_content(msg)
+
+        self.root.bind("<Escape>", lambda e: self._done(False))
+        self._make_draggable()
+        self.root.focus_force()
+
+    # ========== subclass must implement ==========
+
+    def _calc_size(self, msg):
+        raise NotImplementedError
+
+    def _draw_content(self, msg):
+        raise NotImplementedError
+
+    def _on_click(self, event):
+        pass
+
+    # ========== shared drawing utilities ==========
+
+    @staticmethod
+    def _hex_to_rgb(hex_color):
+        h = hex_color.lstrip('#')
+        return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+
+    def _draw_gradient_border(self):
+        br, bg, bb = self._hex_to_rgb(BORDER_COLOR)
+        er, eg, eb = self._hex_to_rgb(BODY_COLOR)
+        bw = self.BORDER_W
+        for i in range(bw):
+            t = (i / max(bw - 1, 1)) ** 3
+            r = int(br + (er - br) * t)
+            g = int(bg + (eg - bg) * t)
+            b = int(bb + (eb - bb) * t)
+            color = f'#{r:02x}{g:02x}{b:02x}'
+            self.cv.create_rectangle(i, i, self.w - i, self.h - i,
+                                     outline=color, width=1)
+
+    def _draw_stroked_text(self, x, y, text, font, fill, stroke, stroke_w):
+        for step in range(24):
+            angle = 2 * math.pi * step / 24
+            dx = stroke_w * math.cos(angle)
+            dy = stroke_w * math.sin(angle)
+            self.cv.create_text(x + dx, y + dy, text=text,
+                                font=font, fill=stroke, anchor="center")
+        self.cv.create_text(x, y, text=text, font=font,
+                            fill=fill, anchor="center")
+
+    # ========== dragging ==========
+
+    def _make_draggable(self):
+        self.cv.bind("<ButtonPress-1>", self._on_press, add='+')
+        self.cv.bind("<B1-Motion>", self._on_motion, add='+')
+        self.cv.bind("<ButtonRelease-1>", self._on_release, add='+')
+
+    def _on_press(self, event):
+        self._px = event.x_root
+        self._py = event.y_root
+        self._ox = event.x_root - self.root.winfo_x()
+        self._oy = event.y_root - self.root.winfo_y()
+
+    def _on_motion(self, event):
+        new_x = event.x_root - self._ox
+        new_y = event.y_root - self._oy
+        self.root.geometry(f"+{new_x}+{new_y}")
+
+    def _on_release(self, event):
+        dx = abs(event.x_root - self._px)
+        dy = abs(event.y_root - self._py)
+        if dx < 5 and dy < 5:
+            self._on_click(event)
+
+    # ========== lifecycle ==========
+
+    def _done(self, value):
+        self.result = value
+        try:
+            self.root.destroy()
+            _get_root().quit()
+        except tk.TclError:
+            pass
+
+    @classmethod
+    def show(cls, *args, **kwargs):
+        dialog = cls(*args, **kwargs)
+        _get_root().mainloop()
+        return dialog.result

dokibox-1.0.0/dokibox/choicebox.py

@@ -0,0 +1,264 @@
+# -*- coding: utf-8 -*-
+"""dokibox.choicebox -- DDLC-style multi-choice dialog (floating windows per option)"""
+import tkinter as tk
+import tkinter.font as tkfont
+from typing import Optional, List
+from dokibox._base import _get_root
+
+BORDER_COLOR = "#FFBBE3"
+BODY_COLOR = "#FEE6F4"
+OPT_FILL_COLOR = "#000000"
+OPT_HOVER_COLOR = "#999999"
+
+BORDER_W = 12
+OPT_FONT_SIZE = 24
+OPT_PAD_X = 80
+OPT_PAD_Y = 4
+OPT_GAP = 40
+UNIFIED_MIN_W = 600
+MSG_FONT_SIZE = 20
+MSG_PAD_Y = 16
+
+
+def _hex_to_rgb(hex_color):
+    h = hex_color.lstrip('#')
+    return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+
+
+class _Panel:
+
+    def __init__(self, master, text, index, pw, on_select, tooltip=False, pinned=True):
+        self.index = index
+        self.text = text
+        self._on_select = on_select
+        self._tooltip = tooltip
+
+        self.win = tk.Toplevel(master)
+        self.win.overrideredirect(True)
+        self.win.attributes('-topmost', pinned)
+
+        f_opt = tkfont.Font(family="Microsoft YaHei", size=OPT_FONT_SIZE, weight="normal")
+        th = f_opt.metrics('linespace')
+        self._font = ("Microsoft YaHei", OPT_FONT_SIZE, "normal")
+
+        self.pw = int(pw)
+        self.ph = int(th + OPT_PAD_Y * 2 + BORDER_W * 2)
+
+        self.win.geometry(f"{self.pw}x{self.ph}")
+
+        self.cv = tk.Canvas(self.win, width=self.pw, height=self.ph,
+                            bg=BODY_COLOR, highlightthickness=0)
+        self.cv.pack()
+
+        self._draw_gradient_border()
+        self._draw_option(text)
+
+        self.cv.bind("<Enter>", lambda e: self._set_hover(True))
+        self.cv.bind("<Leave>", lambda e: self._set_hover(False))
+        self.cv.bind("<Button-1>", lambda e: self._on_select(self.index))
+
+        if self._tooltip:
+            self._add_tooltip()
+
+    def _add_tooltip(self):
+        tip = [None]
+
+        def show(event):
+            if tip[0]:
+                return
+            tw = tk.Toplevel(self.win)
+            tw.overrideredirect(True)
+            tw.attributes('-topmost', True)
+            label = tk.Label(tw, text=self.text, bg=BODY_COLOR, fg='#000000',
+                             font=("Microsoft YaHei", 12),
+                             relief='solid', bd=1, padx=6, pady=2)
+            label.pack()
+            x = event.x_root + 15
+            y = event.y_root + 15
+            tw.geometry(f"+{x}+{y}")
+            tip[0] = tw
+
+        def hide(event):
+            if tip[0]:
+                tip[0].destroy()
+                tip[0] = None
+
+        self.cv.bind("<Enter>", show, add='+')
+        self.cv.bind("<Leave>", hide, add='+')
+
+    def _draw_gradient_border(self):
+        br, bg, bb = _hex_to_rgb(BORDER_COLOR)
+        er, eg, eb = _hex_to_rgb(BODY_COLOR)
+        bw = BORDER_W
+        for i in range(bw):
+            t = (i / max(bw - 1, 1)) ** 3
+            r = int(br + (er - br) * t)
+            g = int(bg + (eg - bg) * t)
+            b = int(bb + (eb - bb) * t)
+            color = f'#{r:02x}{g:02x}{b:02x}'
+            self.cv.create_rectangle(i, i, self.pw - i, self.ph - i,
+                                     outline=color, width=1)
+
+    def _draw_option(self, text):
+        cx = self.pw // 2
+        cy = self.ph // 2
+        self.cv.create_text(cx, cy, text=text, font=self._font,
+                            fill=OPT_FILL_COLOR, anchor="center",
+                            tags=("opt", "opt_fill"))
+
+    def _set_hover(self, hover):
+        items = self.cv.find_withtag("opt_fill")
+        color = OPT_HOVER_COLOR if hover else OPT_FILL_COLOR
+        for item in items:
+            self.cv.itemconfig(item, fill=color)
+
+    def set_position(self, x, y):
+        self.win.geometry(f"+{x}+{y}")
+
+    def destroy(self):
+        try:
+            self.win.destroy()
+        except tk.TclError:
+            pass
+
+
+class _ChoiceManager:
+
+    def __init__(self, msg, choices, title, tooltip=False, force=None, pinned=True):
+        self.result = None
+        self._tooltip = tooltip
+        self._force = force
+        self._pinned = pinned
+        self.root = _get_root()
+
+        f_opt = tkfont.Font(family="Microsoft YaHei", size=OPT_FONT_SIZE, weight="normal")
+        opt_widths = [f_opt.measure(c) for c in choices]
+        max_opt_w = max(opt_widths) if opt_widths else 0
+        unified_w = max(int(max_opt_w + OPT_PAD_X * 2 + BORDER_W * 2), UNIFIED_MIN_W)
+        screen_w = self.root.winfo_screenwidth()
+        unified_w = min(unified_w, screen_w - BORDER_W * 2)
+        self._unified_w = unified_w
+
+        self._panels = []
+        for i, choice in enumerate(choices):
+            panel = _Panel(self.root, choice, i, unified_w, self._on_select, self._tooltip, pinned=pinned)
+            self._panels.append(panel)
+
+        if msg.strip():
+            self._create_msg_label(msg)
+
+        self._layout(msg)
+
+        if force is not None and 0 <= force < len(choices):
+            self._force_index = force
+            p = self._panels[force]
+            cx = p.win.winfo_x() + p.pw // 2
+            cy = p.win.winfo_y() + p.ph // 2
+            self.root.after(50, lambda: p.win.event_generate(
+                '<Motion>', warp=True, x=p.pw // 2, y=p.ph // 2))
+
+    def _on_select(self, index):
+        self.result = index
+        for p in self._panels:
+            p.destroy()
+        if hasattr(self, '_msg_win'):
+            try:
+                self._msg_win.destroy()
+            except tk.TclError:
+                pass
+        try:
+            _get_root().quit()
+        except tk.TclError:
+            pass
+
+    def _create_msg_label(self, msg):
+        f = tkfont.Font(family="Microsoft YaHei", size=MSG_FONT_SIZE, weight="normal")
+        max_lbl_w = max(self._unified_w - 40, 200)
+
+        raw_lines = msg.split('\n')
+        wrapped_lines = []
+        for line in raw_lines:
+            if f.measure(line) <= max_lbl_w:
+                wrapped_lines.append(line)
+            else:
+                current = ""
+                for ch in line:
+                    test = current + ch
+                    if f.measure(test) <= max_lbl_w:
+                        current = test
+                    else:
+                        if current:
+                            wrapped_lines.append(current)
+                        current = ch
+                if current:
+                    wrapped_lines.append(current)
+
+        line_h = f.metrics('linespace')
+        total_h = line_h * len(wrapped_lines) + MSG_PAD_Y * 2
+        text_w = max(f.measure(line) for line in wrapped_lines)
+
+        lbl = tk.Toplevel(self.root)
+        lbl.overrideredirect(True)
+        lbl.attributes('-topmost', self._pinned)
+        self._msg_win = lbl
+        self._msg_w = max(int(text_w + 40), self._unified_w)
+        self._msg_h = int(total_h)
+        lbl.geometry(f"{self._msg_w}x{self._msg_h}")
+
+        cv = tk.Canvas(lbl, width=self._msg_w, height=self._msg_h,
+                       bg=BODY_COLOR, highlightthickness=0)
+        cv.pack()
+        cv.create_rectangle(0, 0, self._msg_w, self._msg_h,
+                            outline=BORDER_COLOR, width=4)
+        for j, line in enumerate(wrapped_lines):
+            y = MSG_PAD_Y + line_h // 2 + j * line_h
+            cv.create_text(self._msg_w // 2, y, text=line,
+                           font=("Microsoft YaHei", MSG_FONT_SIZE, "normal"),
+                           fill="#000000", anchor="center")
+
+    def _layout(self, msg):
+        sw = self.root.winfo_screenwidth()
+        sh = self.root.winfo_screenheight()
+
+        if not self._panels:
+            return
+
+        total_h = sum(p.ph for p in self._panels) + OPT_GAP * (len(self._panels) - 1)
+        if hasattr(self, '_msg_win'):
+            total_h += self._msg_h + OPT_GAP
+
+        start_y = (sh - total_h) // 2
+
+        if hasattr(self, '_msg_win'):
+            msg_x = (sw - self._msg_w) // 2
+            self._msg_win.geometry(f"+{msg_x}+{start_y}")
+            start_y += self._msg_h + OPT_GAP
+
+        for panel in self._panels:
+            px = (sw - panel.pw) // 2
+            panel.set_position(px, start_y)
+            start_y += panel.ph + OPT_GAP
+
+
+def choicebox(msg: str = "", choices: Optional[List[str]] = None, title: str = "", tooltip: bool = False, force: Optional[int] = None, pinned: bool = True) -> Optional[str]:
+    """DDLC-style multi-choice dialog. Each option is a floating window. Returns the selected text, or None if cancelled.
+
+    Args:
+        msg:      prompt text displayed above the options. No label shown if empty.
+        choices:  list of option strings to display.
+        title:    window title (unused in borderless mode).
+        tooltip:  show a floating tooltip when hovering over an option.
+        force:    pre-select an option by index (0-based). The mouse warps to its center.
+        pinned:   keep the windows always on top of other windows.
+
+    Usage:
+        import dokibox
+        text = dokibox.choicebox("Choose a character", ["Sayori", "Yuri", "Natsuki"], force=1)
+    """
+    from dokibox.dialogbox import _destroy_box
+    _destroy_box()
+    if not choices:
+        return None
+    mgr = _ChoiceManager(msg, choices, title, tooltip, force, pinned=pinned)
+    _get_root().mainloop()
+    return choices[mgr.result] if mgr.result is not None else None