Playout

UI library and box model for Playdate

Support this project on Itch.io 🕹

Installation

If you are using toybox, you can run

toybox add potch/playout

Otherwise the library is a single file you can clone/copy into your project.

Demo

If you'd like to run the demo, you'll need the Playdate SDK. Then run:

pdc demo

and open the resulting packaged in the Playdate Simulator.

If you want to develop/experiment on the library or demo and you have node installed you can run the following:

npm install
npm start

Which will build and launch the demo, and re-build after any changes.

API Docs

playout.box

Box-based layout element. supports 1-dimensional layout (horizontal or vertical) with 2-dimensional alignment and flexible sizing.

Methods

playout.box.new(properties, [children])

Creates a new playout.box. Takes a table of properties and a list of children.

Children can be other boxes, images, or text.

Returns a playout.box.

Supported properties:

property	description	default value
backgroundAlpha	opacity of box fill, drawn as a dither pattern.	0 (full)
backgroundColor	color to fill the box when drawing	nil (transparent)
border	thickness of border on box	0
borderColor	color of border (if > 0)	playdate.graphics.kColorBlack
borderRadius	corner radius to use when drawing the box	0
direction	direction of layout. can be horizontal (children will be in a row) or vertical (children will be in a column)	playout.kDirectionVertical
flex	if set (non-zero), box will grow proporitonally to fill extra layout space in its parent.	nil
font	font to use when drawing text in children.	nil (default)
fontFamily	font family to use when drawing text in children. takes precedence over font, and allows for rich formatting.	nil
hAlign	how to horizontally align children. see Alignment	playout.kAlignCenter
height	height of the box. if not specified, box will be the height of its contents plus padding, spacing, etc. (but no larger than maxHeight)	nil
id	unique string used for lookups via playout.tree.get	nil
maxHeight	maximum height of the box	240
maxWidth	maximum width of the box	400
minHeight	minimum height of the box	1
minWidth	minimum width of the box	1
padding	amount of inset, in pixels, between box children and the edge	0
paddingBottom	bottom padding. defaults to paddingTop or padding value if provided, in that order	nil
paddingLeft	left padding. defaults to padding value if provided, in that order	nil
paddingRight	right padding. defaults to paddingLeft or padding value if provided, in that order	nil
paddingTop	top padding. defaults to padding value if provided	nil
selfAlign	override the box alignment from that provided by its parent. if parent's direction is horizontal, affects vertical alignment, if vertical, affects horizontal alignment	nil (no override)
shadow	size of shadow in pixels to draw under the box. note the shadow subtracts from the overall available height of the box	nil (no shaow)
shadowAlpha	how "dark" the shadow is, from 0..1. drawn using dither.	0 (full opacity)
spacing	how much space should be between each child of the box	0
style	see Style Reuse	nill
tabIndex	defines position for sequential lookups by playout.tree.tabIndex.	nil
vAlign	how to vertically align children. see Alignment	playout.kAlignCenter
width	width of the box. if not specified, box will be the width of its contents plus padding, spacing, etc. (but no larger than maxWidth)	nil

playout.box:appendChild(child)

Add a child (text, image, or other box) to the box.

playout.box:insertChild(child, position)

Add a child (text, image, or other box) to the box at a specified position. e.g. insertChild(child, 1) would add the child as the first child.

playout.box:layout([context])

Computes the layout of the box and all children recursively. Returns a playout.geometry.rect with the computed size. Usually indirectly called by playout.tree:layout.

context is a table with the following properties:

property	description	default
maxWidth	maximum width the box can be, regardless of its contents	math.huge (no limit)
maxHeight	maximum height the box can be, regardless of its content	math.huge (no limit)

playout.box:draw(rect)

Draw the box and all its children using their visual properties in the current drawing context within the specified rect. Usually called indirectly by playout.tree.draw with pre-computed rects generated during :layout.

properties

playout.box.properties

table of properties, provided via initial creation.

playout.box.children

list of children, managed via appendChild, insertChild, or playout.tree.

playout.box.childRects

List of rects corresponding to children, determined during :layout. Will be nil if layout hasn't been called yet.

playout.box.parent

Reference to a parent box, if any. set by appendChild, insertChild, or playout.tree. If children were changed directly via .children, their parent will not be set. read only.

playout.box.style

see Style Reuse.

playout.text

Layout element for text content. supports fonts, outlines, and text wrapping.

methods

playout.text.new(text, [properties])

Creates a new playout.text. Takes a string of text and an optional table of properties.

Returns a playout.text

Supported properties:

property	description	default
font	which playdate.graphics.font to use to render text. this property can be inherited from parent boxes.	nil (currently set font),
fontFamily	which playdate.graphics.fontFamily to use to render text. allows for rich text formatting. If set, overrides font. this property can be inherited from parent boxes.	nil,
alignment	text alignment	kTextAlignment.left,
leading	leading adjusment	nil (none),
flex	if set (non-zero), text will grow proporitonally to fill extra layout space in its parent.	nil,
wrap	whether to line-wrap text	true,
stroke	radius of outline to render around the text- will be rendered in white. useful to contrast text against a background.	0,
color	color to render text- overrides font's natural color. playdate.graphics.kColorBlack or kColorWhite.	nil (use defualt font color)

