Size

#include <AppCore/layout/Length.h>

Overview

Fixed, percentage, and flexible sizes for panels and containers.

Size specifies how much space a child node occupies inside a row or column. You assign it when configuring panels and containers in layout options, or update it later with LayoutNode::SetSize().

This row distributes its space among three panels using different sizing units:

RefPtr<Container> body = window->layout()->AddRow();
body->AddPanel({ .size = "240px" });  // logical pixels
body->AddPanel({ .size = "30%" });    // percent of the free space
body->AddPanel({ .size = "2fr" });    // two flex shares of what's left

Layout Units

Panels and containers accept different measurement forms along their parent container's axis:

• Logical pixels specify a fixed distance. A bare number or a string with px sets the dimension in display-independent pixels.
• Percentages claim a fraction of the container's free space. A string with % reserves that portion of the space remaining after fixed siblings.
• Flex shares divide whatever space remains. A string with fr takes a proportional cut of the free space left after fixed and percentage allocations.

Computed Sizes

When sizes depend on runtime calculations rather than string constants, use factory methods or the Flex helper type. Call Size::Fr() or Flex to specify flex shares.

Pass numeric values directly instead of formatting strings:

Size half = Size::Pct(50);
Size wide = Flex(2);  // the same as "2fr"

Literals and Runtime Strings

String literals passed to Size are parsed and validated at compile time. Any syntax typo or unsupported unit produces a compiler error.

For strings read at runtime, use Size::TryParse():

Size parsed;
if (Size::TryParse(saved_width, parsed))
  sidebar->SetSize(parsed);

Default and Unset Sizes

A default-constructed Size has no explicit unit or value. Leaving a size unset instructs the receiving field to apply its own default, which gives panels and containers in a row or column a single flex share (1fr) and floating panels 100%.

Setting an explicit size of 0 or "0px" collapses the node to zero pixels along the layout axis instead of expanding it.

See also

Length, Flex, PanelOptions, LayoutNode::SetSize()

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

Static Public Member Functions
static constexpr Size	Px (double value)
	Create a Size in logical pixels.
static constexpr Size	Pct (double value)
	Create a percent-of-free-space Size.
static constexpr Size	Fr (double value)
	Create a flex-factor Size.
static constexpr bool	TryParse (const char *text, size_t length, Size &out)
	Parse a runtime string with the same rules as the literal form.
static bool	TryParse (const String &text, Size &out)
	Parse a runtime string with the same rules as the literal form.

Public Member Functions
constexpr	Size ()=default
	Create an unset Size (the receiving field's default applies).
constexpr	Size (double px)
	Create a Size in logical pixels (implicit, a bare number means px).
constexpr	Size (Length length)
	Create a Size from a Length (implicit, px stays px and percent stays percent).
constexpr	Size (Flex flex)
	Create a Size from a flex factor (implicit).
template<size_t N>
UL_CSS_CONSTEVAL	Size (const char(&s)[N])
	Create a Size from a CSS string literal, parsed and validated at compile time.
constexpr double	value () const
	Get the numeric value (px, percent points, or flex factor, 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 (see Length::invalid()).

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

Member Enumeration Documentation

Unit

enum class Unit : uint8_t

strong

The unit of a Size.

Enumerator
Default	Unset: the receiving field's default applies.
Px	Logical pixels.
Percent	A percentage of the container's free space along the axis.
Fr	A flex factor (share of the remaining free space).

Constructor & Destructor Documentation

Size() [1/5]

Size ( )

constexprdefault

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

Size() [2/5]

Size ( double px )

inlineconstexpr

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

Size() [3/5]

Size ( Length length )

inlineconstexpr

Create a Size from a Length (implicit, px stays px and percent stays percent).

Size() [4/5]

Size ( Flex flex )

inlineconstexpr

Create a Size from a flex factor (implicit).

Size() [5/5]

template<size_t N>

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

inline

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

Accepted forms are a number with px, %, or fr, 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().

Member Function Documentation

Fr()

constexpr Size Fr ( double value )

inlinestaticconstexpr

Create a flex-factor Size.

Parameters

value

The share of free space, relative to the sibling flex factors.

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 (see Length::invalid()).

is_set()

bool is_set ( ) const

inlineconstexpr

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

Pct()

constexpr Size Pct ( double value )

inlinestaticconstexpr

Create a percent-of-free-space Size.

Parameters

value

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

Px()

constexpr Size Px ( double value )

inlinestaticconstexpr

Create a Size in logical pixels.

Parameters

value

The size, in logical pixels.

TryParse() [1/2]

constexpr bool TryParse ( const char * text, size_t length, Size & 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 Size.

TryParse() [2/2]

bool TryParse ( const String & text, Size & 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 Size.

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, percent points, or flex factor, per unit()).

Zero when unset.

Friends And Related Symbol Documentation

operator==

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

friend

---

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

• AppCore/layout/Length.h