classDocs / ViewportLayout

ViewportLayout

classclientsource

Object → ViewportLayout

A named set of CSS / viewport length descriptors that resolve to floored pixels and refresh when the window is resized.

Indexing a registered alias (hud.hex) returns the cached integer pixel length. Unknown keys fall through to the class prototype.

Handlers attached with :attach / :once run after the shared pixel cache is recomputed on OnScreenSizeChanged.

Construction raises ValueError if any descriptor cannot be parsed.

lua

local hud = ViewportLayout( {
    hex = "1vmin",
    t = "2vmin",
    h = "10cm",
    me = "12mm",
    d = "120px"
} )

print( hud.hex ) -- floored pixels for "1vmin"

hud:attach( function( layout, old_width, old_height, new_width, new_height )
    print( layout.hex ) -- refreshed after resize
end )

Constructor

ViewportLayout(definitions: table<string, string>): table<string, integer>

Static functions

#ViewportLayout.parse

clientnodiscardsource

function ViewportLayout.parse(descriptor: string): integer

Parses a display length string into floored CSS pixels.

Raises ValueError with "missing magnitude", "missing unit type", or "unsupported unit" when the descriptor cannot be parsed.

lua

ViewportLayout.parse( "120px" ) -- 120
ViewportLayout.parse( "10cm" )  -- floored CSS pixels at 96 DPI
ViewportLayout.parse( "1vmin" ) -- floored pixels from current window size

Parameters

Name	Type	Description
`descriptor`	`string`	The length quantity string to parse (`"<number><ViewportUnit>"`).

Returns

Type	Name	Description
`integer`	`pixels`	The floored pixel length.

Methods

`attach`	Attaches a handler that runs after this layout's pixel values are refreshed on screen resize.
`await`	Waits for the next screen-size refresh of this layout.
`clear`	Removes every resize handler attached to this layout.
`detach`	Detaches a previously attached resize handler.
`once`	Attaches a one-shot resize handler that detaches itself before running.

#ViewportLayout:attach

clientsource

function ViewportLayout:attach(handler: fun( layout: ViewportLayout, old_width: integer, old_height: integer, new_width: integer, new_height: integer ) | Hook | Event)

Attaches a handler that runs after this layout's pixel values are refreshed on screen resize.

Attaching the same handler twice is a no-op, handlers run in protected mode.

Parameters

Name	Type	Description
`handler`	`fun( layout: ViewportLayout, old_width: integer, old_height: integer, new_width: integer, new_height: integer ) \| Hook \| Event`	The callback or callable object.

#ViewportLayout:await

clientasyncsource

async function ViewportLayout:await(): ViewportLayout, integer, integer, integer, integer

Waits for the next screen-size refresh of this layout.

Returns

Type	Name	Description
`ViewportLayout`	`layout`
`integer`	`old_width`
`integer`	`old_height`
`integer`	`new_width`
`integer`	`new_height`

#ViewportLayout:clear

clientsource

function ViewportLayout:clear()

Removes every resize handler attached to this layout.

#ViewportLayout:detach

clientsource

function ViewportLayout:detach(handler: fun( layout: ViewportLayout, old_width: integer, old_height: integer, new_width: integer, new_height: integer ) | Hook | Event): boolean

Detaches a previously attached resize handler.

Parameters

Name	Type	Description
`handler`	`fun( layout: ViewportLayout, old_width: integer, old_height: integer, new_width: integer, new_height: integer ) \| Hook \| Event`	The exact handler reference.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the handler was attached.

#ViewportLayout:once

clientsource

function ViewportLayout:once(handler: fun( layout: ViewportLayout, old_width: integer, old_height: integer, new_width: integer, new_height: integer ) | Hook | Event)

Attaches a one-shot resize handler that detaches itself before running.

Parameters

Name	Type	Description
`handler`	`fun( layout: ViewportLayout, old_width: integer, old_height: integer, new_width: integer, new_height: integer ) \| Hook \| Event`	The callback or callable object.