Area Settings Reference (Paint)

The QSettings schema behind paint's named-areas registry. Useful for scripting area creation, bulk imports, or backups outside the app.

Where the data lives

Named areas are persisted via QSettings under the application's default org/app keys (the same store that holds brush state, panel geometry, and so on). On Linux that's typically ~/.config/<org>/<app>.conf.

All keys live under the ui/paint/areas/ group.

Discovery key

Key Type Notes
ui/paint/areas/uuids QStringList Ordered list of all known area uuids. The list order is the display order in the Areas tab and in AreaListActivity.

When you add or remove an area, the application writes the full updated uuid list AND the per-area group AND calls QSettings::sync() in the same operation, so a crash mid-edit leaves the store consistent.

Per-area group

For each uuid in ui/paint/areas/uuids, a group of the form ui/paint/areas/<uuid>/ holds:

Key Type Notes
ui/paint/areas/<uuid>/name QString User-given name. Unique constraint enforced on write — duplicate name → write rejected.
ui/paint/areas/<uuid>/rectX int Top-left x in canvas pixels.
ui/paint/areas/<uuid>/rectY int Top-left y in canvas pixels.
ui/paint/areas/<uuid>/rectW int Width in canvas pixels, must be ≥ 1.
ui/paint/areas/<uuid>/rectH int Height in canvas pixels, must be ≥ 1.
ui/paint/areas/<uuid>/inputPath QString May be empty. The path Load reads from. Stored as the user entered it; resolved through QFileInfo::absoluteFilePath at action time.
ui/paint/areas/<uuid>/outputPath QString May be empty. The path Save writes to. Same resolution rules as inputPath.

Overlay opacity

A separate setting controls how strongly area frames show on the canvas. It is independent of the chunk-debug overlay.

Key Type Default Notes
ui/paint/canvas/showAreasOpacity float 0 0 hides the frames, 1 shows them fully. The Areas tab and the Area overlay opacity row of the paint settings window write it.

Invariants

Anything the application writes guarantees:

  1. Pixel-aligned rect. rectX / rectY / rectW / rectH are always integers. The drag-to-create tool rounds via floor(x + 0.5).
  2. Non-degenerate rect. rectW ≥ 1 and rectH ≥ 1. Smaller rects are silently dropped during drag, rejected on form submit.
  3. Unique names. Two areas can't share a name. The application auto-uniquifies a colliding name to <base>-2, <base>-3, …
  4. uuids match groups. Every uuid in ui/paint/areas/uuids has a per-area group with at least name / rectX / rectY / rectW / rectH populated.

If you hand-edit the conf file and break one of these, the application refuses to load the offending entry — it logs a warning and skips it rather than crash.

Scripting an area from scratch

To inject an area without launching the app, write the per-area group and append the uuid to the discovery list. A minimal entry in ~/.config/<org>/<app>.conf:

[ui%2Fpaint%2Fareas]
uuids=a1b2c3d4-1234-5678-90ab-cdef12345678

[ui%2Fpaint%2Fareas%2Fa1b2c3d4-1234-5678-90ab-cdef12345678]
name=Hero pose
rectX=128
rectY=64
rectW=512
rectH=768
inputPath=/home/me/refs/hero.png
outputPath=/home/me/output/hero.png

QSettings percent-encodes / as %2F in INI section headers. The uuid itself uses the QUuid::WithoutBraces format (lowercase hex, hyphens, no braces).

In this section