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

10.6 KB
Raw Blame

tkinter on BUI

bui.tksyntax is a complete implementation of the tkinter API on BUI's C kit. Programs keep their tkinter code and get Blender's look and interactions.

A plain tkinter program on BUI

Three ways to use it

1. Run an existing program unchanged

python -m bui.tksyntax my_app.py [args...]

This runs the script with tkinter (and tkinter.ttk, tkinter.messagebox ...) pointing to BUI. sys.argv is passed through, so the script sees its own arguments.

2. Switch inside your program

import bui.tksyntax
bui.tksyntax.install()   # before the first `import tkinter`

import tkinter as tk
from tkinter import ttk

install() covers tkinter and its submodules: ttk, messagebox, filedialog, simpledialog, colorchooser, commondialog, dialog, font, scrolledtext and constants.

filedialog (askopenfilename, asksaveasfilename, askopenfilenames, askdirectory, ...) shows Blender's File Browser in its own window. It accepts tkinter's options (title, initialdir, initialfile, filetypes, defaultextension) and returns what tkinter returns. Set BUI_FILEDIALOG=native to get the operating system's dialogs instead.

3. Import it by name

import bui.tksyntax as tk
from bui.tksyntax import ttk, messagebox, filedialog

Example

import tkinter as tk
from tkinter import ttk, messagebox

root = tk.Tk()
root.title("Inventory")

# menus become a Blender menu bar
menubar = tk.Menu(root)
filemenu = tk.Menu(menubar, tearoff=0)
filemenu.add_command(label="Quit", accelerator="Ctrl+Q", command=root.destroy)
menubar.add_cascade(label="File", menu=filemenu)
root.config(menu=menubar)

form = ttk.LabelFrame(root, text="New item")            # a Blender panel
form.pack(fill="x", padx=6, pady=6)
name = tk.StringVar(value="Cube")
ttk.Label(form, text="Name").grid(row=0, column=0, sticky="e", padx=4)
ttk.Entry(form, textvariable=name).grid(row=0, column=1, sticky="we")
ttk.Label(form, text="Count").grid(row=1, column=0, sticky="e", padx=4)
tk.Spinbox(form, from_=1, to=99).grid(row=1, column=1, sticky="we")  # a number field
form.columnconfigure(1, weight=1)

tree = ttk.Treeview(root, columns=("name", "kind"), show="headings", height=5)
for col in ("name", "kind"):
    tree.heading(col, text=col.title())
tree.insert("", "end", values=("Cube", "Mesh"))
sb = ttk.Scrollbar(root, orient="vertical", command=tree.yview)
tree.configure(yscrollcommand=sb.set)
tree.pack(side="left", fill="both", expand=True)
sb.pack(side="right", fill="y")

ttk.Button(root, text="About",
           command=lambda: messagebox.showinfo("About", "Plain tkinter")).pack()
root.mainloop()

The full version is examples/tk_unchanged_app.py.

GPU rendering

Pass gpu=True to draw the window on the GPU (Direct3D 11) instead of the CPU:

import bui.tksyntax as tk

root = tk.Tk(gpu=True)

The pixels are the same, but rendering uses far less CPU, which helps busy Canvas scenes most. For apps you run unchanged (python -m bui.tksyntax app.py), set BUI_GPU=1 instead, or call bui.set_gpu(True) before the first Tk() (and bui.set_slug(False) for the glyph-atlas text path instead of Slug). The first frames draw on the CPU while the device starts. If no GPU is available, the window stays on the software raster.

Module map

tkinter BUI Notes
tkinter bui.tksyntax Tk, Toplevel, every classic widget, variables, Event, PhotoImage, BitmapImage, mainloop, constants
tkinter.ttk bui.tksyntax.ttk Themed widgets including Treeview, Notebook, Progressbar, Combobox, Separator, Sizegrip, LabeledScale, Panedwindow, Style. state() / instate() work.
tkinter.messagebox .messagebox Blender-styled modal dialogs with the same return values ("ok", True, None ...)
tkinter.simpledialog .simpledialog Dialog (override body / validate / apply), SimpleDialog, askstring, askinteger, askfloat
tkinter.filedialog .filedialog Blender's File Browser in its own window, with the same functions and return values; BUI_FILEDIALOG=native uses the operating system's dialogs instead
tkinter.colorchooser .colorchooser askcolor with Blender's color picker; returns ((r, g, b), "#rrggbb")
tkinter.font .font Font, named fonts (TkDefaultFont ...), measure / metrics through the native text engine
tkinter.scrolledtext .scrolledtext ScrolledText, as in tkinter
tkinter.dialog, .commondialog, .constants same names

