Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

Position and size

Widgets have to look right on a 13-inch laptop, a 27-inch 5K display and everything in between. So Atsurae never uses pixels or points. Every size and distance in widget.json is a fraction of the screen height.

A size of 0.1 means one tenth of the screen’s height.

Value On a 1080-point-tall screen Feels like
0.01 ~11 points fine print
0.016 ~17 points a caption, the built-in Date
0.03 ~32 points a heading
0.05 ~54 points the built-in Day
0.16 ~173 points a huge clock

The same unit is used for:

  • font.size: the text’s size (roughly the height of a capital letter plus a bit)
  • size: [width, height] of images, shapes and progress bars
  • offset: [x, y]
  • cornerRadius, strokeWidth and lineWidth

Width uses the screen height too, so [0.1, 0.1] is always a square, even on an ultrawide display.

You don’t choose where your widget sits on the screen; the person using it does. In Customize Widgets they drag it to a spot, and Atsurae stores that spot as an anchor point: a position given as fractions of the screen’s width and height, so it stays in the same place if the resolution changes.

Each placement also has:

  • Size: a multiplier from 0.25× to 3× applied to every size and offset in your widget, so the whole widget scales together
  • Color: replaces the color of text and progress bars, and the tint of tinted images (Color)
  • Option values: whatever your options let people choose

A new widget starts at the center of the screen.

Every element is positioned relative to the widget’s anchor point:

offset [-0.1, -0.05]
●
anchor ✛ (where the widget was placed)
● offset [0.1, 0.05]
  • offset: [x, y] moves the element from the anchor. Positive x is right, positive y is down. Leave it out for [0, 0].
  • Vertically, an element is always centered on its offset point.
  • Horizontally, alignment decides which part of the element sits on the offset point:
    • "center" (default): the element’s middle
    • "leading": its left edge
    • "trailing": its right edge

So a two-column layout puts labels on the left with "alignment": "leading" and values on the right with "alignment": "trailing":

{ "text": "LONDON", "alignment": "leading", "offset": [-0.13, 0] },
{ "text": "20:18", "alignment": "trailing", "offset": [ 0.13, 0] }

Both columns line up neatly however long the text is. The World Clock example works this way.

Because people place widgets by dragging the anchor, put the anchor somewhere that makes sense:

  • A single line or block: center everything on the anchor (all offsets near [0, 0]). Snapping to the screen’s center then centers your widget.
  • A stack: put the most important element on the anchor and stack others above and below it.
  • A card: put the card’s background shape at [0, 0] and lay the contents out inside it.

Elements are drawn in the order they’re listed. Later elements are drawn on top. Put background shapes first.

Widgets appear on the main display (the one with the menu bar in System Settings ▸ Displays). Positions are fractions of that display, so they survive resolution changes and switching between the built-in screen and an external one.