Widgets

A widget is a card on the desk: the time, the system, the network, what is playing, drawn by Stillward Display from a short JSON file. Nothing in the file runs. It names what to show from a list the program keeps, and what a button does from another.

In the program

On the Widgets page, Make a widget opens the studio on an empty card. Add items from the list on the left, drag them into place and size them by their corner, and choose in the panel on the right what each shows. The card in the middle is the program's own drawing, the same one the desk will show; Try it on the desk puts it there with real numbers while the studio is open.

The file

A card of a size, its ground, and items drawn in order, the last on top. Sizes and places are in points at 100%; on a monitor at 150% the card is drawn again at that scale, never stretched.

{
  "$schema": "https://stillwarddisplay.com/schema/widget.json",
  "version": 1,
  "name": "Clock",
  "size": [344, 164],
  "ground": {
    "fill": "steel:4",
    "fill2": "steel:5",
    "opacity": 1,
    "radius": 22,
    "edge": true
  },
  "items": [
    {
      "at": [18, 22],
      "size": [310, 84],
      "colour": "ink",
      "opacity": 1,
      "radius": 0,
      "type": "text",
      "text": "{time}",
      "font": 74,
      "weight": 600,
      "align": "start"
    },
    {
      "at": [22, 114],
      "size": [306, 26],
      "colour": "ink-2",
      "opacity": 1,
      "radius": 0,
      "type": "text",
      "text": "{weekday}, {date.long}",
      "font": 16,
      "weight": 500,
      "align": "start"
    }
  ]
}

The widgets drawn for the program come in three sizes: a square of 164 points, a wide card of 344 × 164, and a strip of 344 × 76. A card of one of those sizes sits well beside them.

• size: from 40 to 1200 points a side. Every item is moved and cut to stay on the card, and on a card with rounded corners it is drawn inside them.
• ground: fill, and fill2 for a ground that fades to a second colour from top to bottom; opacity, radius, and edge for a hairline of light just inside the rim.
• Items: text, bar, ring, graph, glyph, image, button, desks, rect, clock, calendar, cover, spectrum. At most 64. An item of a kind this version does not know is left out, not the file, so a widget made for a newer version still shows what this one can draw.
• text: words up to 200 characters, 6 to 160 points, with weight and align. Words, with any of these in braces for what the program knows: {time}, {time.seconds}, {time.h}, {time.m}, {ampm}, {date}, {date.long}, {date.monthday}, {weekday}, {weekday.short}, {day}, {month}, {month.short}, {year}, {cpu}, {ram}, {ram.used}, {ram.total}, {gpu}, {net.down}, {net.up}, {battery}, {battery.state}, {uptime}, {media.title}, {media.artist}, {media.position}, {media.length}, {media.progress}, {volume}, {desk}, {desk.number}, {desk.count}, {preset}, {timer}, {rec.time}, {game.time}, {download}, {download.percent}, {download.progress}, {call.app}, {output}, {headset.battery}, {shelf}, {agent.state}, {agent.project}, {agent.say}, {agent.allow}, {agent.deny}; {disk.c}, {disk.c.free} for any drive letter; and {time@Tokyo Standard Time}, {offset@Tokyo Standard Time} for the time in a zone, by Windows' own id, and how far it is from yours.
• bar, ring and graph show a number: cpu, ram, gpu, battery, volume, net.down, net.up, media.progress, download.progress. A graph shows the last seconds of it.
• glyph: one of Windows' own icons by name: play, pause, stop, previous, next, volume, mute, clock, calendar, wifi, download, upload, battery, monitor, settings, home, star, music, video, game, sun, cloud, search, folder, mail, person, pin, stopwatch, chart, desks, power, heart, switch, terminal, back, forward.
• image: a PNG or SVG in the same folder. The program decodes it itself, checking its size first; a drawing cannot reach a font, another file or the network.
• button: does one of media.toggle, media.next, media.previous, volume.mute, volume.up, volume.down, find-pointer, open, desk:N (go to virtual desktop N) or preset:N (run the preset at that place in the list), with a glyph or a text.
• desks: a dot for each virtual desktop, the current one drawn longer.
• clock: a clock with hands, in the computer's own time zone or in another by Windows' own id (zone, the names tzutil /l lists). face is ticks, numbers, dots or bare; dial is the face's colour or none; hand is the second hand's colour, and seconds turns it off.
• calendar: this month, its weeks starting on the day set in Windows, with today ringed in today.
• cover: the cover of what is playing, filling its box with its corners rounded by radius; a note where the player gives none.
• Buttons that play, pause and skip draw solid shapes; play turns to pause while something plays. bare draws a button without the pad under it.
• Colours are words: ink and ink-2 (the card's text, light on a dark card and dark on a light one), steel:1 to steel:5, accent:1 to accent:5 (the person's Windows accent), or #rrggbb. Any of them takes /0.5 to be see-through.

The schema is at /schema/widget.json; an editor that knows JSON Schema offers every field as you type.

What a widget cannot do

It cannot run anything, open a file outside its folder, reach the network or read the screen. It shows only what Windows tells any program: the time, how busy the processor, memory and graphics are, the disks, the network's speed, the battery, the volume, what the media controls say is playing, the virtual desktops and the preset Stillward is running. No temperatures and no frame rates: both would need a driver or a hook into another program, and Stillward uses neither.

Checking a widget

stillward-display.exe --check mine.widget.json says whether the program would take it, what it left out, every number it brought into range, which pictures it found beside the file, and whether its Workshop card can carry the widget itself. Nothing of the program starts.

Importing and publishing

On the Widgets page, Import takes a .widget.json with its pictures beside it, or a .zip of the same. Your own widgets have Publish; the Workshop's card for a widget carries the file itself, so other people see it drawn before they add it.