Widgets!

Pixlet comes with a number of built-in Widgets. These are used to describe how data should be laid out, presented and finally rendered to an image file.

The easiest way to get started is probably to take a look at some of the examples, and then refer to the detailed Widget documentation (this document) when the need arises.

A quick note about colors. When specifying colors, use a CSS-like hexdecimal color specification. Pixlet supports "#rgb", "#rrggbb", "#rgba", and "#rrggbbaa" color specifications.

For animated widgets like Marquee, you can also call frame_count() to work out how many frames are required to display the whole animation. You can also call size() on dynamically-sized widgets like Text to get the width and height.

Animation

Animations turns a list of children into an animation, where each child is a frame.

FIXME: Behaviour when children themselves are animated is a bit weird. Think and fix.

Attributes

Name	Type	Description	Required
`children`	`[Widget]`	Children to use as frames in the animation	N

Example

render.Animation(
     children=[
          render.Box(width=10, height=10, color="#300"),
          render.Box(width=12, height=12, color="#500"),
          render.Box(width=14, height=14, color="#700"),
          render.Box(width=16, height=16, color="#900"),
          render.Box(width=18, height=18, color="#b00"),
     ],
)

Box

A Box is a rectangular widget that can hold a child widget.

Boxes are transparent unless color is provided. They expand to fill all available space, unless width and/or height is provided. Boxes can have a child, which will be centered in the box, and the child can be padded (via padding).

Attributes

Name	Type	Description	Required
`child`	`Widget`	Child to center inside box	N
`width`	`int`	Limits Box width	N
`height`	`int`	Limits Box height	N
`padding`	`int`	Padding around the child widget	N
`color`	`color`	Background color	N

Example

render.Box(
     color="#00f",
     child=render.Box(
          width=20,
          height=10,
          color="#f00",
     )
)

Circle

Circle draws a circle with the given diameter and color. If a child widget is provided, it is drawn in the center of the circle.

Attributes

Name	Type	Description	Required
`color`	`color`	Fill color	Y
`diameter`	`int`	Diameter of the circle	Y
`child`	`Widget`	Widget to place in the center of the circle	N

Example

render.Circle(
     color="#666",
     diameter=30,
     child=render.Circle(color="#0ff", diameter=10),
)

Column

Column lays out and draws its children vertically (in a column).

By default, a Column is as small as possible, while still holding all its children. However, if expanded is set, the Column will fill all available space vertically. The width of a Column is always that of its widest child.

Alignment along the vertical main axis is controlled by passing one of the following main_align values:

"start": place children at the beginning of the column
"end": place children at the end of the column
"center": place children in the middle of the column
"space_between": place equal space between children
"space_evenly": equal space between children and before/after first/last child
"space_around": equal space between children, and half of that before/after first/last child

Alignment along the horizontal cross axis is controlled by passing one of the following cross_align values:

"start": place children at the left
"end": place children at the right
"center": place children in the center

Attributes

Name	Type	Description	Required
`children`	`[Widget]`	Child widgets to lay out	Y
`main_align`	`str`	Alignment along vertical main axis	N
`cross_align`	`str`	Alignment along horizontal cross axis	N
`expanded`	`bool`	Column should expand to fill all available vertical space	N

Example

render.Column(
     children=[
          render.Box(width=10, height=8, color="#a00"),
          render.Box(width=14, height=6, color="#0a0"),
          render.Box(width=16, height=4, color="#00a"),
     ],
)

Example

render.Column(
     expanded=True,
     main_align="space_around",
     cross_align="center",
     children=[
          render.Box(width=10, height=8, color="#a00"),
          render.Box(width=14, height=6, color="#0a0"),
          render.Box(width=16, height=4, color="#00a"),
     ],
)

Image

Image renders the binary image data passed via src. Supported formats include PNG, JPEG, GIF, and SVG.

If width or height are set, the image will be scaled accordingly, with nearest neighbor interpolation. Otherwise the image's original dimensions are used.

If the image data encodes an animated GIF, the Image instance will also be animated. Frame delay (in milliseconds) can be read from the delay attribute.

Attributes

Name	Type	Description	Required
`src`	`str`	Binary image data or SVG text	Y
`width`	`int`	Scale image to this width	N
`height`	`int`	Scale image to this height	N
`delay`	`int`	(Read-only) Frame delay in ms, for animated GIFs	N

Marquee

Marquee scrolls its child horizontally or vertically.

