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) 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 Unit) float32
  • func (uc *Context) ToDotsFactor(un Unit) float32
• type Unit
  • func (i *Unit) FromString(s string) error
  • func (ev Unit) MarshalJSON() ([]byte, error)
  • func (i Unit) String() string
  • func (ev *Unit) UnmarshalJSON(b []byte) error
• type Value
  • func NewValue(val float32, un Unit) Value
  • func StringToValue(str string) Value
  • func (v *Value) Convert(to Unit, ctxt *Context) Value
  • func (v *Value) Set(val float32, un Unit)
  • func (v *Value) SetFromString(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_Unit = kit.Enums.AddEnumAltLower(UnitN, false, 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 {
	// dots-per-inch of the display
	DPI float32
	// point size of font (in points)
	FontEm float32
	// x-height of font in points
	FontEx float32
	// ch-size of font in points
	FontCh float32
	// rem-size of font in points
	FontRem float32
	// viewport width in dots
	VpW float32
	// viewport height in dots
	VpH float32
	// width of surrounding contextual element in dots
	ElW float32
	// 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()

func (*Context) Set

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

set the context values

func (*Context) SetFont

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

set the context values for fonts

func (*Context) SetSizes

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

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

func (*Context) ToDots

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

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

func (*Context) ToDotsFactor

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

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

type Unit

type Unit int32

const (
	// Px = pixels -- 1px = 1/96th of 1in -- these are NOT raw display pixels
	Px Unit = 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 -- fallback to 12pt by default
	Rem

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

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

	// Ch = with 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

	UnitN
)

func (*Unit) FromString

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

func (Unit) MarshalJSON

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

func (Unit) String

func (i Unit) String() string

func (*Unit) UnmarshalJSON

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

type Value

type Value struct {
	Val  float32
	Un   Unit
	Dots float32
}

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

func NewValue

func NewValue(val float32, un Unit) Value

convenience for not having to specify the Dots member

func StringToValue

func StringToValue(str string) Value

func (*Value) Convert

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

Convert converts value to the given units, given unit context

func (*Value) Set

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

func (*Value) SetFromString

func (v *Value) SetFromString(str string)

parse string into a value

func (*Value) String

func (v *Value) String() string

String implements the fmt.Stringer interface.

func (*Value) ToDots

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

Convert 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

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