PiClock3 Theme Template

A starting point for a PiClock3 theme. Press Use this template to make your own repository from it.

It runs as it stands: a dark ground, amber frames and a light-blue clock. Replace the art and the colors with yours.

That is examples/example.yaml below, on the classic layout. Replace the picture with one of yours - it is the first thing anybody looks at.

Try it first

From the top of a PiClock3 checkout:

git clone https://github.com/yourname/piclock3-example-theme themes/example
python3 PyQtPiClock3.py themes/example/examples/example.yaml

That config is carried in this repository, which is the quickest way to let somebody see a theme without editing a config of their own. Name yours in a config of your own the same way:

pages:
  clock-page: {order: 0, layout: classic, theme: example}

theme: is the folder it was cloned into. Two themes both called midnight are told apart by renaming a directory.

What a theme is

Colors, fonts, the background, the frames drawn around regions, and which art each kind of widget uses. A theme holds no code, so there is nothing to review before running somebody else's - the worst it can do is be ugly.

A theme never decides where anything goes. No positions, no sizes. Those live in the layout, and keeping that line clean is what lets any theme work with any layout.

What is in here

theme.yaml              the whole theme
images/background.png   behind everything
images/frame.png        the sheet a frame is cut from
examples/example.yaml   a clock wearing it, run by naming it
screenshot.png          what it looks like, shown above
README.md               and a license for the pictures

A plain relative path is relative to this folder, so a published theme never has to know where it was installed. {this-folder}/background.png says the same thing explicitly, and is what to write in a file that might be included from somewhere else.

A repository may also carry layouts/, languages/, units/ and another theme. A theme drawn against a layout nobody else has can bring it: a layout you bring can add a name, never replace one.

Frames

borders:
  default: {art: images/frame.png, width: 0.012, inset: 0.5}

width is a fraction of the region and inset is how far the frame's own edge sits inside its picture. How the sheet itself is cut - which part is corner, which stretches - is FRAME-ART.md.

A layout region's border: names one of these, or says true for default.

Art the widgets use

kind-settings:
  analog-clock:       {clock-images-folder: lightblue}
  current-conditions: {icons-folder: icons-lightblue}
  forecast:           {icons-folder: icons-lightblue}

A kind means interchangeable with, so this reaches every clock face or every forecast column at once without naming anybody's widget. Those three name sets that ship with PiClock3. Draw your own, put them in this folder, and say {this-folder}/icons-example instead - MARKER-ART.md and FRAME-ART.md are about drawing them.

Before you publish

• Replace screenshot.png with yours. A theme without a picture is invisible - nobody clones four repositories to see what they look like
• python3 PyQtPiClock3.py themes/example/examples/example.yaml --check
• Try it against more than one layout, since that is the promise
• A license for the images. A theme is mostly pictures, and that is the part somebody actually has to check
• Add the topic piclock3-theme to your repository so people can find it

The long form

WRITING-A-THEME.md is the whole of it, with FRAME-ART.md and MARKER-ART.md for the drawing. Two links to each, because they answer different questions:

• in the checkout this is cloned into - WRITING-A-THEME.md, FRAME-ART.md, MARKER-ART.md. These describe the core you are actually running.
• on the web - WRITING-A-THEME.md, FRAME-ART.md, MARKER-ART.md. These are current, which is not the same thing.