The scroll_direction will be 'horizontal' and will scroll from right to left if left empty, if specified as 'vertical' the Marquee will scroll from bottom to top.

In horizontal mode the height of the Marquee will be that of its child, but its width must be specified explicitly. In vertical mode the width will be that of its child but the height must be specified explicitly.

If the child's width fits fully, it will not scroll.

The offset_start and offset_end parameters control the position of the child in the beginning and the end of the animation.

Alignment for a child that fits fully along the horizontal/vertical axis is controlled by passing one of the following align values:

"start": place child at the left/top
"end": place child at the right/bottom
"center": place child at the center

Attributes

Name	Type	Description	Required
`child`	`Widget`	Widget to potentially scroll	Y
`width`	`int`	Width of the Marquee, required for horizontal	N
`height`	`int`	Height of the Marquee, required for vertical	N
`offset_start`	`int`	Position of child at beginning of animation	N
`offset_end`	`int`	Position of child at end of animation	N
`scroll_direction`	`str`	Direction to scroll, 'vertical' or 'horizontal', default is horizontal	N
`align`	`str`	Alignment when contents fit on screen, 'start', 'center' or 'end', default is start	N
`delay`	`int`	Delay the scroll of the animation by a certain number of frames, default is 0	N

Example

render.Marquee(
     width=64,
     child=render.Text("this won't fit in 64 pixels"),
     offset_start=5,
     offset_end=32,
)

Padding

Padding places padding around its child.

If the pad attribute is a single integer, that amount of padding will be placed on all sides of the child. If it's a 4-tuple (left, top, right, bottom), then padding will be placed on the sides accordingly.

Attributes

Name	Type	Description	Required
`child`	`Widget`	The Widget to place padding around	Y
`pad`	`int / (int, int, int, int)`	Padding around the child	N
`expanded`	`bool`	This is a confusing parameter	N
`color`	`color`	Background color	N

PieChart

PieChart draws a circular pie chart of size diameter. It takes two arguments for the data: parallel lists colors and weights representing the shading and relative sizes of each data entry.

Attributes

Name	Type	Description	Required
`colors`	`[color]`	List of color hex codes	Y
`weights`	`[float]`	List of numbers corresponding to the relative size of each color	Y
`diameter`	`int`	Diameter of the circle	Y

Example

render.PieChart(
     colors = [ "#fff", "#0f0", "#00f" ],
     weights  = [ 180, 135, 45 ],
     diameter = 30,
)

Plot

Plot is a widget that draws a data series.

Attributes

Name	Type	Description	Required
`data`	`[(float, float)]`	A list of 2-tuples of numbers	Y
`width`	`int`	Limits Plot width	Y
`height`	`int`	Limits Plot height	Y
`color`	`color`	Line color, default is '#fff'	N
`color_inverted`	`color`	Line color for Y-values below 0	N
`x_lim`	`(float, float)`	Limit X-axis to a range	N
`y_lim`	`(float, float)`	Limit Y-axis to a range	N
`fill`	`bool`	Paint surface between line and X-axis	N
`chart_type`	`str`	Specifies the type of chart to render, "scatter" or "line", default is "line"	N
`fill_color`	`color`	Fill color for Y-values above 0	N
`fill_color_inverted`	`color`	Fill color for Y-values below 0	N

Example

render.Plot(
  data = [
    (0, 3.35),
    (1, 2.15),
    (2, 2.37),
    (3, -0.31),
    (4, -3.53),
    (5, 1.31),
    (6, -1.3),
    (7, 4.60),
    (8, 3.33),
    (9, 5.92),
  ],
  width = 64,
  height = 32,
  color = "#0f0",
  color_inverted = "#f00",
  x_lim = (0, 9),
  y_lim = (-5, 7),
  fill = True,
),

Root

Every Widget tree has a Root.

The child widget, and all its descendants, will be drawn on a 64x32 canvas. Root places its child in the upper left corner of the canvas.

If the tree contains animated widgets, the resulting animation will run with delay milliseconds per frame.

If the tree holds time sensitive information which must never be displayed past a certain point in time, pass MaxAge to specify an expiration time in seconds. Display devices use this to avoid displaying stale data in the event of e.g. connectivity issues.

Attributes

Name	Type	Description	Required
`child`	`Widget`	Widget to render	Y
`delay`	`int`	Frame delay in milliseconds	N
`max_age`	`int`	Expiration time in seconds	N
`show_full_animation`	`bool`	Request animation is shown in full, regardless of app cycle speed	N

