Length

#include <AppCore/layout/Length.h>

Overview

A distance or size constraint in an AppCore layout.

You use Length to set container padding and gap, or to define minimum and maximum size constraints on panels and containers.

Numbers and CSS string literals convert to Length automatically, so you can write values directly in layout options.

This example sets a row's spacing and constrains a child panel:

RefPtr<Container> body =
    window->layout()->AddRow({ .gap = 8, .padding = "12px" });
body->AddPanel({ .min_size = "160px", .max_size = "40%" });

Supported Units

A Length is measured in one of two units:

• Logical pixels represent fixed distances. Bare numbers, Length::Px(), and string literals with "px" specify logical pixels. Container gap and padding accept logical pixels only.
• Percentages are relative to the container's content box (inside its padding). Unlike a Size percent, which is a share of the container's free space, a Length percent uses the whole box.

Length doesn't accept flex units– a flex factor isn't a distance, and passing "fr" or a Flex produces a compile error.

Literals and Unset Values

String literals and runtime strings follow the same rules as Size (see Size).

The default constructor creates an unset Length, which leaves the receiving field's default in effect:

• Size constraints impose no bounds. An unset min_size leaves a node with no minimum size, and an unset max_size leaves it with no maximum size.
• Container spacing adds no space. An unset gap leaves zero space between adjacent children, and an unset padding applies zero inset around the container.

See also

Size, ContainerOptions, LayoutNode::SetMinSize()

Public Types
enum class	Unit : uint8_t { Default = 0 , Px , Percent }
	The unit of a Length. More...

Static Public Member Functions
static constexpr Length	Px (double value)
	Create a Length in logical pixels.
static constexpr Length	Pct (double value)
	Create a percentage Length.
static constexpr bool	TryParse (const char *text, size_t length, Length &out)
	Parse a runtime string with the same rules as the literal form.
static bool	TryParse (const String &text, Length &out)
	Parse a runtime string with the same rules as the literal form.

Public Member Functions
constexpr	Length ()=default
	Create an unset Length (the receiving field's default applies).
constexpr	Length (double px)
	Create a Length in logical pixels (implicit, a bare number means px).
template<size_t N>
UL_CSS_CONSTEVAL	Length (const char(&s)[N])
	Create a Length from a CSS string literal, parsed and validated at compile time.
constexpr	Length (Flex)=delete
	Length does not accept fr units– a flex factor is not a distance.
constexpr double	value () const
	Get the numeric value (px or percent points, per unit()).
constexpr Unit	unit () const
	Get the unit.
constexpr bool	is_set () const
	Whether or not this value was explicitly set (shorthand for unit() != Unit::Default).
constexpr bool	invalid () const
	Whether or not this value came from a malformed literal on a compiler where literal validation degrades to a runtime flag.

Friends
constexpr bool	operator== (const Length &, const Length &)=default

Member Enumeration Documentation

Unit

enum class Unit : uint8_t

strong

The unit of a Length.

Enumerator
Default	Unset: the receiving field's default applies.
Px	Logical pixels.
Percent	A percentage of the parent container's content box (inside its padding).

Constructor & Destructor Documentation

Length() [1/4]

Length ( )

constexprdefault

Create an unset Length (the receiving field's default applies).

Length() [2/4]

Length ( double px )

inlineconstexpr

Create a Length in logical pixels (implicit, a bare number means px).

Length() [3/4]

template<size_t N>

UL_CSS_CONSTEVAL Length ( const char(&) s[N] )

inline

Create a Length from a CSS string literal, parsed and validated at compile time.

Accepted forms are a number with px, a number with %, and a bare number (logical pixels). Any other format produces a compile error that explains the issue.

Note

Only string literals bind here. A runtime string must go through TryParse().

Length() [4/4]

Length ( Flex )

constexprdelete

Length does not accept fr units– a flex factor is not a distance.

Use Size instead.

Member Function Documentation

invalid()

bool invalid ( ) const

inlineconstexpr

Whether or not this value came from a malformed literal on a compiler where literal validation degrades to a runtime flag.

Note

The library treats an invalid value as unset and logs a warning that identifies the panel or container it belongs to.

is_set()

bool is_set ( ) const

inlineconstexpr

Whether or not this value was explicitly set (shorthand for unit() != Unit::Default).

Pct()

constexpr Length Pct ( double value )

inlinestaticconstexpr

Create a percentage Length.

Parameters

value

The percentage, in percent points (50 means 50%).

Px()

constexpr Length Px ( double value )

inlinestaticconstexpr

Create a Length in logical pixels.

Parameters

value

The distance, in logical pixels.

TryParse() [1/2]

constexpr bool TryParse ( const char * text, size_t length, Length & out )

inlinestaticconstexpr

Parse a runtime string with the same rules as the literal form.

Parameters

text	UTF-8 text to parse.
length	Byte length of text.
out	Receives the parsed value on success (left unchanged on failure).

Returns

Returns whether or not the text parsed as a valid Length.

TryParse() [2/2]

bool TryParse ( const String & text, Length & out )

inlinestatic

Parse a runtime string with the same rules as the literal form.

Parameters

text	The text to parse.
out	Receives the parsed value on success (left unchanged on failure).

Returns

Returns whether or not the text parsed as a valid Length.

unit()

Unit unit ( ) const

inlineconstexpr

Get the unit.

Unit::Default means unset (the field's default applies).

value()

double value ( ) const

inlineconstexpr

Get the numeric value (px or percent points, per unit()).

Zero when unset.

Friends And Related Symbol Documentation

operator==

bool operator== ( const Length & , const Length &  )

friend

---

The documentation for this class was generated from the following file:

• AppCore/layout/Length.h