units

Documentation

Overview

Package Units supports full range of CSS-style length units (em, px, dp, etc)

The unit is stored along with a value, and can be converted at a later point into a raw display pixel value using the Context which contains all the necessary reference values to perform the conversion. Typically the unit value is parsed early from a style and then converted later once the context is fully resolved. The Value also holds the converted value (Dots) so it can be used directly without further re-conversion.

'Dots' are used as term for underlying raw display pixels because "Pixel" and the px unit are actually not conventionally used as raw display pixels in the current HiDPI environment. See https://developer.mozilla.org/en/docs/Web/CSS/length -- 1 px = 1/96 in Also supporting dp = density-independent pixel = 1/160 in

Index

• Constants
• Variables
• type Context
  • func (uc *Context) Defaults()
  • func (uc *Context) DotsToPx(val float32) float32
  • func (uc *Context) PxToDots(val float32) float32
  • func (uc *Context) Set(em, ex, ch, rem, vpw, vph, elw, elh float32)
  • func (uc *Context) SetFont(em, ex, ch, rem float32)
  • func (uc *Context) SetSizes(vpw, vph, elw, elh float32)
  • func (uc *Context) ToDots(val float32, un Units) float32
  • func (uc *Context) ToDotsFactor(un Units) float32
• type Units
  • func (i *Units) FromString(s string) error
  • func (ev Units) MarshalJSON() ([]byte, error)
  • func (i Units) String() string
  • func (ev *Units) UnmarshalJSON(b []byte) error
• type Value
  • func NewCh(val float32) Value
  • func NewDot(val float32) Value
  • func NewDp(val float32) Value
  • func NewEm(val float32) Value
  • func NewEx(val float32) Value
  • func NewPct(val float32) Value
  • func NewPt(val float32) Value
  • func NewPx(val float32) Value
  • func NewValue(val float32, un Units) Value
  • func StringToValue(str string) Value
  • func (v *Value) Convert(to Units, ctxt *Context) Value
  • func (v *Value) Set(val float32, un Units)
  • func (v *Value) SetCh(val float32)
  • func (v *Value) SetDot(val float32)
  • func (v *Value) SetDp(val float32)
  • func (v *Value) SetEm(val float32)
  • func (v *Value) SetEx(val float32)
  • func (v *Value) SetFmInheritProp(key string, k ki.Ki, inherit, typ bool) (bool, error)
  • func (v *Value) SetFmProp(key string, props ki.Props) (bool, error)
  • func (v *Value) SetIFace(iface any, key string) error
  • func (v *Value) SetPct(val float32)
  • func (v *Value) SetPt(val float32)
  • func (v *Value) SetPx(val float32)
  • func (v *Value) SetString(str string)
  • func (v *Value) String() string
  • func (v *Value) ToDots(ctxt *Context) float32
  • func (v *Value) ToDotsFixed(ctxt *Context) fixed.Int26_6

Constants

const (
	PxPerInch = 96.0
	DpPerInch = 160.0
	MmPerInch = 25.4
	CmPerInch = 2.54
	PtPerInch = 72.0
	PcPerInch = 6.0
)

standard conversion factors -- Px = DPI-independent pixel instead of actual "dot" raw pixel

Variables

var KiT_Units = kit.Enums.AddEnumAltLower(UnitsN, kit.NotBitFlag, nil, "")

var KiT_Value = kit.Types.AddType(&Value{}, ValueProps)

var UnitNames = [...]string{
	Px:   "px",
	Dp:   "dp",
	Pct:  "pct",
	Rem:  "rem",
	Em:   "em",
	Ex:   "ex",
	Ch:   "ch",
	Vw:   "vw",
	Vh:   "vh",
	Vmin: "vmin",
	Vmax: "vmax",
	Cm:   "cm",
	Mm:   "mm",
	Q:    "q",
	In:   "in",
	Pc:   "pc",
	Pt:   "pt",
	Dot:  "dot",
}

var ValueProps = ki.Props{
	"style-prop": true,
}

Types

type Context

type Context struct {

	// DPI is dots-per-inch of the display
	DPI float32

	// FontEm is the point size of the font in raw dots (not points)
	FontEm float32

	// FontEx is the height x-height of font in points (size of 'x' glyph)
	FontEx float32

	// FontCh is the ch-size character size of font in points (width of '0' glyph)
	FontCh float32

	// FontRem is rem-size of font in points -- root Em size -- typically 12 point
	FontRem float32

	// VpW is viewport width in dots
	VpW float32

	// VpH is viewport height in dots
	VpH float32

	// ElW is width of surrounding contextual element in dots
	ElW float32

	// ElH is height of surrounding contextual element in dots
	ElH float32
}

Context specifies everything about the current context necessary for converting the number into specific display-dependent pixels

func (*Context) Defaults

func (uc *Context) Defaults()

Defaults are generic defaults

func (*Context) DotsToPx

func (uc *Context) DotsToPx(val float32) float32

DotsToPx just converts a value from dots to pixels

func (*Context) PxToDots

func (uc *Context) PxToDots(val float32) float32

PxToDots just converts a value from pixels to dots

func (*Context) Set

func (uc *Context) Set(em, ex, ch, rem, vpw, vph, elw, elh float32)

Set sets the context values

func (*Context) SetFont

func (uc *Context) SetFont(em, ex, ch, rem float32)

SetFont sets the context values for fonts: note these are already in raw DPI dots, not points or anything else

func (*Context) SetSizes