Row

Row lays out and draws its children horizontally (in a row).

By default, a Row is as small as possible, while still holding all its children. However, if expanded is set, the Row will fill all available space horizontally. The height of a Row is always that of its tallest child.

Alignment along the horizontal main axis is controlled by passing one of the following main_align values:

"start": place children at the beginning of the row
"end": place children at the end of the row
"center": place children in the middle of the row
"space_between": place equal space between children
"space_evenly": equal space between children and before/after first/last child
"space_around": equal space between children, and half of that before/after first/last child

Alignment along the vertical cross axis is controlled by passing one of the following cross_align values:

"start": place children at the top
"end": place children at the bottom
"center": place children at the center

Attributes

Name	Type	Description	Required
`children`	`[Widget]`	Child widgets to lay out	Y
`main_align`	`str`	Alignment along horizontal main axis	N
`cross_align`	`str`	Alignment along vertical cross axis	N
`expanded`	`bool`	Row should expand to fill all available horizontal space	N

Example

render.Row(
     children=[
          render.Box(width=10, height=8, color="#a00"),
          render.Box(width=14, height=6, color="#0a0"),
          render.Box(width=16, height=4, color="#00a"),
     ],
)

Example

render.Row(
     expanded=True,
     main_align="space_between",
     cross_align="end",
     children=[
          render.Box(width=10, height=8, color="#a00"),
          render.Box(width=14, height=6, color="#0a0"),
          render.Box(width=16, height=4, color="#00a"),
     ],
)

Sequence

Sequence renders a list of child widgets in sequence.

Each child widget is rendered for the duration of its frame count, then the next child wiget in the list will be rendered and so on.

It comes in quite useful when chaining animations. If you want to know more about that, go check out the animation documentation.

Attributes

Name	Type	Description	Required
`children`	`[Widget]`	List of child widgets	Y

Example

render.Sequence(
  children = [
    animation.Transformation(...),
    animation.Transformation(...),
    ...
  ],
),

Stack

Stack draws its children on top of each other.

Just like a stack of pancakes, except with Widgets instead of pancakes. The Stack will be given a width and height sufficient to fit all its children.

Attributes

Name	Type	Description	Required
`children`	`[Widget]`	Widgets to stack	Y

Example

render.Stack(
     children=[
          render.Box(width=50, height=25, color="#911"),
          render.Text("hello there"),
          render.Box(width=4, height=32, color="#119"),
     ],
)

Text

Text draws a string of text on a single line.

By default, the text will use the "tb-8" font, but other fonts can be chosen via the font attribute. The height and offset parameters allow fine tuning of the vertical layout of the string. Take a look at the font documentation for more information.

Attributes

Name	Type	Description	Required
`content`	`str`	The text string to draw	Y
`font`	`str`	Desired font face	N
`height`	`int`	Limits height of the area on which text is drawn	N
`offset`	`int`	Shifts position of text vertically.	N
`color`	`color`	Desired font color	N

Example

render.Text(content="Tidbyt!", color="#099")

WrappedText

WrappedText draws multi-line text.

The optional width and height parameters limit the drawing area. If not set, WrappedText will use as much vertical and horizontal space as possible to fit the text.

Alignment of the text is controlled by passing one of the following align values:

"left": align text to the left
"center": align text in the center
"right": align text to the right

Attributes

Name	Type	Description	Required
`content`	`str`	The text string to draw	Y
`font`	`str`	Desired font face	N
`height`	`int`	Limits height of the area on which text may be drawn	N
`width`	`int`	Limits width of the area on which text may be drawn	N
`linespacing`	`int`	Controls spacing between lines	N
`color`	`color`	Desired font color	N
`align`	`str`	Text Alignment	N

Example

render.WrappedText(
      content="this is a multi-line text string",
      width=50,
      color="#fa0",
)

Files

widgets.md

Latest commit

History

widgets.md

File metadata and controls

Widgets!

Animation

Attributes

Example

Box

Attributes

Example

Circle

Attributes

Example

Column

Attributes

Example

Example

Image

Attributes

Marquee

Attributes

Example

Padding

Attributes

PieChart

Attributes

Example

Plot

Attributes

Example

Root

Attributes

Row

Attributes

Example

Example

Sequence

Attributes

Example

Stack

Attributes

Example

Text

Attributes

Example

WrappedText

Attributes

Example