API Reference

What follows is an API reference. If you’d like a more hands-on tutorial, have a look at stretchable by Example.

Nodes

class stretchable.Node(*children: Node, key: str = None, measure: Callable[[Node, SizePoints, SizeAvailableSpace], SizePoints] = None, style: Style = None, **kwargs)

A node in a layout.

Parameters:

• *children (Node) – Any child nodes to add to this node, optional

• key (str, default: None) – Node identifier that can be used to locate the node in the node tree, optional

• measure (Callable[[Node, SizePoints, SizeAvailableSpace], SizePoints], default: None) – A method that is able to measure and return the size of the node during computation of layout, optional

• style (Style, default: None) – The style to apply to the node, optional

• **kwargs – If the style parameter is not provided, any additional keyword arguments are passed to a new instance of Style which is assigned to this node, optional

add(*children: Node) → Node

Add one or more child nodes and return the node itself (enables chaining of node instantiation, see Building Node Trees).

Return type:

Node

Parameters:

children (Node)

compute_layout(available_space: SizeAvailableSpace | tuple[float, float] | None = None, *, use_rounding: bool = False) → bool

Computes the layout for this node and any child nodes.

Parameters:

• available_space (Union[SizeAvailableSpace, tuple[float, float], None], default: None) – The available space for the layout. It may be provided as SizeAvailableSpace, as a tuple of width and height, or omitted

• use_rounding (bool, default: False) – If True, all positions and dimensions will be rounded to integers.

Return type:

True if layout was computed successfully, False otherwise.

Notes

Depending on the nodes, the resulting layout may extend outside available_space.

find(address: str) → Node

Returns the node at the specified address.

Node addresses use a syntax similar to file paths, eg. a leading / starts from the root of the node tree, ./ indicates the current location and ../ steps up a level.

Nodes can be identified either by the Node.key (optional), or the 0-based node index.

See Locating Nodes for some examples of how to locate nodes using this method.

Parameters:

address (str) – The address of the node to find

Return type:

Node

get_box(edge: Edge = Edge.BORDER, *, relative: bool = True, flip_y: bool = False) → Box

Get the computed layout (position and size) for the node.

See CSS box model for more information.

Parameters:

• edge (Edge, default: <Edge.BORDER: 'border'>) – The edge for which to get the corresponding Box

• relative (bool, default: True) – Determines if returned position is relative to parent (if True) or relative to the root (if False)

• flip_y (bool, default: False) – Determines if the vertical position (y) is measured from the top (if False), or from the bottom (if True)

Return type:

The Box corresponding to the provided arguments

mark_dirty()

Marks this node as dirty meaning that the layout needs to be recomputed.

property address: str

The address of this node, relative to the root node.

property is_dirty: bool

True if the layout needs to be (re)computed to get the layout of this node, False otherwise.

property is_root: bool

True if this node is the root node, False otherwise.

property key: str | None

Node identifier.

property parent: Node | None

The parent Node of this node, or None if it does not have a parent node.

property root: Node

The root Node of the node tree with which this node is associated.

class stretchable.Box(x: float, y: float, width: float, height: float) → None

Represents a rectangle with a position and size.

Parameters:

• x (float) – The horizontal position of the left edge of the box

• y (float) – The vertical position of the top (default) or bottom (if using flip_y = True in Node.get_box()) edge of the box

• width (float) – The width of the box

• height (float) – The height of the box

enum stretchable.Edge

Describes which edge of a node a given Box corresponds to. See the Glossary for a description of the box model and the different boxes.

Members:

CONTENT PADDING BORDER MARGIN

Styles

class stretchable.Style(**kwargs)

All Style properties listed below can also be passed as keyword arguments when creating a new instance.

Note

The Style class is immutable. To change the style of a node, assign a new Style instance.

property display: Display

Used to control node visibility and layout strategy.

property overflow_x: Overflow

Controls the desired behavior when content does not fit horizontally inside the parent node.

property overflow_y: Overflow

Controls the desired behavior when content does not fit vertically inside the parent node.

property scrollbar_width: float

How much space (in points) should be reserved for the scrollbars of Overflow.SCROLL nodes.

property position: Position

The positioning strategy for this node.

property align_items: AlignItems

Used to control how child nodes are aligned.

property justify_items: JustifyItems

Used to control how child nodes are aligned.

property align_self: AlignSelf

Used to control how the node is aligned.

property justify_self: JustifySelf

