Skip to content

THEME.md: the whole theme reference, with pictures (and the image crash fix) - #383

Merged
kloptops merged 3 commits into
PortsMaster:mainfrom
kloptops:theme-docs
Nov 12, 2026
Merged

kloptops merged 3 commits into
PortsMaster:mainfrom
kloptops:theme-docs

Conversation

@kloptops

Copy link
Copy Markdown
Member

THEME.md was a partial, unfinished reference: no color schemes, a third of the region keys and screens missing, and some of it wrong. This rewrites it as the reference for everything a theme can do, and fixes a crash it turned up.

This includes the image fix commit (theme-images): merge this one alone to get both.

The image crash

  • Regions keep the images they load, but the 30-image cache destroyed old textures even while a region still held one. A theme whose list pointer wasn't in #resources crashed ("Cannot use a texture after it has been destroyed") once enough port screenshots had loaded.
  • Now the theme's own images (found by name: #resources, a region's image, pimage and pointer, animation frames) stay loaded until the theme reloads.
  • Data images (screenshots by absolute path, QR codes) are cached as before. One a region still holds after the cache dropped it loads itself again on its next draw.
  • Tested in tests/test_image_cache.py: all six tests fail without the fix.

THEME.md

  • Covers a theme's files, how a region gets its keys, capabilities, areas, colors, text, images (atlases, 9-patch, QR codes, which images stay loaded), lists, pointers and grids, the button bar and special words, templates, color schemes, styles, elements, layouts, translations, sounds, animations, the theme server, and what older PortMasters do with each newer feature.
  • Lists every screen with the regions it needs and the tags it sets, plus tables of all 83 region keys and all 71 tags.
  • Corrects the old doc:
    • Areas are two corners, not x, y, width, height.
    • {if:tag} is true when the tag isn't empty (the old table had it backwards).
    • A theme needs seven sections, not four: port_info, filter_list and message_box have no fallback, and PortMaster quits when one of those screens opens without its section.
    • on_screen_keyboard is listed as unused: nothing opens it.
  • docs/theme/ holds 30 pictures (3.6 MB), all real renders of the default theme from the theme server: every screen, numbered region maps, the color schemes, both layouts, three languages, four screen sizes, the 9-patch, the pointer, and the theme server's pages. tools/theme_docs.py makes them again (it needs Pillow). docs/ isn't in the release zip.
  • tests/test_theme_docs.py fails when the engine has a region key, screen, tag, # section or #info key THEME.md doesn't name, or a picture or internal link is missing. It turned up an undocumented key, scroll-direction.

Theme editor

  • It flagged the default theme's own #layouts ("PortMaster doesn't use") and #info's default-layout. It now knows both, suggests layout names for default-layout, and warns about one #layouts doesn't have.
  • A test checks the editor knows every key the default theme uses.

The step-by-step guide, CREATING_A_THEME.md, is a separate PR on PortMaster-Themes; THEME.md links to it.

Tested: the full suite on Python 3.7 and 3.13, the new tests on 3.12–3.14, and the flake8 errors-only lint.

🤖 Generated with Claude Code

kloptops and others added 3 commits November 12, 2026 12:35
…t holds them

The image cache kept the 30 most recently loaded images and destroyed the
rest, including ones a region still held: a theme whose list pointer
wasn't in #resources crashed ("Cannot use a texture after it has been
destroyed") once enough port screenshots had loaded.

Now:
- theme images, found by name (the theme's files and PortMaster's:
  #resources, a region's image, pimage and pointer, animation frames),
  stay loaded until the theme reloads
- data images (screenshots and other absolute paths, QR codes) are cached
  as before, and one a region still holds after the cache dropped it
  loads itself again on its next draw

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NxABmR1rUUgi4iicVLZchY
The editor flagged the default theme's own #layouts ("PortMaster doesn't
use") and #info's default-layout. It now suggests the layout names for
default-layout and warns about one #layouts doesn't have. A test checks
the editor knows every key the default theme uses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NxABmR1rUUgi4iicVLZchY
A rewrite of THEME.md as the reference for every theme key: files,
inheritance, capabilities, areas, colors, text, images, lists, the button
bar, templates, color schemes, styles, elements, layouts, translations,
sounds, animations, every screen with its required regions, every region
key and every tag, the theme server, and what older PortMasters do.

It corrects what the old one got wrong: areas are two corners (the old
one said x, y, width, height), {if:tag} is true when the tag isn't empty,
and a theme needs seven sections, not four (port_info, filter_list and
message_box too).

The pictures in docs/theme/ are real renders of the default theme, made
by tools/theme_docs.py with the theme server. tests/test_theme_docs.py
fails when the engine has a region key, screen, tag or section THEME.md
doesn't name, or a picture is missing.

The step-by-step guide, CREATING_A_THEME.md, is in PortMaster-Themes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NxABmR1rUUgi4iicVLZchY
@kloptops
kloptops merged commit f1d62e6 into PortsMaster:main Nov 12, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant