Skip to content

armgit / BUI

Public Imported from GitHub
0

Blender's GPU Accelerated UI, Decoupled from it's original codebase. Supports Rust, Python, JS, React, C & C++. Twice as good as GPUI

8.4 KB
Raw Blame
---
title: Run a tkinter app on BUI
sidebarLabel: tkinter app
description: Take a plain tkinter program, run it on BUI without changing a line, then give it Blender's panels, sliders and number fields on purpose.
section: Tutorials
order: 20
languages: ["python"]
badges: ["10 minutes", "Beginner"]
sources: ["docs/tkinter.md", "examples/tk_unchanged_app.py", "README.md", "pyproject.toml", "bindings/python/bui/tksyntax/__init__.py", "bindings/python/bui/tksyntax/__main__.py", "SYNTAX_COVERAGE.md"]
---

You already have a tkinter app, or you know how to write one. In the next ten minutes you'll run it on BUI **without changing a line**, and it will come out looking and behaving like Blender.

Then you'll learn which tkinter widgets turn into which Blender widgets, so you can design for that look on purpose.

<Callout type="note" title="What you need">
Python 3.11 or newer and `pip install blenderui` ([installation](../../start/installation/)). To compare against the original look, you also need Python's own `tkinter`, which most Python installs include.
</Callout>

## The app

Here's a small, ordinary tkinter program: a render-settings form with a text entry, a spin box, a slider, a dropdown, a checkbox and a button. There's no BUI in it anywhere.

```py title="render_settings.py"
import tkinter as tk
from tkinter import ttk, messagebox

root = tk.Tk()
root.title("Render settings")

panel = ttk.LabelFrame(root, text="Output")
panel.pack(fill="x", padx=6, pady=6)

name = tk.StringVar(value="shot_010")
samples = tk.IntVar(value=128)
denoise = tk.BooleanVar(value=True)

ttk.Label(panel, text="Name").grid(row=0, column=0, sticky="e", padx=4, pady=2)
ttk.Entry(panel, textvariable=name).grid(row=0, column=1, sticky="we", pady=2)

ttk.Label(panel, text="Samples").grid(row=1, column=0, sticky="e", padx=4, pady=2)
tk.Spinbox(panel, from_=1, to=4096, textvariable=samples).grid(
    row=1, column=1, sticky="we", pady=2)

ttk.Label(panel, text="Quality").grid(row=2, column=0, sticky="e", padx=4, pady=2)
quality = tk.Scale(panel, from_=0, to=100, orient="horizontal")
quality.set(90)
quality.grid(row=2, column=1, sticky="we", pady=2)

ttk.Label(panel, text="Format").grid(row=3, column=0, sticky="e", padx=4, pady=2)
fmt = ttk.Combobox(panel, values=("PNG", "JPEG", "OpenEXR"), state="readonly")
fmt.current(0)
fmt.grid(row=3, column=1, sticky="we", pady=2)

ttk.Checkbutton(panel, text="Denoise", variable=denoise).grid(
    row=4, column=1, sticky="w", pady=2)
panel.columnconfigure(1, weight=1)

def render():
    messagebox.showinfo("Render", "%s: %d samples, %d%% %s" % (
        name.get(), samples.get(), quality.get(), fmt.get()))

ttk.Button(root, text="Render", command=render).pack(fill="x", padx=6, pady=(0, 6))
root.mainloop()
```

## Run it three ways

<Steps>

1. **Run it the usual way, for comparison.**

   ```sh
   python render_settings.py
   ```

   You get the classic Tk window. Close it.

2. **Run it on BUI, unchanged.**

   ```sh
   blenderui-tk render_settings.py
   ```

   Same file, same code, but now drawn by BUI. `blenderui-tk` comes with `pip install blenderui`. It makes `import tkinter` (and `tkinter.ttk`, `tkinter.messagebox` and the other submodules) point to BUI, then runs your script. Anything after the script's name is passed to it in `sys.argv`, as usual.

   If the `blenderui-tk` command isn't on your `PATH`, this does the same thing:

   ```sh
   python -m bui.tksyntax render_settings.py
   ```

3. **Or switch inside the program.**

   When you'd rather start the app with plain `python`, call `install()` before the first `import tkinter`:

   ```py title="render_settings.py" ins={1-2}
   import blenderui.tksyntax
   blenderui.tksyntax.install()   # before the first `import tkinter`

   import tkinter as tk
   from tkinter import ttk, messagebox
   ```

   From then on, every `import tkinter` in the process, including inside libraries you use, gets BUI.

4. **Or import it by name.**

   For new code that's meant for BUI, import BUI's tkinter directly and skip the switch:

   ```py
   import blenderui.tksyntax as tk
   from blenderui.tksyntax import ttk, messagebox
   ```

   The names and behaviour are tkinter's, so the rest of the file stays the same.