Used to control how the node is aligned.

property align_content: AlignContent

Sets the distribution of space between and around content items.

property justify_content: JustifyContent

Sets the distribution of space between and around content items.

property gap: SizePointsPercent

Sets the gaps (gutters) between rows and columns in a grid layout (default: 0.0).

property padding: RectPointsPercent

Sets the padding area between the content edge and the padding edge (default: 0.0).

property border: RectPointsPercent

Sets the border area between the padding edge and the border edge (default: 0.0).

property margin: RectPointsPercentAuto

Sets the margin area between the border edge and the margin edge (default: 0.0).

property size: SizePointsPercentAuto

Sets the desired width and height of the border box (default: AUTO).

property min_size: SizePointsPercentAuto

Sets the minimum width and height of the border box (default: AUTO).

property max_size: SizePointsPercentAuto

Sets the maximum width and height of the border box (default: AUTO).

property aspect_ratio: float

Sets the desired width-to-height of the border box (default: None).

property flex_wrap: FlexWrap

Sets whether flex items are forced onto one line or can wrap onto multiple lines. If wrapping is allowed, it sets the direction that lines are stacked (default: NO_WRAP).

property flex_direction: FlexDirection

Sets how flex items are placed in the flex container defining the main axis and the direction (normal or reversed) (default: ROW).

property flex_grow: float

Sets the flex grow factor, which specifies how much of the flex container’s remaining space should be assigned to the flex item’s main size. (default: 0.0).

property flex_shrink: float

Sets the flex shrink factor of a flex item. If the size of all flex items is larger than the flex container, items shrink to fit according to flex-shrink (default: 1.0).

property flex_basis: LengthPointsPercentAuto

Sets the initial main size of the border box of a flex item (default: AUTO)

property grid_auto_flow: GridAutoFlow

Controls how the auto-placement algorithm works, specifying exactly how auto-placed items get flowed into the grid.

property grid_template_rows: list[GridTrackSizing]

Defines the track sizing functions of the grid rows (default: None).

property grid_template_columns: list[GridTrackSizing]

Defines the track sizing functions of the grid columns (default: None).

property grid_auto_rows: list[GridTrackSize]

Specifies the size of an implicitly-created grid row track or pattern of tracks. (default: None).

property grid_auto_columns: list[GridTrackSize]

Specifies the size of an implicitly-created grid column track or pattern of tracks. (default: None).

property grid_row: GridPlacement

Specifies a grid item’s size and location within a grid row (default: AUTO).

property grid_column: GridPlacement

Specifies a grid item’s size and location within a grid column (default: AUTO).

Options

enum stretchable.style.Display

Used to control node visibility and layout strategy.

See display on MDN for more information.

Members:

NONE FLEX GRID BLOCK

enum stretchable.style.Overflow

Controls the desired behavior when content does not fit inside the parent node.

See overflow on MDN for more information.

Members:

VISIBLE HIDDEN SCROLL CLIP

enum stretchable.style.Position

The positioning strategy for this node.

This controls both how the origin is determined for the inset property, and whether or not the item will be controlled by flexbox’s layout algorithm.

See position on MDN for more information.

Warning

This enum follows the behavior of CSS’s position property, which can be unintuitive.

Members:

RELATIVE ABSOLUTE

Alignment

enum stretchable.style.AlignItems

Used to control how child nodes are aligned.

For Flexbox it controls alignment in the cross axis. For Grid it controls alignment in the block axis.

See align-items on MDN for more information.

Members:

START END FLEX_START FLEX_END CENTER BASELINE STRETCH

enum stretchable.style.JustifyItems

Used to control how child nodes are aligned.

Does not apply to Flexbox, and will be ignored if specified on a flex container. For Grid it controls alignment in the inline axis.

See justify-items on MDN for more information.

Members:

START END FLEX_START FLEX_END CENTER BASELINE STRETCH

enum stretchable.style.AlignSelf

Used to control how the node is aligned.

Overrides the parent Node’s AlignItems property. For Flexbox it controls alignment in the cross axis For Grid it controls alignment in the block axis

See align-self on MDN for more information.

Members:

START END FLEX_START FLEX_END CENTER BASELINE STRETCH

enum stretchable.style.JustifySelf

Used to control how the node is aligned.

Overrides the parent node Style property. Does not apply to Flexbox, and will be ignored if specified on a flex child For Grid it controls alignment in the inline axis

See justify-self on MDN for more information.

Members:

START END FLEX_START FLEX_END CENTER BASELINE STRETCH

enum stretchable.style.AlignContent

Sets the distribution of space between and around content items.

For Flexbox it controls alignment in the cross axis. For Grid it controls alignment in the block axis.

See align-content on MDN for more information.

Members:

START END FLEX_START FLEX_END CENTER STRETCH SPACE_BETWEEN SPACE_EVENLY SPACE_AROUND

enum stretchable.style.JustifyContent

Sets the distribution of space between and around content items.

For Flexbox it controls alignment in the main axis. For Grid it controls alignment in the inline axis.

See justify-content on MDN for more information.

Members:

START END FLEX_START FLEX_END CENTER STRETCH SPACE_BETWEEN SPACE_EVENLY SPACE_AROUND

Flexbox

enum stretchable.style.FlexWrap

Controls whether flex items are forced onto one line or can wrap onto multiple lines.

See flex-wrap on MDN for more information.

Members:

NO_WRAP WRAP WRAP_REVERSE

enum stretchable.style.FlexDirection

The direction of the flexbox layout main axis.

There are always two perpendicular layout axes: main (or primary) and cross (or secondary). Adding items will cause them to be positioned adjacent to each other along the main axis. By varying this value throughout your tree, you can create complex axis-aligned layouts.

Items are always aligned relative to the cross axis, and justified relative to the main axis.

See flex-direction on MDN for more information.

Members:

ROW COLUMN ROW_REVERSE COLUMN_REVERSE

Grid

enum stretchable.style.GridAutoFlow

Controls whether grid items are placed row-wise or column-wise, and whether the sparse or dense packing algorithm is used.

The “dense” packing algorithm attempts to fill in holes earlier in the grid, if smaller items come up later. This may cause items to appear out-of-order, when doing so would fill in holes left by larger items.

See grid-auto-flow on MDN for more information.

Members:

ROW COLUMN ROW_DENSE COLUMN_DENSE

enum stretchable.style.GridIndexType

Members:

AUTO INDEX SPAN

class stretchable.style.GridTrackSize

class stretchable.style.GridTrackSizing

class stretchable.style.GridPlacement

Geometry

The stretchable.style.geometry module describes length, size (2 lengths, typically width and height) and rectangles (4 lengths). For each of these, different scales (eg. points, percentages, etc.) are available.

All of the classes have different variants which limit the allowed scales for a specific context/setting on the Style class.

Scale

enum stretchable.style.geometry.Scale

All available length scales/settings (support is context-dependent).

Members:

AUTO POINTS PERCENT MIN_CONTENT MAX_CONTENT FIT_CONTENT_POINTS FIT_CONTENT_PERCENT FLEX

enum stretchable.style.geometry.Points

Members:

POINTS

enum stretchable.style.geometry.PointsPercent

Members:

POINTS PERCENT

enum stretchable.style.geometry.PointsPercentAuto

Members:

AUTO POINTS PERCENT

enum stretchable.style.geometry.AvailableSpace

Members:

DEFINITE MIN_CONTENT MAX_CONTENT

enum stretchable.style.geometry.MinTrackSize

Members:

POINTS PERCENT MIN_CONTENT MAX_CONTENT AUTO

enum stretchable.style.geometry.MaxTrackSize

Members:

POINTS PERCENT MIN_CONTENT MAX_CONTENT FIT_CONTENT_POINTS FIT_CONTENT_PERCENT AUTO FLEX

Length

class stretchable.style.geometry.Length(scale: Scale, value: float) → Length

Represents a length. For some values of Scale, value is not applicable.

It is recommended to use the static constructors on the different variants of Length, instead of using the constructor directly.

Todo

Add documentation for Length constructors and variants.

Size

class stretchable.style.geometry.Size(*values: Length, width: Length = None, height: Length = None) → Size

Represents two lengths (typically the size of a rectangle eg. width and height).

Todo

Add documentation for Size constructors and variants.

Rect

class stretchable.style.geometry.Rect(*values: Length, top: Length = None, right: Length = None, bottom: Length = None, left: Length = None) → Rect

Represents four lengths.

Todo

Add documentation for Rect constructors and variants.

Exceptions

exception stretchable.exceptions.TaffyUnavailableError

exception stretchable.exceptions.NodeLocatorError

exception stretchable.exceptions.NodeNotFound

exception stretchable.exceptions.LayoutNotComputedError

Todo

Add documentation for exceptions.