func (uc *Context) SetSizes(vpw, vph, elw, elh float32)

SetSizes sets the context values for non-font sizes -- el is ignored if zero

func (*Context) ToDots

func (uc *Context) ToDots(val float32, un Units) float32

ToDots converts value in given units into raw display pixels (dots in DPI)

func (*Context) ToDotsFactor

func (uc *Context) ToDotsFactor(un Units) float32

ToDotsFact returns factor needed to convert given unit into raw pixels (dots in DPI)

type Units

type Units int32

const (
	// Px = pixels -- 1px = 1/96th of 1in -- these are NOT raw display pixels
	Px Units = iota

	// Dp = density-independent pixels -- 1dp = 1/160th of 1in
	Dp

	// Pct = percentage of surrounding contextual element
	Pct

	// Rem = font size of the root element -- defaults to 12pt scaled by DPI factor
	Rem

	// Em = font size of the element -- fallback to 12pt by default
	Em

	// Ex = x-height of the element's font (size of 'x' glyph) -- fallback to 0.5em by default
	Ex

	// Ch = width of the '0' glyph in the element's font -- fallback to 0.5em by default
	Ch

	// Vw = 1% of the viewport's width
	Vw

	// Vh = 1% of the viewport's height
	Vh

	// Vmin = 1% of the viewport's smaller dimension
	Vmin

	// Vmax = 1% of the viewport's larger dimension
	Vmax

	// Cm = centimeters -- 1cm = 96px/2.54
	Cm

	// Mm = millimeters -- 1mm = 1/10th of cm
	Mm

	// Q = quarter-millimeters -- 1q = 1/40th of cm
	Q

	// In = inches -- 1in = 2.54cm = 96px
	In

	// Pc = picas -- 1pc = 1/6th of 1in
	Pc

	// Pt = points -- 1pt = 1/72th of 1in
	Pt

	// Dot = actual real display pixels -- generally only use internally
	Dot

	UnitsN
)

func (*Units) FromString

func (i *Units) FromString(s string) error

func (Units) MarshalJSON

func (ev Units) MarshalJSON() ([]byte, error)

func (Units) String

func (i Units) String() string

func (*Units) UnmarshalJSON

func (ev *Units) UnmarshalJSON(b []byte) error

type Value

type Value struct {
	Val  float32
	Un   Units
	Dots float32
}

Value and units, and converted value into raw pixels (dots in DPI)

func NewCh

func NewCh(val float32) Value

NewCh creates a new Ch value

func NewDot

func NewDot(val float32) Value

NewDot creates a new Dot value

func NewDp

func NewDp(val float32) Value

NewDp creates a new Dp value

func NewEm

func NewEm(val float32) Value

NewEm creates a new Em value

func NewEx

func NewEx(val float32) Value

NewEx creates a new Ex value

func NewPct

func NewPct(val float32) Value

NewPct creates a new Pct value

func NewPt

func NewPt(val float32) Value

NewPt creates a new Pt value

func NewPx

func NewPx(val float32) Value

NewPx creates a new Px value

func NewValue

func NewValue(val float32, un Units) Value

NewValue creates a new value with given units

func StringToValue

func StringToValue(str string) Value

StringToValue converts a string to a value representation.

func (*Value) Convert

func (v *Value) Convert(to Units, ctxt *Context) Value

Convert converts value to the given units, given unit context

func (*Value) Set

func (v *Value) Set(val float32, un Units)

Set sets value and units of an existing value

func (*Value) SetCh

func (v *Value) SetCh(val float32)

SetCh sets value in Ch

func (*Value) SetDot

func (v *Value) SetDot(val float32)

SetDot sets value in Dots directly

func (*Value) SetDp

func (v *Value) SetDp(val float32)

SetDp sets value in Dp

func (*Value) SetEm

func (v *Value) SetEm(val float32)

SetEm sets value in Em

func (*Value) SetEx

func (v *Value) SetEx(val float32)

SetEx sets value in Ex

func (*Value) SetFmInheritProp

func (v *Value) SetFmInheritProp(key string, k ki.Ki, inherit, typ bool) (bool, error)

SetFmInheritProp sets value from property of given key name in inherited or type properties from given Ki.ki type -- returns true if property found and set, error for any errors in setting property

func (*Value) SetFmProp

func (v *Value) SetFmProp(key string, props ki.Props) (bool, error)

SetFmProp sets value from property of given key name in given list of properties -- returns true if property found and set, error for any errors in setting property

func (*Value) SetIFace

func (v *Value) SetIFace(iface any, key string) error

SetIFace sets value from an interface value representation as from ki.Props key is optional property key for error message -- always logs the error

func (*Value) SetPct

func (v *Value) SetPct(val float32)

SetPct sets value in Pct

func (*Value) SetPt

func (v *Value) SetPt(val float32)

SetPt sets value in Pt

func (*Value) SetPx

func (v *Value) SetPx(val float32)

SetPx sets value in Px

func (*Value) SetString

func (v *Value) SetString(str string)

SetString sets value from a string

func (*Value) String

func (v *Value) String() string

String implements the fmt.Stringer interface.

func (*Value) ToDots

func (v *Value) ToDots(ctxt *Context) float32

ToDots converts value to raw display pixels (dots as in DPI), setting also the Dots field

func (*Value) ToDotsFixed

func (v *Value) ToDotsFixed(ctxt *Context) fixed.Int26_6

ToDotsFixed converts value to raw display pixels (dots in DPI) in fixed-point 26.6 format for rendering