StyleValue

#include <Ultralight/dom/StyleValue.h>

Overview

A numeric CSS value and its unit.

dom::StyleValue pairs a number with a CSS unit for styling page elements from native code. It lets you write numeric values directly to an element's inline style without formatting strings, and read numeric properties back from inline or computed styles.

You can update a health bar with computed values:

dom::Element bar = document.getElementById("health-bar");
bar.style.width = dom::StyleValue::Pct(health * 100);
bar.style.left = dom::StyleValue::Px(x);
bar.style.opacity = 0.8;  // a bare number has no unit

The library still parses the value as CSS when applying it to the element.

Reading Styles and Value States

Calling AsStyleValue() on an inline or computed style parses the property into a dom::StyleValue:

dom::StyleValue width = dom::getComputedStyle(bar).width.AsStyleValue();
if (width)
  PlaceMinimap(width.value);  // 300 when the width is "300px"

A dom::StyleValue is always in one of these states:

• A number holds a finite value and a StyleUnit. Writing it sets the property.
• Empty holds no value. Writing it removes the inline property.
• Invalid represents text that doesn't convert to a number (eg, auto) or a number that isn't finite. Writing it does nothing and keeps the existing style.

Checking a dom::StyleValue with if (value) evaluates to true only when it holds a number.

You can copy an inline style directly between elements by assigning what you read:

icon.style.width = badge.style.width.AsStyleValue();  // removes icon's width
                                                      // if badge has none

Unsupported Units and Custom Properties

• Properties ignore unsupported units. Assigning a unit that a property doesn't accept (such as pixels for opacity or a unitless number for width) does nothing and keeps the previous value. When DOM diagnostics are on, the library logs a warning for each ignored write.
• Custom properties require text. Assigning a dom::StyleValue to a custom property (--name) does nothing, so assign text like "8px" instead.

See also

dom::Element::style, dom::getComputedStyle(), dom::StyleUnit, dom::CssValue

Static Public Member Functions
static constexpr StyleValue	Parse (std::string_view text)
	Parse CSS text into a StyleValue.
static constexpr StyleValue	Number (double v)
	Create a unitless number (CSS <number>).
static constexpr StyleValue	Px (double v)
	Create a length in CSS pixels (px).
static constexpr StyleValue	Pct (double v)
	Create a percentage (%).
static constexpr StyleValue	Em (double v)
	Create a multiple of the element's font size (em).
static constexpr StyleValue	Rem (double v)
	Create a multiple of the root element's font size (rem).
static constexpr StyleValue	Vw (double v)
	Create a percentage of the viewport width (vw).
static constexpr StyleValue	Vh (double v)
	Create a percentage of the viewport height (vh).
static constexpr StyleValue	Deg (double v)
	Create an angle in degrees (deg).
static constexpr StyleValue	Ms (double v)
	Create a time in milliseconds (ms).
static constexpr StyleValue	S (double v)
	Create a time in seconds (s).

Public Member Functions
constexpr	StyleValue ()=default
	Create an Empty StyleValue (it holds nothing, and writing it removes the property).
constexpr	StyleValue (double value)
	Create a unitless number (CSS <number>).
constexpr	StyleValue (double value, StyleUnit unit)
	Create a number with a unit.
constexpr bool	IsEmpty () const
	Whether or not this StyleValue is Empty (it holds nothing).
constexpr bool	IsInvalid () const
	Whether or not this StyleValue is Invalid (it came from text that doesn't convert, or its value isn't finite).
constexpr	operator bool () const
	Whether or not this StyleValue holds a number (it's neither Empty nor Invalid).

Public Attributes
double	value = 0
	The number (only meaningful when this holds one).
StyleUnit	unit = StyleUnit::Empty
	The number's unit (StyleUnit::Empty when it's Empty).

Constructor & Destructor Documentation

StyleValue() [1/3]

StyleValue ( )

constexprdefault

Create an Empty StyleValue (it holds nothing, and writing it removes the property).

StyleValue() [2/3]

StyleValue ( double value )

inlineconstexpr

Create a unitless number (CSS <number>).

A bare number converts to this implicitly.

Parameters

value

The number.

StyleValue() [3/3]

StyleValue ( double value, StyleUnit unit )

inlineconstexpr

Create a number with a unit.

The unit factories (eg, Px()) are shorter.

Parameters

value	The number.
unit	The number's unit.

Member Function Documentation

Deg()

constexpr StyleValue Deg ( double v )

inlinestaticconstexpr

Create an angle in degrees (deg).

Parameters

v	The number of degrees.

Em()

constexpr StyleValue Em ( double v )

inlinestaticconstexpr

Create a multiple of the element's font size (em).

Parameters

v	The multiple.

IsEmpty()

bool IsEmpty ( ) const

inlineconstexpr

Whether or not this StyleValue is Empty (it holds nothing).

IsInvalid()

bool IsInvalid ( ) const

inlineconstexpr

Whether or not this StyleValue is Invalid (it came from text that doesn't convert, or its value isn't finite).

Ms()

constexpr StyleValue Ms ( double v )

inlinestaticconstexpr

Create a time in milliseconds (ms).

Parameters

v	The number of milliseconds.

Number()

constexpr StyleValue Number ( double v )

inlinestaticconstexpr

Create a unitless number (CSS <number>).

Parameters

v	The number.

operator bool()

operator bool ( ) const

inlineexplicitconstexpr

Whether or not this StyleValue holds a number (it's neither Empty nor Invalid).

Parse()

constexpr StyleValue Parse ( std::string_view text )

inlinestaticconstexpr

Parse CSS text into a StyleValue.

The text must be a single number with no unit or a StyleUnit unit. Style members and reads by name have AsStyleValue(), which does the same.

StyleValue::Parse("300px");   // 300, StyleUnit::Px
StyleValue::Parse("0.5");     // 0.5, StyleUnit::Number
StyleValue::Parse("");        // Empty
StyleValue::Parse("auto");    // Invalid (a keyword)
StyleValue::Parse("12pt");    // Invalid (pt isn't a StyleUnit)

Parameters

text	The CSS text.

Returns

Returns the number with its unit, an Empty StyleValue when text is empty, or an Invalid one when text doesn't convert.

Pct()

constexpr StyleValue Pct ( double v )

inlinestaticconstexpr

Create a percentage (%).

Parameters

v	The percentage (50 means 50%).

Px()

constexpr StyleValue Px ( double v )

inlinestaticconstexpr

Create a length in CSS pixels (px).

Parameters

v	The number of pixels.

Rem()

constexpr StyleValue Rem ( double v )

inlinestaticconstexpr

Create a multiple of the root element's font size (rem).

Parameters

v	The multiple.

S()

constexpr StyleValue S ( double v )

inlinestaticconstexpr

Create a time in seconds (s).

Parameters

v	The number of seconds.

Vh()

constexpr StyleValue Vh ( double v )

inlinestaticconstexpr

Create a percentage of the viewport height (vh).

Parameters

v	The percentage (100 is the full height).

Vw()

constexpr StyleValue Vw ( double v )

inlinestaticconstexpr

Create a percentage of the viewport width (vw).

Parameters

v	The percentage (100 is the full width).

Member Data Documentation

unit

StyleUnit unit = StyleUnit::Empty

The number's unit (StyleUnit::Empty when it's Empty).

value

double value = 0

The number (only meaningful when this holds one).

---

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

• Ultralight/dom/StyleValue.h