</Steps>

<Figure
  src="images/tkinter-render-settings.png"
  alt="The render settings form on BUI: an Output panel with a Name text field, a Samples number field showing 128, a blue Quality slider at 90, a Format dropdown set to PNG, a checked Denoise checkbox, and a Render button"
  caption="<code>render_settings.py</code> on BUI, unchanged. The <code>LabelFrame</code> became a panel, the <code>Spinbox</code> a number field and the <code>Scale</code> a slider."
  width={276}
  height={195}
/>

## Play with it

None of this needed extra code. It's Blender's behaviour, built into the widgets BUI draws:

- **Drag the Samples field** sideways. The cursor hides and the number scrubs. Hold <Kbd>Shift</Kbd> for fine steps, <Kbd>Ctrl</Kbd> to snap.
- **Click the Quality slider** and type `75`, or `100/3`, then press <Kbd>Enter</Kbd>. Sliders and number fields are Blender's, so they accept math. A plain `Entry` stays a text field and takes text as typed.
- **Press <Kbd keys="Ctrl+Z" />** to undo the last edit, and <Kbd keys="Ctrl+Shift+Z" /> to redo.
- **Press <Kbd>Tab</Kbd>** while editing a field to jump to the next one.
- **Click Render.** The message box is a Blender-styled dialog, and `showinfo` returns `"ok"` just like tkinter's.

## Which widget becomes what

You don't choose the look: it always comes from Blender's theme. But some tkinter widgets have a natural Blender twin, and BUI uses it:

| You write | You get |
| --- | --- |
| `ttk.LabelFrame` | A Blender panel |
| `tk.Spinbox` | A Blender number field |
| `tk.Scale`, `ttk.Scale` | A Blender slider |
| `ttk.Combobox`, `tk.OptionMenu` | A Blender dropdown (enum menu) |
| `tk.Checkbutton(indicatoron=0)` | A Blender toggle button |
| `tk.Menu` on the root | A Blender menu bar |
| `ttk.Scrollbar` | A Blender scroller that speaks Tk's scrollbar protocol |

So if you want a Blender-style tool, reach for `LabelFrame` to group settings and `Spinbox` for numbers. A plain `Entry` holding a number is still just a text field.

Options that only change Tk's own look, like `relief`, `borderwidth`, `highlightthickness`, `activebackground` and `ttk.Style` settings, are accepted and returned by `cget`, but they don't change what's drawn. These do apply: `bg` on frames, canvases and windows, `fg` on text, `font` (size and bold), `cursor`, `width` and `height`, `image` and `state`.

<Callout type="tip" title="GPU rendering">
With the import-by-name style you can ask for the GPU in code: `tk.Tk(gpu=True)`. For apps you run unchanged, set `BUI_GPU=1` instead. The pixels are the same; the CPU does much less work. If there's no usable GPU, the window stays on the CPU renderer.
</Callout>

## A bigger example

The repository has a fuller unchanged app with a menu bar, a notebook with three tabs, a `Treeview` table, a `Text` widget with tags and a `Canvas`:

```sh
blenderui-tk examples/tk_unchanged_app.py
```

<Figure
  src="images/tkinter_items.png"
  alt="An Inventory window on BUI: a File and Edit menu bar, Items, Notes and Canvas tabs, a New item panel with fields, and a table of objects"
  caption="<code>examples/tk_unchanged_app.py</code>: plain tkinter, no BUI imports."
  width={386}
  height={408}
/>

## If something looks different

BUI follows Tk's rules and checks them against the real tkinter in its tests, so differences are bugs. A few Tk rules surprise people anyway, on any toolkit: `Text.get("1.0", "end")` ends with a newline (use `"end-1c"`), and menus keep a tear-off entry at index 0 unless you pass `tearoff=0`. The [tkinter guide](../../python/tkinter/) lists these, plus the few things BUI can't do (there's no Tcl interpreter, so `root.tk.call` only knows a handful of commands).

## Next steps

<CardGrid>
  <Card title="tkinter on BUI" href="docs/python/tkinter/" icon="book" kicker="Python">
    The full guide: module map, behaviour notes, limitations and testing against stdlib tkinter.
  </Card>
  <Card title="Blender components" href="docs/tutorials/first-app-python/" icon="sparkles" kicker="Tutorial">
    Starting fresh? Build with Blender's own widgets instead.
  </Card>
  <Card title="Qt syntax" href="docs/tutorials/first-app-qt/" icon="layers" kicker="Tutorial">
    Prefer <code>QWidget</code> and <code>clicked.connect</code>? Build the same kind of form in Qt style.
  </Card>
</CardGrid>