PiClock3 Layout Template

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

It runs as it stands: conditions and two radars down the left, a square clock in the middle, nine forecast cells down the right. Move the rectangles and it is yours.

That is examples/wireframe.yaml, which draws nothing but the region names. Run it whenever you move something: a shape is hard to check by reading numbers and obvious to check by looking.

Try it first

From the top of a PiClock3 checkout:

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

That is a whole clock standing on the layout, and it needs no API key. examples/wireframe.yaml is the picture above. Both are carried here, which is the quickest way to let somebody see a layout without writing a config of their own. Name yours in a config of your own the same way:

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

layout: is the folder it was cloned into. Two layouts both called tall are told apart by renaming a directory.

What a layout is

Named rectangles, and nothing else. No colors, no fonts, no art - a theme says all of that. Keeping that line clean is what lets any theme work with any layout.

Every number is a fraction of the screen, so one file serves a 1280x720 panel and a 1080p monitor alike.

clock: {width: 0.42, aspect: 1.0,
        horizontal-center: 0.0, vertical-center: 0.0}

Give an edge and a size - left with width, top or bottom with height. Give both edges and no size and the region is whatever lies between them, which is what the date strip wants so it stays clear of the columns either side. aspect is measured off the width, so on 16:9 a region 0.42 wide is already three-quarters of the height. The two centers are offsets from the middle of the page.

What is in here

layout.yaml                the whole layout
examples/example.yaml      a clock standing on it, run by naming it
examples/wireframe.yaml    the region names and nothing else
screenshot.png             what it looks like, shown above
README.md                  and a license

A layout has no art, so it is usually one file. A folder is what a git checkout looks like, and layouts/tall/layout.yaml and layouts/tall/tall.yaml both work.

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

repeat

repeat divides one region into cells named maps.1 and maps.2:

maps: {left: 0.0, top: 0.33, width: 0.25, height: 0.67,
       border: radar, repeat: {count: 2, direction: down}}

A widget takes one cell, or takes the bare name and fills every cell - which is how one forecast entry fills nine of them. That difference is real: two radars are two separate settings, while a forecast is one dataset drawn as a series.

direction is down or across, and gap is a fraction of the span left between cells.

border

border: true asks the theme for its default frame; border: radar asks for one by name. A theme with no such name falls back to its default, so a layout never has to know which themes exist. No border key, no frame.

style

A region can name a set of Qt stylesheet properties, and both files have a say in what the name means:

date: {left: 0.25, right: 0.25, top: 0.0, height: 0.11, style: date}

layout-style-settings:
  date:
    font-size: 0
    qproperty-alignment: AlignCenter

Carry the sizing here. How big text has to be to fit a region is the layout's business, and it is what lets yours look right under a theme that has never heard of it. A theme's own styles: of the same name wins.

font-size: 0 means as large as fits. A bare number is a fraction of the region's height; one with units, 20px, is used as written.

designed-for

Fractions carry a layout across resolutions, but not across shapes.

designed-for: '16:9'

With that, core corrects each region's width in proportion to how far the screen departs from the shape you drew on, so a region keeps its shape instead of being stretched into a slot nothing fits in. Quote it - yaml reads a bare 16:9 as sexagesimal. Leave it out and nothing is corrected.

It softens the change of shape; it does not undo it. Only widths are corrected, and each one on its own, so regions that just cleared each other at the shape you drew on can still meet at another - the shipped classic does it too. A layout is allowed to be drawn for one screen and say which.

Use the conventional names

Unlike a theme, a layout is not freely swappable. A config names the region each widget draws in, so if your names differ from the ones somebody already has, their config points at regions that no longer exist.

Sticking to clock, date, bottom, current, maps and forecast makes yours drop-in. Inventing left-column is allowed and sometimes right - just know it costs the user an edit, and say so in your README.

Before you publish

• Replace screenshot.png with yours. A layout is a shape, and describing a shape in words does not work
• python3 PyQtPiClock3.py layouts/example/examples/example.yaml --check
• See it at another shape. --geometry 800x600 needs no second screen, and the wireframe shows in one glance what happens there. Decide what you will accept, then say so
• Try it under a theme you did not draw it against, since that is the promise
• Name the themes you did draw it against, in description: and here
• Add the topic piclock3-layout to your repository so people can find it

The long form

WRITING-A-LAYOUT.md is the whole of it, and WRITING-A-CONFIG.md is the far end - how somebody puts a widget in a region you named. Two links to each, because they answer different questions:

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