What you get

  • Geometry managers. pack, grid and place with every option: in_, before/after, ipadx, sticky, spans, columnconfigure weights and minsize, grid_remove, *_info, *_slaves, grid_bbox, grid_location, grid_size, and pack_propagate(False). The packer and gridder are C ports of Tk's own algorithms.
  • Scrolling. xview / yview / *_moveto / *_scroll and x/yscrollcommand work on Listbox, Text, Treeview and Canvas. Canvas adds scrollregion, confine, scroll increments and scan_*. Scrollbar is drawn as a Blender scroller and speaks Tk's protocol, so sb.config(command=lb.yview); lb.config(yscrollcommand=sb.set) works. Scrollable frames (Canvas + create_window + <Configure> → scrollregion=bbox("all")) work too.
  • Bindings. bind, bind_all, bind_class, bindtags, unbind*, event_add and event_generate:
    • modifiers (Control, Shift, Alt, B1), Double-, buttons 1–3, <B1-Motion>, <KeyPress> / <KeyRelease>;
    • <MouseWheel> (Button-4/5 on X11), <Enter> / <Leave>, <Configure>, <Map>, <Destroy>, <FocusIn/Out>, and virtual events;
    • callbacks run once per bindtag and stop on "break";
    • Event carries Tk's fields.
  • Widgets. Entry supports show="*" and validate / validatecommand with %P %s %S %d %i %V %W. Listbox supports selectmode single / browse / multiple / extended, with Ctrl and Shift clicks. Treeview has sortable headings (heading(command=...)), show="headings" tables, <<TreeviewOpen>> / <<TreeviewClose>>, and move / detach / reattach. Also included: Notebook, PanedWindow with draggable sashes, OptionMenu (a Blender enum dropdown), Menubutton, and Message.
  • Canvas.
    • Items: all types, including window, smoothed lines and arrowheads.
    • Tags: tag expressions ("a&&!b"), find_* / addtag_*, and tag_bind with current plus per-item <Enter> / <Leave>.
    • Editing: shape-accurate hit tests, move / moveto / scale / coords, and editing text items in place.
  • Text.
    • Indices: the full grammar (3.5, end-1c, insert lineend, @x,y, tag.first, marks, +N lines, wordstart ...).
    • Tags: foreground and background colors, priorities, and tag_bind.
    • Also: marks with gravity, search (regexp, backwards, count), dump, count, the undo stack, <<Modified>>, and peers.
  • Windows. geometry (size and +x+y), attributes (-topmost, -alpha, -fullscreen, -disabled), resizable, minsize / maxsize, overrideredirect, state / iconify / withdraw, transient, protocol("WM_DELETE_WINDOW"), grab_set (disables the other windows), clipboard, after / after_idle / after_info, wait_window, wait_variable and every winfo_*.
  • Images. PhotoImage decodes with the kit's image module (the C decoders every BUI binding shares): Tk's PNG, GIF (format="gif -index n" picks a frame) and PPM / PGM, and also JPEG, WebP, BMP, TGA, QOI, Radiance HDR and SVG. It supports put / get / copy / zoom / subsample / copy_replace / data and write (PNG, PPM). BitmapImage reads XBM.

The Blender look

The look always comes from Blender's theme:

  • tk.Scale and ttk.Scale are Blender sliders (drag to scrub, click to type).
  • Spinbox is a Blender number field.
  • Combobox and OptionMenu are Blender enum dropdowns.
  • LabelFrame is a Blender panel.
  • Checkbutton(indicatoron=0) is a Blender toggle button.

Some options only change Tk's appearance: relief, borderwidth, highlightthickness, activebackground, selectcolor, ttk.Style settings and similar. They are accepted and returned by cget, but they don't change what's drawn.

These options do apply:

  • bg on Frame, Canvas and windows
  • fg on text
  • font (size and bold: font=("Arial", 18, "bold"))
  • cursor ("hand2", "xterm", "fleur" ...)
  • width / height (characters or pixels, as in Tk)
  • image
  • state

On top of that, every widget gets Blender's interactions (see components.md). Number fields scrub, Ctrl+Z / Ctrl+Shift+Z undo edits, and Tab moves to the next field.

Behaviour

BUI follows Tk's semantics, checked against the stdlib by bindings/python/tests/test_tk_compat.py. Some of them are easy to miss:

  • textvariable overrides text, and cget("text") returns the variable's value.
  • A Scale's command and <<TreeviewSelect>> run when the loop is idle, not inside set() / selection_set().
  • validatecommand also sees programmatic insert / delete.
  • Generated key events (event_generate("<Control-q>")) go to the widget with keyboard focus.
  • Menus keep Tk's tearoff entry at index 0 unless you pass tearoff=0. On macOS the default is tearoff=0, as in Tk on Aqua.
  • Text keeps the trailing newline: get("1.0", "end") ends with "\n", so use "end-1c".
  • edit_undo() does nothing while undo is off.
  • A Notebook requests the size of its largest page.
  • A Toplevel appears when the loop is next idle, sized to its content.
  • Checkbutton and Radiobutton create a variable if you don't give one, as Tk does.

Limitations

  • send raises TclError, as on Windows Tk.
  • Images and windows embedded in a Text (image_create, window_create) are kept and listed, but not drawn.
  • There's no Tcl interpreter. root.tk.call(...) handles a few common commands (tk scaling, wm ..., set, info patchlevel) and raises TclError for the rest.
  • Canvas dash / stipple and postscript output are accepted but not rendered.

Testing your app against tkinter

bindings/python/tests/test_tk_compat.py runs programs on both the stdlib and BUI and compares what they observe:

def prog_mine(tk, ttk):
    root = tk.Tk()
    lb = tk.Listbox(root)
    lb.insert("end", "a", "b")
    lb.selection_set(1)
    result = {"sel": lb.curselection()}
    root.destroy()
    return result

Add your function to PROGRAMS and run python bindings/python/tests/test_tk_compat.py.