ui-tables

Intelligent Qt Tables

The trap (why tables go wrong)

Qt gives you two blunt instruments and no good default:

• ResizeToContents sizes each column to its content — but never caps it, so a long path column can run off the screen.
• Stretch / setStretchLastSection(True) makes a column eat all the leftover width. Put it on the wrong column and a field showing only 1 / 2 becomes enormous. (This is the exact FK_Pro "File" column bug.)

Equal-width columns are just as wrong: a one-digit column deserves ~50 px, a file path deserves the rest.

The rule (TB — table design)

• TB1 — Size to content, then cap. Every column starts at the width of its widest sampled cell + its header, then is clamped to a per-role min/max.

• TB2 — Exactly the flexible column(s) absorb slack. Leftover width goes to the primary text column(s) — never to a number, index, or status column. If there's no flexible column, leave trailing empty space; don't stretch a number.

• TB3 — Role decides width + alignment:

  Role	Width	Align	Examples
  index	tiny (≈28–64)	centre	row #, id, "1"/"2"
  status	tiny (≈22–52)	centre	dot / flag / D M R S
  num	small (≈54–120)	right	"76.0", offsets, counts
  short	content (≈60–220)	left	"rev", names, codes
  flex	absorbs slack (≥140)	left + elide	paths, descriptions

• TB4 — Numbers right-align; long text elides with a tooltip. setTextElideMode(Qt.ElideRight), full value in the tooltip. Never wrap rows into multiple lines unless the column is explicitly multi-line.

• TB5 — Re-balance on resize, not just at startup, so widening the window feeds the flex column, not a frozen layout.

• TB6 — Quiet chrome. One header weight, subtle gridlines (or none + alternating row colors), comfortable row height (~22–26 px), selectionBehavior=SelectRows for record tables. Let the data, not the borders, carry the eye.

• TB7 — Short tables don't sprawl vertically. Cap a few-row table's height to its rows (+header) instead of leaving a tall empty body (see ui-design-standards S1).

How to apply it — smart_columns()

Use the bundled helper (scripts/smart_columns.py, dependency-free, works for QTableView and QTableWidget). Call it after the model/items are set:

from smart_columns import smart_columns

smart_columns(table)                                   # fully automatic
smart_columns(table, roles={0: "index", 4: "flex"})    # override classification
smart_columns(table, caps={"num": (50, 90)})           # tune a role's min/max

It classifies each column (by sampling the data), measures content + header, clamps to role caps, gives leftover width to the flexible column(s), right-aligns numbers, centres status/index, elides long text, and re-runs on resize.

For a fixed, tiny static table you can instead set widths by hand following TB3 — the helper is for any table whose contents vary.

Verify

Render the table with the ui-visual-review loop at a wide/maximized width and a narrow one. Pass when: no column is wide for trivial content (TB1/TB2), numbers are right-aligned (TB4), long values elide instead of overflowing, and the table doesn't leave a giant empty body (TB7).

Reference

• QHeaderView resize modes: https://doc.qt.io/qt-6/qheaderview.html