khao (thai for "rice") is a layout library for LÖVE inspired by clay and HTML. It's designed to be as declarative and terse as possible within the syntax of Lua.

Place khao.lua in your project and use require whereever you need it.

local khao = require("khao") -- if khao.lua is in your root directory
local khao = require("path.to.khao") -- if it's in a subfolder

The Element class acts as the foundation of khao. To construct one, use the :from method or call the class directly, then pass a configuration table where its keys are properties of the element and its indices are child elements.

local Element = khao.Element
local Text = khao.Text

local thing = Element { 
    width = 150, 
    height = 100,
    align_x = "center",
    align_y = "center",

    Text {
        content = "Hello World!"
    }
}

We can then call the :calculate method that computes the dimensions and positions of each element, which then allows us to :draw our elements where ever we like.

thing:calculate()

function love.draw ()
    thing:draw(100, 100)
end

The base element class.

Constructs an Element from a given configuration table, its keys being properties and its indices being child elements. Can also be invoked by calling the Element class itself.

• width_sizing: "fixed"|"fit"|"grow" - The sizing behavior of the width. "fixed" by default.
• height_sizing: "fixed"|"fit"|"grow" - The sizing behavior of the height. "fixed" by default.
• width: number - If sizing is set to "fixed", the width in pixels. If sizing is set to "grow", the proportion of available width this element takes.
• height: number - If sizing is set to "fixed", the height in pixels. If sizing is set to "grow", the proportion of available height this element takes.
• min_width: number - The minimum width in pixels.
• max_width: number - The maximum width in pixels.
• min_height: number - The minimum height in pixels.
• max_height: number - The maximum height in pixels.
• align_x: "left"|"center"|"right" - The positioning of child elements along the x-axis. "left" by default.
• align_y: "top"|"center"|"bottom" - The positioning of child elements along the y-axis. "top" by default.
• direction: "row"|"column" - The direction child elements are drawn. "row" by default.
• padding: number - A shorthand for setting all padding values.
• padding_left: number - The amount of pixels between the child elements and the left edge.
• padding_right: number - The amount of pixels between the child elements and the right edge.
• padding_top: number - The amount of pixels between the child elements and the top edge.
• padding_bottom: number - The amount of pixels between the child elements and the bottom edge.
• gap: number - The amount of pixels between each child element.
• name: string - Just a string, mainly intended for drawing/debugging.
• color: [number, number, number, number] - A table of RGBA values, intended for love.graphics.setColor.
• on_update: function (self, dt: number) - A callback fired when the root element calls :update.
• on_draw: function (self, x: number, y: number) - A callback fired when the root element calls :draw
• post_draw: function (self, x: number, y: number) - A callback fired after child elements have been drawn.

Instances of Element have the following fields upon creation along with the ones listed above. These should be treated as read-only.

• parent: Element? - The parent element. nil if it is a root element.
• x: number - The x position relative to its parent.
• y: number - The y position relative to its parent.
• w: number - The calculated width.
• h: number - The calculated height.

Adds child elements to the end of the list of children. Configuration tables can be inputed which get instantiated as the type of the element.

Returns a class that extends the Element class. If false is inputed, it prevents this type from having child elements.

An abstract method called whenever elements are instantiated. Intended for subclasses to override with custom initialization.

Calculates the dimensions and positions of the element and its descendents. This should be called after initialization and whenever changes are made an element's properties so it and its descendents' x, y, w, and h fields are updated.

The default callback fired by :calculate and called if an element instance doesn't have an calculate callback, intended to be overriden by subclasses for custom sizing calculations.

Calls the element's and its descendents' :on_update callbacks.

The default callback fired by :update and called if an element instance doesn't have an on_update callback, intended to be overriden by subclasses. This is called before its child elements.

Calls the element's and its descendents :on_draw and :post_draw callbacks.

The default callback fired by :draw and called if an element instance doesn't have an on_draw callback, intended to be overriden by subclasses. This is called before its child elements are drawn.

The default callback fired by :draw and called if an element instance doesn't have an post_draw callback, intended to be overriden by subclasses. This is called after its child elements are drawn.

Returns the elements computed width and height.

A subclass of Element with some basic handling for text. Text elements have their sizing permanently set to "grow" so that their text can wrap.

• content: string - The text to display.
• font: love.Font - The Font object to use. Default value is whatever love.graphics.getFont returns.

A subclass of Element for drawing images.

• image: love.Image - The Image object to use.
• path: string - The path to the image, used only if no Image object is given.
• settings: { mipmaps: boolean, linear: boolean, dpiscale: number } - The settings for the image, used only if no Image object is given.
• quad: love.Quad - The Quad object to use. By default, a quad of the entire image is used.
• angle: number - The image's angle of rotation.
• skew_x: number - The image's horizontal skew factor.
• skew_y: number - The image's vertical skew factor.
• scale_x: number - The image's horizontal scale factor.
• scale_y: number - The image's vertical scale factor.
• offset_x: number - The image's offset along the x-axis.
• offset_y: number - The image's offset along the y-axis.

After construction, Images get the following fields. These are intended to use for scaling the image to the computed dimensions.

• sx: number - The computed horizontal scale factor for setting the image's width to the element's w.
• sy: number - The computed vertical scale factor for setting the image's height to the element's h.

A subclass of Element for transforming it and its child element's draw calls.

• angle: number - The element's angle of rotation.
• skew_x: number - The element's horizontal skew factor.
• skew_y: number - The element's vertical skew factor.
• scale_x: number - The element's horizontal scale factor.
• scale_y: number - The element's vertical scale factor.
• origin_x: number - The element's origin offset along the x-axis.
• origin_y: number - The element's origin offset along the y-axis.

After construction, Transform instances keep a LÖVE Transform object.

• transform: love.Transform - The Transform object applied before :on_draw and updated after :on_update is called.