playout.text:layout(context)

Computes the layout and dimensions of renderered text. Returns a playout.geometry.rect with the computed size. Usually indirectly called by playout.tree:layout.

playout.text:draw(rect)

Renders text into the provided playout.geometry.rect. Usually called indirectly by playout.tree:draw.

Properties

Changing properties will require re-running layout and draw to see the changes.

playout.text.text

Value of text string to render. changing this will likely require re-computing layout.

playout.text.properties

Table of properties, provided via initial creation.

playout.text.parent

Reference to a parent box, if any. set by appendChild, insertChild, or playout.tree. If children were changed directly via .children, their parent will not be set. read only.

playout.text.style

See Style Reuse.

playout.image

Allows for the incorporation of playdate.graphics.image into a layout.

Methods

playout.image.new(image, [properties])

Creates a new playout.image. Takes a playdate.graphics.image and an optional table of properties.

image nodes are sized to the width and height of their corresponding playdate.graphics.image, which is used in layout.

Returns a playout.image.

playout.text:layout(context)

Calculates a `play

playout.text:draw(rect)

Properties

playout.text.parent

Reference to a parent box, if any. set by appendChild, insertChild, or playout.tree. If children were changed directly via .children, their parent will not be set. Read only.

playout.tree

Structure for creating/accessing a tree of playout nodes. This is the recommended way to create, layout, and draw layouts.

Methods

playout.tree.new([root, [options])

Create a new playout.tree. Takes root, the top-level note of the tree (a box, text, or image), as well as a table of options.

Supported options:

option	description	default
useCache	Whether or not to cache nodes looked up using tree:get(id). Makes subsequent lookups faster.	true

playout.tree:layout()

Compute the layout of all children recursively, starting at root.

playout.tree.draw()

Returns a playdate.graphics.image containing the rendered tree. Will run tree:layout if it has not yet been run. To save on memory, this method will store and re-use the same image for subsequent re-renders (at tree.img), provided the computed layout dimensions of the tree haven't changed. Will automatically update an associated sprite if created with playout.tree:asSprite

playout.tree:asSprite()

Creates a new playdate.graphics.sprite, draws the tree into the sprite, and returns the sprite. Future calls to tree:draw will automatically update the sprite's image.

playout.tree:get(id)

Find a node in the tree based on its properties.id. Will recursively walk the tree to find the node. Returns the first node with matching id, or nil if no match was found. If tree.useCache is true, subsequent lookups will skip walking the tree.

playout.tree:computeTabIndex()

Computes a sequential list of nodes in the tree which have the tabIndex property set. Higher tabIndex values will be sorted later in the list. Useful for interactivity and menuing. The computed list will be store in the playout.tree.tabIndex property, which is nil until this method is called.

Properties

playout.tree.root

The top node of the layout tree.

playout.tree.tabIndex

An ordered list of nodes, sorted by their tabIndex property. Useful for interactivity and menuing. Will be nil until playout.tree:computeTabIndex() is called.

playout.tree.rect

A playdate.geometry.rect representing the dimensions of the tree after the last call to playout.tree:layout()

playout.tree.img

A playdate.graphics.image containing the latest results of calling playout.tree:draw()

playout.tree.sprite

A playout.graphics.sprite, populated after calling playout.tree:asSprite()

Utilities and Constants

Alignment

Used for hAlign and vAlign properties:

playout.kAlignStart

Children are aligned to the start of the box (left for hAlign, top for vAlign).

playout.kAlignCenter

Children are aligned to the center of the box (rounded down in the case of an odd width).

playout.kAlignEnd

Children are aligned to the end of the box (right for hAlign, bottom for vAlign).

playout.kAlignStretch

Resizes children to fill the available remaining space.

Only valid for off-axis alignment. If direction is vertical, valid for hAlign, if directon is horizontal, valid for vAlign. When used in selfAlign, always refers to the off-axis direction.

Anchoring

playout.getRectAnchor(r, anchor)

Returns a playdate.geometry.point for a given anchor position on the the provided playdate.geometry.rect:

playout.kAnchorTopLeft
playout.kAnchorTopCenter
playout.kAnchorTopRight
playout.kAnchorCenterLeft
playout.kAnchorCenter
playout.kAnchorCenterRight
playout.kAnchorBottomLeft
playout.kAnchorBottomCenter
playout.kAnchorBottomRight

Direction

Used for specifying the direction of box layout, horizontal or vertical:

playout.kDirectionVertical
playout.kDirectionHorizontal

Styling

All node types (box, image, and text) can take an optional style property. This is a table of properties that will override any properties provided at creation or default values. Can be used to define repeatable common collections of properties.

Example

local button = {
  padding = 4,
  border = 2,
  borderRadius = 4,
  shadow = 2
}

local options = playout.tree.new(
  playout.box.new({
    direction = playout.kDirectionHorizontal,
    spacing = 8
  }, {
    playout.box.new({ style = button, tabIndex = 1 }, { playout.text.new("Cancel") }),
    playout.box.new({ style = button, tabIndex = 2 }, { playout.text.new("Okay") }),
  })
)