look: how the system's windows look -- the theme and the frame, as a
library of their own, so that the screen draws frames with it, a picture
can be drawn of a theme without a screen, and a different look is a
different theme file or, for a shape no theme can say, a different frame
module built in.

  lib/look/theme.talc   (look theme)  a theme, from a file of forms the way
                        Openbox reads its themerc: font, border, padding,
                        the title bar's side and layout, handle, shadow,
                        colours, button bitmaps; what a line left out keeps
  lib/look/frame.talc   (look frame)  a window's frame drawn as a theme
                        says, around a content rectangle on any (canvas)
                        surface: title bar on any of the four sides, its
                        buttons, border, handle, shadow; what the frame
                        adds on each side, and which part of it a point is on
  lib/look/elements.talc (look elements)  the elements a control is drawn
                        out of -- a face, a well, a pick, an edge -- as
                        the theme's widgets section says
  lib/look/icons.talc   (look icons)   icons named by what they mean --
                        folder, file, talc, executable -- from the pack
                        the theme names, a directory of PNGs under the
                        icons directory the screen hands every program;
                        which icon a file gets, decided here once for
                        every program's list
  lib/look.talc         (look)        the three above under one import
  themes/               plain.theme and its button bitmaps: the built-in
                        look, written out, which is also the file to copy
  icons/standard/       the icon pack built in: file, folder, talc and
                        executable, 24 by 24; a theme
                        says (icons "other") for another pack beside it
  tools/preview.talc    a theme looked at without a screen: two framed
                        windows drawn into a picture
  examples/             left, right and bottom: one-line themes that move
                        the bar; classic: a 1995 desktop, bevels, a blue
                        title bar and Helvetica's bitmap; and the picture
                        each is expected to draw
  scripts/build.sh      builds tools/ into bin/, against lib/ here,
                        ../canvas/lib and the toolchain's
  scripts/regress.sh    draws every theme here with bin/preview and
                        compares the pictures with examples/*.ppm

Build:

  scripts/build.sh
  scripts/regress.sh

which need the installed toolchain (compiler on PATH) and ../canvas built
(its fonts). To look at a theme while editing it:

  bin/preview ../canvas/fonts out.ppm -theme my.theme

and ../screen/bin/screen ... -theme my.theme puts it on the screen, where
super+r reads it again.

A THEME IS DATA, and a theme file says only what it changes: every line
left out keeps the built-in value, so

  (theme "left" (title (side left)))

is a whole theme, the built-in look with the title bar down the left
side. A theme also says what ../toolkit draws inside a window with, in
the (widgets ...) section, so one file is the whole look, frames and
contents.

THE WIDGETS SECTION is three layers, so that themes can look like
different decades and not like one desktop in different colours. ROLES
are colours by what they mean -- paper, page (the ground of text typed
or picked from), ink, faint, accent, pick, pick-ink, edge, raised -- and
a control draws in roles, so a theme never needs to know which controls
exist. METRICS are sizes: bevel, gap (the room a window leaves between
its parts), and the theme's padding. ELEMENTS are
how the things controls are made of are drawn, as a style over the
other two: a face is flat, raised or sunken, a well or a list's ground
is flat, outlined, underlined or sunken, the relief is single (a
bevel one ring of two tones) or double (two rings of four, the way 1995
drew them), a scroll bar is thin (a line for a thumb, nothing else) or
has arrows at its ends and a face for a thumb, and its track is plain
or 1995's checker of page and paper; (look elements) draws them, with a
bevel's tones all made from the colour it bevels: halfway to white and
two thirds of the way to black, the brighter ring of a double relief
halfway to white again and never white, which would look like the
page. Any other (name ...) line is kept for a
control that asks for it by name, with a role to fall back on.
examples/classic.theme is the proof: grey raised faces with the double
bevel, sunken wells and lists on white, a four-pixel raised frame, a
blue title bar, Helvetica's bitmap, no shadow -- 1995 as one file --
and the plain theme beside it is flat
faces and an orange underline, from the same code. What a theme cannot
say yet: rounded corners, gradients, images; each is a word added to
the elements when a theme wants it. (look theme) lists every line; themes/plain.theme is the built-in
look written out with a comment on each. examples/classic.theme is the
other direction: (font "helv-12"), the 1984 Helvetica bitmap the canvas
draws pixel for pixel and never smooths, no shadow, a thicker border --
the old-school look is three lines, since any bitmap font the canvas
has (../canvas/scripts/bitmap-font.py makes one from a BDF or PCF) is a
font a theme can name.

ICONS are the fourth thing a theme names, beside its font, its colours
and its elements: (icons "standard") is a directory of PNGs,
<icons>/standard/<name>.png, under the icons directory ../screen is
started with (-icons, handed on as SCREEN_ICONS, as the fonts are
SCREEN_FONTS). An icon is asked for BY WHAT IT MEANS -- folder, file,
talc, executable -- never by a file name, as a colour is asked for by
its role: (look icons) opens a pack, answers (icon-named icons 'folder)
with a (canvas) surface read by (canvas picture) when first asked for
and kept, and decides in one place, icon-kind, which name a file gets
(a directory, a .talc file, a file some party may execute, any other),
so that a file is the same picture in every program's list. A pack
that lacks a name shows the file icon, so a theme's own pack need not
be complete; a program started without an icons directory gets a set
that answers #f to every name and draws nothing. ../toolkit's list
takes an icon with each item and ../editor shows them beside its files
and on its tabs.

THE SIDE. (title (side top|bottom|left|right)) puts the title bar above
the content, below it, or along its left or right. The bar is laid out
along its length -- the buttons before the L in (layout "LC") at its
start, the text, the buttons after L at its end -- and on the left and
the right it is turned as if the window had been stood on its side: on
the left it reads upward, its start at the bottom, and on the right
downward, buttons turned with it. A button is its image on the bar, or,
with (title (buttons face)), its image on a face of its own drawn as the
widgets section draws a button -- raised, sunken while held -- which is
how 1995 set grey squares on its blue bar; the other themes keep their
images bare. The handle, when there is one, is on
the side opposite the bar. Everything else -- the border, the resize
edges, the shadow -- does not care where the bar is. The border is flat
unless the theme says (edge raised) or (content sunken): then its
outermost pixels are a bevel of the border colour, and its innermost
ones a bevel around the content, `bevel` wide. examples/classic.theme
raises the edge and leaves the content flat, as that desktop did: it
sank its controls, not its windows.

THE FRAME knows nothing of the screen. It is told a frame-state -- the
content rectangle, the title, whether the window is active, which button
is held down -- and draws around it on whatever surface it is given, or
answers what part of itself a point is on: content, title, a button's
name, a resize edge. ../screen's (screen compose) builds a frame-state
from each of its windows and draws with it; tools/preview.talc builds
two by hand, which is how the look is regressed without a card. The
pointer's bindings in ../screen name parts, so a frame with fewer parts
or other ones breaks none of them.

ANOTHER FRAME. The frame module's exports are the contract -- extents,
draw, shadow, part at a point, the title's and a button's rectangle. A
look the theme cannot describe is a module with those exports in place
of lib/look/frame.talc, and the screen built with it; talc links
statically, so that is a build, not a setting. The theme grows as looks
are wanted that it can describe.

Widgets -- buttons, fields, lists for programs to build their content
from -- are the obvious third module here, and are not here yet.