Module for drawing on top of the game.
A script builds its interface from widgets once, and keeps them.
trx.ui.regions.place puts a widget in one of the regions of the screen,
where it stacks with the health bars and the item names, so the player's
choice of where each element sits still holds. trx.ui.layers.push puts a
screen of widgets, such as a menu, over the rest. A widget takes signals in
place of fixed values, and follows them as they change.
Below the widgets, a script can reserve room in a region during
trx.ui.on_reserve and paint into it by hand with trx.ui.primitive during
trx.ui.on_paint. The primitive drawing calls work only while the
interface is painted.
Sizes are in canvas units, not screen pixels. trx.ui.canvas reports the
canvas, and trx.ui.safe_area the part of it that is free to draw in.
Text carries the same markup the rest of the game uses, and it is part of
this API: \{small} draws the rest of the line small, \{arrow up} draws an
arrow, and \{button left} draws the button the player has bound.
\{color #c08040 #401000} draws what follows in a colour that grades from
the top of each glyph to its bottom, up to \{/color}. A colour is
#rrggbb or #rrggbbaa, one for a flat colour or two for a gradient, and
pulse after them makes it brighten and dim. In TR4, a channel of 80
draws a glyph as it is, and higher values light it up, as the original
lights its font.
trx.ui.canvas (trx.ui.Area). The whole canvas. Widget sizes are in these units rather than in screen pixels, and the canvas is 640 by 480 for a 4:3 screen at the default text size. (read-only)trx.ui.clipboard (string). What the system clipboard holds. Reads as an empty string where it holds nothing, and raises on assignment where the platform refuses the text.
A script-drawn text field uses this value to paste and copy text.trx.ui.text_scale (number). The scale applied to text and its boxes. The value depends on the player's text size and the screen. It is not the ui.text_scale setting alone. (read-only)trx.ui.screen (trx.ui.Area). The whole screen, in canvas units. The canvas holds a whole number of units, so its right and bottom edges can stop short of the screen by a fraction of a unit; the screen reaches the edges. Something drawn from edge to edge, such as a frame around the screen, uses this area. (read-only)trx.ui.safe_area (trx.ui.Area). The part of the canvas that is free to draw in: the canvas, less the margin kept at the edges, less what the game reserves at the top and the bottom for the bars and the text it puts there. (read-only)trx.ui.frames_shown (boolean). Whether the game's frames are drawn: the boxes of dialogs, the strips of headings and the boxes around the option the player is on. A script that draws its menus flat turns them off, and the option the player is on then shows in trx.ui.picked_text_color instead. true by default.trx.ui.text_color (string). The colour text is drawn in where it names none, as the text markup names a colour, or nil for the font as it is drawn.trx.ui.picked_text_color (string). The colour the option the player is on shows in while trx.ui.frames_shown is off, as the text markup names a colour, or nil for the colour of the text around it.trx.ui.working_area (trx.ui.Area). The part of the canvas between the cinematic bars. It is the whole canvas while there are none, and follows the bars as they move in and out. The interface regions lay out inside it, so trx.ui.safe_area lies within it too. (read-only)trx.ui.signals.layout (trx.signal.Signal). Says when the room that the interface lays out in changes: the canvas, trx.ui.safe_area, trx.ui.working_area or trx.ui.text_scale. It holds a count that goes up with each change. A widget that lays itself out by that room listens to this rather than reading the room every frame. (read-only)The direction a stack lays its children out in.
trx.ui.Orientation.VERTICALtrx.ui.Orientation.HORIZONTALWhere a stack puts its children across its width.
trx.ui.HAlign.LEFTtrx.ui.HAlign.CENTERtrx.ui.HAlign.RIGHTtrx.ui.HAlign.SPANtrx.ui.HAlign.DISTRIBUTEWhere a stack puts its children down its height.
trx.ui.VAlign.TOPtrx.ui.VAlign.CENTERtrx.ui.VAlign.BOTTOMtrx.ui.VAlign.SPANtrx.ui.VAlign.DISTRIBUTEOne of the nine areas of the screen that the interface is laid out in. Everything that reserves room in a region is stacked together, so nothing in one region overlaps.
The eight around the edge stack what they hold away from the edge they sit at. The middle is what the others leave, and is where a dialog goes.
trx.ui.Region.TOP_LEFTtrx.ui.Region.TOP_CENTERtrx.ui.Region.TOP_RIGHTtrx.ui.Region.LEFTtrx.ui.Region.CENTERtrx.ui.Region.RIGHTtrx.ui.Region.BOTTOM_LEFTtrx.ui.Region.BOTTOM_CENTERtrx.ui.Region.BOTTOM_RIGHTWhich of the game's frames to draw. The look of each follows the menu style the player chose.
trx.ui.FrameStyle.DIALOGtrx.ui.FrameStyle.DIALOG_HEAVYtrx.ui.FrameStyle.HEADINGtrx.ui.FrameStyle.SELECTEDtrx.ui.FrameStyle.OUTLINEtrx.ui.FrameStyle.HEADING_OUTLINEWhich of the game's bars to draw, which decides its colors.
trx.ui.BarType.LARA_HPtrx.ui.BarType.LARA_HP_POISONtrx.ui.BarType.LARA_AIRtrx.ui.BarType.LARA_STAMINAtrx.ui.BarType.LARA_EXPOSUREtrx.ui.BarType.ENEMY_HPtrx.ui.BarType.ALLY_HPtrx.ui.BarType.PROGRESSAn engine screen that a script can draw. Each screen hands its definition a context of its own kind, which reports what the screen shows.
trx.ui.Screen.RING_ENTRYtrx.ui.EntryContext. A definition can name the entry it draws. A ring opened to save or load leaves when the screen ends, and any ring leaves when the screen ends with trx.ui.ScreenContext:confirm.trx.ui.Screen.PAUSEtrx.ui.PauseContext.trx.ui.Screen.SAVE_LOADtrx.ui.SaveLoadContext. The save and load keys open it when the instant screen setting is on. The screen ends with trx.ui.ScreenContext:confirm once the player saves or loads, and with trx.ui.ScreenContext:cancel otherwise.trx.ui.Screen.STATStrx.ui.StatsContext. The player skips the screen as they would the engine's, and the screen also ends with trx.ui.ScreenContext:cancel or trx.ui.ScreenContext:confirm.trx.ui.Screen.EXAMINEtrx.ui.EntryContext. The screen ends with trx.ui.ScreenContext:cancel, which puts the entry away.trx.ui.Screen.COMBINEtrx.inventory.combine_partners, and combining the two with trx.inventory.combine. It has a trx.ui.EntryContext. The screen ends with trx.ui.ScreenContext:cancel or trx.ui.ScreenContext:confirm, which both put the entry away, and the ring then rests on what a combination made.trx.ui.Screen.GLOBE_SELECTtrx.ui.GlobeContext. The script picks an adventure by starting its level with trx.game.play_level, and trx.ui.ScreenContext:cancel leaves for the title screen.trx.ui.Screen.LEVEL_VIEWtrx.ui.TimedContext. The view ends with trx.ui.ScreenContext:confirm or trx.ui.ScreenContext:cancel.trx.ui.Screen.PICTUREtrx.ui.PictureContext. The picture ends with trx.ui.ScreenContext:confirm or trx.ui.ScreenContext:cancel.trx.ui.Screen.MENUtrx.ui.MenuContext. The menu ends with trx.ui.ScreenContext:confirm once it has done what the player chose.What the engine opens its menu for, which the menu screen is told as it opens.
trx.ui.MenuMode.GAMEtrx.ui.MenuMode.TITLEtrx.ui.MenuMode.KEYStrx.ui.MenuMode.SAVEtrx.ui.MenuMode.LOADtrx.ui.MenuMode.DEATHtrx.ui.MenuMode.SAVE_CRYSTALOne input role, or a list of roles shown side by side.
A rectangle on the canvas, in canvas units, counted from the top left.
Properties:
The player's input, as the active layer reads it.
A layer reads each press as pressed once per tick. A menu key that the player holds keeps reading as pressed at the rate that the game's own menus repeat it. The presses that a layer read on the tick that it closes do not reach the layer below, because they stay inactive until the player releases them.
Methods:
layerkeys:held(role)
Returns whether a role is active. Does not use it up.
Parameters:
role (trx.input.Role). The role.Returns: boolean. Whether it is held.
layerkeys:held_for(role)
Returns for how many ticks a role has been held. A tick in which the layer
did not ask counts as a release.
Parameters:
role (trx.input.Role). The role.Returns: integer. The number of ticks.
layerkeys:pressed(role)
Returns whether a role became active this tick, and uses the press up.
Parameters:
role (trx.input.Role). The role.Returns: boolean. Whether it was pressed.
One screen of widgets on the stack.
Properties:
Methods:
stacklayer:close()
Removes the layer from the stack, and releases its widgets. Does nothing if
the layer is already closed.
Returns: boolean. Whether the layer was open.
stacklayer:set_root(root, [place])
Replaces the widget tree that the layer draws, and releases the old one.
Parameters:
root (trx.ui.Widget). The new tree.place (trx.ui.Placement or function, optional). Where the new tree goes, as trx.ui.layers.push takes it. The tree keeps the old placement where this is nil.Where a layer puts its tree within an area of the canvas. The tree takes a share of the room that it leaves free on each axis, and starts from the top left of the area where it is too large for it.
Properties:
canvas: any, optional. Whether the area is the whole canvas, or a signal that holds that value. By default, the area is trx.ui.safe_area_for the width of the tree, as the engine centers its own boxes.margin: any, optional. The room kept clear inside each edge of the area, in canvas units, or a signal that holds it. 0 by default.x: any, optional. How far across the free width the tree stands, from 0 against the left edge to 1 against the right edge, or a signal that holds it. 0.5 by default.y: any, optional. How far down the free height the tree stands, from 0 against the top edge to 1 against the bottom edge, or a signal that holds it. 0.5 by default.A layer drawn over the interface: one colour, or the frame as it was when the layer was made. Its opacity moves on a curve, and the layer paints itself, so the script that made it paints nothing. Fade layers stack in the order they were made, above every screen and below the console.
A backdrop layer is drawn under the interface instead, as the backdrop that the game draws behind its screens. Its opacity says how far the backdrop has come in: a picture comes in from black, and any other style from the frame behind it.
Properties:
holds_screen: boolean. Whether the engine waits to start its next screen, or to exit, while the layer is open. Setting it to false lets the engine go on while the layer stays drawn.is_open: boolean. Whether the layer is still drawn. (read-only)opacity: number. How opaque the layer is now, from 0 to 1. (read-only)Methods:
fadelayer:close()
Stops drawing the layer. Does nothing if the layer is already closed.
Returns: boolean. Whether the layer was open.
fadelayer:to(target, ticks, [options])
Moves the opacity to a target. The move takes the ticks it is given whatever
the fade settings are.
Parameters:
options (table, optional). How the move goes, and what happens when it ends.
Keys:
curve (function, optional). The curve of the move, one of trx.ui.ease. trx.ui.ease.linear by default.close (boolean, optional). Whether the layer closes once the move ends. false by default.on_done (function, optional). Runs once when the move ends, and not if another move or a close cuts it short. A move of no ticks made in a tick handler ends within that tick. It receives the layer.Returns: trx.ui.FadeLayer. The same layer.
How a widget stands among the others in its region.
Properties:
alone: boolean, optional. Whether the widget shows only while nothing else in its region does, as an arrow in a corner that a bar can take. false by default.order: number, optional. Where the widget stacks: a lower order stacks first, and widgets of the same order stack in the order they were placed. 0 by default.A screen that a script holds, which the definition receives. Each screen hands over a context of its own kind, which adds what that screen reports to what every screen has.
Properties:
is_held: boolean. Whether the script still holds the screen. (read-only)screen: trx.ui.Screen. The screen. (read-only)Methods:
screencontext:cancel()
Ends the screen, and closes its layers. A ring entry is put away, the pause
screen returns to the game, the quick save or load screen
closes, and the statistics screen ends as the player skipping it does. Does
nothing if the screen has already ended.
Returns: boolean. Whether the screen was still held.
screencontext:confirm()
Ends the screen as a choice that the player made, and closes its layers. A
ring entry leaves the ring, as an entry that the player uses does, a
combined entry is put away, and the statistics screen ends as the player
skipping it does. Does nothing if the screen has already ended.
Returns: boolean. Whether the screen was still held.
screencontext:on_end(callback)
Runs a function once the screen ends, for any reason, after its layers have
closed.
Parameters:
Example:
local black = trx.ui.layers.fade({ fill = trx.math.color("000000") })
ctx:on_end(function()
black:close()
end)
screencontext:push(settings)
Pushes a layer that belongs to the screen, with the settings that
trx.ui.layers.push takes. The layer closes when the screen ends.
Parameters:
settings (table). The layer settings.
Keys:
root (trx.ui.Widget). The widget tree to draw.place (trx.ui.Placement or function, optional). Where the tree goes. A function receives the width and the height that the tree measures, and returns the top left corner of the tree, in canvas units. The layer works the corner out again only when the tree's size, the room the interface lays out in, or a signal that the placement reads changes, and on every frame while the placement reads a trx.ui.Tween. The tree is centered in trx.ui.safe_area_for its width by default.modal (boolean, optional). Whether the layer reads input. A layer that reads input takes it from the layers below, and during play from the game. By default, a layer reads input when it has on_input. Set it to true for a layer that holds the input back without reading any.on_input (function, optional). Runs once a tick while the layer is the active layer. It receives the layer and a trx.ui.LayerKeys. An error closes the layer.on_close (function, optional). Runs once when the layer closes, for any reason. It receives the layer.Returns: trx.ui.StackLayer. The pushed layer.
The context of an entry of the inventory ring, for
trx.ui.Screen.RING_ENTRY, trx.ui.Screen.EXAMINE and
trx.ui.Screen.COMBINE.
Properties:
object: trx.catalog.objects. The entry that the player uses, examines or combines. (read-only)The context of the pause screen, for trx.ui.Screen.PAUSE.
Properties:
can_exit_to_title: boolean. Whether the screen can leave for the title screen. It cannot while an FMV plays. (read-only)Methods:
The context of the quick save or load screen, for
trx.ui.Screen.SAVE_LOAD.
Properties:
mode: trx.ui.MenuMode. Whether the screen opened for saving or for loading. (read-only)The context of the statistics screen, for trx.ui.Screen.STATS.
Properties:
background: string. The picture the screen stands on, as trx.ui.primitive.background takes it, or nil for none. (read-only)is_bare: boolean. Whether the screen is drawn bare, as plain lines of text without a frame. (read-only)is_final: boolean. Whether the screen shows the totals for the whole game rather than one level. (read-only)level: trx.game.Level. The level whose statistics the screen shows. The totals name the level that ended the game. (read-only)offers_save: boolean. Whether the screen offers a save before it ends, as trx.savegame.set_save_offer decides. A save made while the screen is held resumes after it. (read-only)The context of the TR3 globe, for trx.ui.Screen.GLOBE_SELECT.
Properties:
background: string. The picture the globe stands on, as trx.ui.primitive.background takes it, or nil for none. (read-only)The context of a screen that the game shows for a time, for
trx.ui.Screen.LEVEL_VIEW.
Properties:
The context of a picture, for trx.ui.Screen.PICTURE.
Properties:
background: string. The picture, as trx.ui.primitive.background takes it, or nil for none. (read-only)can_cross_fade_in: boolean. Whether the picture may fade in from the frame shown before it, rather than from black. (read-only)is_loading: boolean. Whether the picture shows while a level loads. (read-only)The context of the game's menu, for trx.ui.Screen.MENU.
Properties:
background: string. The picture the title's menu stands on, as trx.ui.primitive.background takes it, or nil for none. (read-only)is_live: boolean. Whether the title level runs behind the menu, in place of a picture. (read-only)key: trx.catalog.objects. The item that fits the keyhole or receptacle the menu opens at, whether Lara carries it or not, or nil where the menu opens elsewhere. (read-only)mode: trx.ui.MenuMode. What the menu opened for. (read-only)object: trx.catalog.objects. The entry the menu opens on, such as the crowbar a door asks for, or nil for none. (read-only)A number that moves to a target over some ticks.
Reading it while the interface is painted gives the value part way between two ticks, so that what it moves glides at any frame rate.
Methods:
Returns: number. The value.
tween:is_moving()
Whether the value is still on its way to its target, counted in whole
ticks, as the input a script reads each tick is.
Returns: boolean. true until the tick the move ends on.
tween:set(value)
Puts the value at once where it is told, and stops any move.
Parameters:
Returns: trx.ui.Tween. The same tween.
tween:target()
Where the value is going, or where it rests.
Returns: number. The target.
tween:to(target, ticks, [options])
Starts moving to a target from wherever the value is now.
Parameters:
options (table, optional). How the move goes.
Keys:
curve (function, optional). The curve of the move, one of trx.ui.ease. trx.ui.ease.linear by default. Any other function raises an error.delay (integer, optional). How many ticks to wait before the move starts. The value holds still while it waits, and is_moving reports true. 0 by default.Returns: trx.ui.Tween. The same tween.
A reusable UI element drawn over the game.
A widget holds its own state. Every setting that holds a value, rather than
a widget or a function, also takes a signal that holds the value. The widget
remeasures only when a signal that it read while measuring changes, and
when the room the interface lays out in changes. A trx.ui.Tween moves
between ticks, so a widget reads one only while it paints, and reading one
while it measures raises an error.
A widget is in one place at a time: inside another widget, in a region or as the root of a layer. Using it in a second place is an error. Releasing a widget ends it and every widget under it, and using a released widget is an error.
Methods:
widget:is_visible()
Returns whether the widget participates in layout.
A widget that is not visible keeps no room and leaves no gap.
Returns: boolean. Whether it draws.
widget:measure()
How much room the widget wants.
Returns:
widget:paint(x, y, w, h)
Draws the widget in an assigned box.
trx.ui.regions.place calls this automatically. Custom layout code can call
it during trx.ui.on_paint.
Parameters:
widget:release()
Ends the widget and every widget under it: removes the widget from its
region if it is placed, and detaches each one from its signals. Does nothing
if the widget is already released.
Signals keep references to their listeners. Release temporary widgets when they are no longer needed. A widget that another widget or a layer holds is released with its holder, and releasing it directly is an error. A widget that a level script placed is released when the level ends.
widget:wake()
Invalidates the widget's cached size manually.
Returns: trx.ui.Widget. The same widget.
A row of items turned to the one in the middle.
Methods:
carousel:is_sliding()
Returns whether the row is still sliding to the selected item.
Returns: boolean. Whether it slides.
carousel:turn(by)
Selects the item some places away, and slides the row that way, wrapping
round at either end. Setting the selected signal slides the row the short
way round, which has no direction where the row holds two items.
Parameters:
Example:
carousel:turn(-1)
One entry of a trx.ui.widgets.List.
Properties:
right: string or trx.locale.Text, optional. Text drawn against the right edge. The main text is then drawn against the left edge.rule: boolean, optional. Whether a line separates the row from the row above it.text: string or trx.locale.Text. The text. It is centered unless the row has a right part.A column of rows that the player picks one entry from. The row under the
cursor is drawn in a frame, or in the picked colour while
trx.ui.frames_shown is off. Arrows show where the list runs past the rows
it shows.
Methods:
list:control(keys)
Reads the menu keys for one tick. Up and down move the cursor, confirm
picks the row under it, and back reports that the player backed out. Uses up
only the presses that it reads.
Parameters:
keys (trx.ui.LayerKeys). The input of the layer the list is on.Returns:
nil. The picked row, or nil where none was picked.list:move(step)
Moves the cursor by a number of rows. Past either end, the cursor goes to
the other end where the ui.enable_wraparound setting is on, and stays
otherwise.
Parameters:
Returns: boolean. Whether the cursor moved.
list:select(index)
Moves the cursor to a row. Does nothing for an index out of range.
Parameters:
list:selection()
Returns the index of the row under the cursor.
Returns: integer or nil. The index, or nil for an empty list.
list:set_rows(rows)
Replaces the rows. The cursor stays on the same index where it can.
Parameters:
rows (a list of trx.ui.ListRow). The new rows.trx.ui.signals
What the interface tells a script about the room that it lays out in.
trx.ui.layers
Draws screens of widgets over the rest of the interface.
A layer holds one widget tree, such as a menu or a question. Layers are kept
in a stack. Each layer draws over the layers below it and over the widgets
placed with trx.ui.regions.place. The engine interface still draws over
all of them.
Only the active layer, the top layer that reads input, reads the player's
input. The layers below it read nothing until it closes. While a layer that
reads input is open during play, the layers take the devices from the game
with trx.input.grab: Lara does not move, and the game's own keys, such as
the pause key, do nothing. The level keeps running.
A layer that a level script pushes closes when the level ends.
trx.ui.primitive
Low-level drawing calls and layout reservations.
Use trx.ui.widgets for normal UI. Use these primitives only when building
a custom widget. Primitive drawing does not affect region layout unless code
reserves space first.
Drawing calls are available only during trx.ui.on_paint. They
report an error at any other time.
trx.ui.regions
Places script widgets on the screen.
The screen has nine regions. The shipped scripts place the bars, the
overlay text and the inventory ring hints in them, and dialogs keep clear
of them. A widget placed in a region stacks with the others there, in the
order that place.options gives.
Place a widget once when the script loads. Use signals when the widget must change later.
trx.ui.screens
Lets a script draw an engine screen in place of the engine.
Define a screen with define. When the engine opens the
screen, it calls the function that the definition gives. The function pushes
layers through the context it receives and returns the first one. The engine
then draws nothing for the screen and reads no input for it, until the
script ends the screen through the context.
The screen also ends when the layer that the definition returned closes, for any reason, and the screen's other layers close with it. A layer that raises an error therefore gives the screen back to the engine.
While a script holds a screen, a game-flow command such as
trx.savegame.load waits for the screen to end. In the inventory ring, the
ring spins out before the command runs.
trx.ui.ease
Curves that shape how a trx.ui.Tween moves. Each takes how far the move
has gone in time, from 0 to 1, and returns how far the value has gone.
trx.ui.widgets
The widgets a script builds its screen from.
A widget is created once and kept. Give it signals instead of fixed values, and it remeasures when they change.
Put a widget on screen with trx.ui.regions.place.
trx.ui.on_reserve(callback)
Happens while the interface is built, once for each region. The handler
reserves room in the region it is handed with trx.ui.primitive.reserve,
and paints into that room later during trx.ui.on_paint.
It happens anywhere the game draws its interface, including fades, FMVs and normal play, and it follows the frame rate rather than the game clock.
Parameters:
callback (function). What to run for each region.
Called with:region (trx.ui.Region). The region being built.Returns: trx.events.Listener. The attached handler.
Example:
local slot = nil
trx.ui.on_reserve(function(region)
if region == trx.ui.Region.TOP_CENTER then
local w, h = trx.ui.primitive.measure_text("hello")
slot = trx.ui.primitive.reserve(region, w, h)
end
end)
trx.ui.on_paint(function()
local x, y = trx.ui.primitive.slot_box(slot)
if x ~= nil then
trx.ui.primitive.text("hello", x, y)
end
end)
trx.ui.on_paint(callback)
Happens once the interface is laid out and before it is drawn, under the
engine interface. The boxes reserved during trx.ui.on_reserve are known by
then, and the primitive drawing calls work here and nowhere else. The
console still draws over what is painted here.
Parameters:
Returns: trx.events.Listener. The attached handler.
trx.ui.safe_area_for(width)
The part of the canvas that a box of the given width, centered, is free to
take. Unlike trx.ui.safe_area, an edge of the interface takes room from it
only if the box is wide enough to reach that edge, so a narrow box ignores
what sits in a corner, such as the FPS counter.
Parameters:
Returns: trx.ui.Area. The room the box has.
Example:
local area = trx.ui.safe_area_for(200)
trx.ui.is_ps1_bar(type)
Whether a bar of the given type takes the PS1 look, which the player picks
in the settings and which decides which of its colors applies.
Parameters:
type (trx.ui.BarType). The bar.Returns: boolean. True for the PS1 look.
trx.ui.interpolation_rate()
Returns the interpolation factor of the frame being drawn between the last
two ticks: 0 at the earlier tick and 1 at the later one.
trx.ui.Tween reads it to move smoothly between ticks.
Returns: number. The factor, from 0 to 1.
trx.ui.input_hint_text(input, [words])
The text that shows the keys bound to one or more input roles, as the game
shows them, followed by some words. The keys follow the player's bindings
and controller.
Parameters:
input (trx.ui.Inputs). The role, or the roles shown side by side.words (string, optional). What the keys do. A trx.locale.Text makes the result follow the player's language.Returns: string. The text.
Example:
local text = trx.ui.input_hint_text(trx.input.Role.MENU_CONFIRM, "Use")
trx.ui.layers.push(settings)
Puts a layer on top of the stack.
The layer reads no input on the tick it is pushed, because the press that opened it is often still active.
Parameters:
settings (table). The layer settings.
Keys:
root (trx.ui.Widget). The widget tree to draw.place (trx.ui.Placement or function, optional). Where the tree goes. A function receives the width and the height that the tree measures, and returns the top left corner of the tree, in canvas units. The layer works the corner out again only when the tree's size, the room the interface lays out in, or a signal that the placement reads changes, and on every frame while the placement reads a trx.ui.Tween. The tree is centered in trx.ui.safe_area_for its width by default.modal (boolean, optional). Whether the layer reads input. A layer that reads input takes it from the layers below, and during play from the game. By default, a layer reads input when it has on_input. Set it to true for a layer that holds the input back without reading any.on_input (function, optional). Runs once a tick while the layer is the active layer. It receives the layer and a trx.ui.LayerKeys. An error closes the layer.on_close (function, optional). Runs once when the layer closes, for any reason. It receives the layer.Returns: trx.ui.StackLayer. The pushed layer.
Example:
local layer = trx.ui.layers.push({
root = trx.ui.widgets.Label({ text = "Paused" }),
on_input = function(layer, keys)
if keys:pressed(trx.input.Role.MENU_BACK) then
layer:close()
end
end,
})
trx.ui.layers.fade(settings)
Puts up a fade layer, on top of the others drawn where it is. A level
script's layer closes when the level ends.
Parameters:
settings (table). The layer settings.
Keys:
fill (trx.math.Color, optional). The colour that the layer holds.snapshot (boolean, optional). Whether the layer holds the frame on screen now, in place of a colour.backdrop (string, optional). The backdrop style that the layer holds, in place of a colour, by the names that the ui.stats_background_style setting takes.path (string, optional). The picture of an image backdrop, as trx.ui.primitive.background takes it.opacity (number, optional). How opaque the layer starts, from 0 to 1. 1 by default.on_close (function, optional). Runs once when the layer closes, for any reason. It receives the layer.holds_screen (boolean, optional). Whether the engine waits to start its next screen, or to exit, while the layer is open. false by default.over_console (boolean, optional). Whether the layer is drawn over the console too, as the fade to black as the game exits is. false by default.Returns: trx.ui.FadeLayer. The layer.
Example:
local black = trx.ui.layers.fade({ fill = trx.math.color("000000"), opacity = 0 })
black:to(1, 15, { close = true })
trx.ui.layers.active()
Returns the active layer: the top layer that reads input.
Returns: trx.ui.StackLayer or nil. The layer, or nil if no layer reads input.
trx.ui.layers.count()
Returns how many layers are on the stack.
Returns: integer. The number of layers.
trx.ui.primitive.reserve(region, w, h)
Reserves space in a region and returns a slot for it.
The reservation is stacked with the engine UI in that region. Reserve space
during trx.ui.on_reserve, then read the assigned box during
trx.ui.on_paint.
A slot is valid only for the scene that created it.
Parameters:
region (trx.ui.Region). Which region to keep room in.w (number). How wide, in canvas units.h (number). How tall, in canvas units.Returns: integer. The slot.
trx.ui.primitive.slot_box(slot)
Returns the box assigned to a reservation by the last layout.
Parameters:
Returns:
nil. The left edge, or nil when the slot is no longer valid.trx.ui.primitive.measure_text(text, [scale])
Measures one line of text. Available at any time.
Parameters:
text (string or trx.locale.Text). What to measure.scale (number, optional). Multiplies the text size. 1.0 by default.Returns:
trx.ui.primitive.wrap_text(text, width, [scale])
Breaks text into lines that fit a width, the way the game wraps its own
text. Available at any time.
Parameters:
text (string or trx.locale.Text). What to wrap.width (number). The widest a line may be, in canvas units.scale (number, optional). Multiplies the text size. 1.0 by default.Returns: string. The text with line breaks where the lines end.
Example:
local lines = trx.ui.primitive.wrap_text(description, 300)
trx.ui.primitive.text(text, x, y, [scale], [z])
Draws one line of text on the canvas.
Parameters:
text (string or trx.locale.Text). What to draw.x (number). The left edge.y (number). The top edge.scale (number, optional). Multiplies the text size.z (integer, optional). The draw order.trx.ui.primitive.to_screen(length)
Converts a canvas length to screen pixels.
The canvas is a fixed 640x480 grid, and the screen size depends on the
player settings and window. Use this with to_canvas when
geometry must align to whole screen pixels, such as an even border.
Parameters:
Returns: number. The same length in screen pixels.
trx.ui.primitive.to_canvas(pixels)
Converts a screen-pixel length to canvas units.
Use this with to_screen when geometry must align to whole
screen pixels.
Parameters:
Returns: number. The same length in canvas units.
trx.ui.primitive.horizontal_line(x0, x1, y, [z])
Draws a horizontal rule in the selected menu style.
Parameters:
trx.ui.primitive.panel(x, y, z, w, h, style)
Draws the box the game draws behind a dialog, in the style the player chose.
The look follows the menu style setting, so a panel drawn this way matches
the game's own dialogs rather than standing apart from them. Nothing is
drawn while trx.ui.frames_shown is off.
Parameters:
x (number). The left edge.y (number). The top edge.z (integer). The draw order.w (number). The width.h (number). The height.style (trx.ui.FrameStyle). Which of the game's frames to draw.trx.ui.primitive.quad(x, y, z, w, h, color)
Draws a rectangle of one color.
Parameters:
x (number). The left edge.y (number). The top edge.z (integer). The draw order.w (number). The width.h (number). The height.color (trx.math.Color or table). What color to fill it with: a trx.math.Color, or a table of r, g, b and a channels from 0 to 255. The color is opaque where a is absent.trx.ui.primitive.line(x0, y0, x1, y1, z, width, color)
Draws a straight line of one color between two points, with smooth edges.
Parameters:
x0 (number). Where the line starts across.y0 (number). Where the line starts down.x1 (number). Where the line ends across.y1 (number). Where the line ends down.z (integer). The draw order.width (number). How thick the line is.color (trx.math.Color or table). What color to draw it in, in either form that quad takes.trx.ui.primitive.gradient_quad(x, y, z, w, h, tl, tr, bl, br)
Draws a rectangle whose corners each carry a color.
Parameters:
x (number). The left edge.y (number). The top edge.z (integer). What to draw in front of.w (number). The width.h (number). The height.tl (trx.math.Color or table). The top-left color, in either form that quad takes.tr (trx.math.Color or table). The top-right color, in either form that quad takes.bl (trx.math.Color or table). The bottom-left color, in either form that quad takes.br (trx.math.Color or table). The bottom-right color, in either form that quad takes.trx.ui.primitive.image(path, x, y, w, h, [opacity])
Draws an image file in a box on the canvas.
The image is looked for where the game keeps its images, and stretches to fill the box, so a box of the image's own shape keeps that shape. The image draws under everything else the canvas holds, whatever order the calls come in.
Returns whether the game has such an image, so a script can leave the space alone where it does not.
Parameters:
path (string). The image file, named from the images directory.x (number). The left edge.y (number). The top edge.w (number). The width.h (number). The height.opacity (number, optional). How solid the image is, from 0 to 1. 1 by default.Returns: boolean. Whether the image was there to draw.
Example:
trx.ui.primitive.image("uklogo.pak", 64, 0, 512, 256)
trx.ui.primitive.image_size(path)
Reports the size of an image file, in pixels.
Where the game keeps versions of the image for other screen shapes, the size is that of the version the screen draws. Use it to give a box the shape of the image it holds.
Parameters:
Returns:
nil. The width, or nil where the game has no such image.nil. The height, or nil where the game has no such image.Example:
local w, h = trx.ui.primitive.image_size("uklogo.pak")
trx.ui.primitive.sprite_count(object)
Reports how many sprites an object has.
An object the level did not load has none, and a model has none as well. Use
this function to check whether sprite has anything to
draw.
Parameters:
object (trx.catalog.objects). The sprite object to count.Returns: integer. How many sprites it has.
trx.ui.primitive.sprite_bounds(object, sprite_num)
Reports the edges of one sprite of an object, in canvas units at a scale of
one.
The edges sit around the point the sprite is drawn at, so both left and top are usually negative. Multiply them by the scale the sprite is drawn at.
Raises where the level did not load the object, so check
trx.objects.get(object).loaded first.
Parameters:
object (trx.catalog.objects). The sprite object to read from.sprite_num (integer). Which sprite of the object to read, counted from 0.Returns:
trx.ui.primitive.mesh_bounds(object)
Reports the box a model occupies, from the first frame of its first
animation.
The box sits around the point the model is drawn at, so the low edges are usually negative. A script fits a model into a box of its own by comparing the two.
Returns nothing where the object carries no model, which is how a script
tells whether it can draw one at all. Raises where the level did not load
the object, so check trx.objects.get(object).loaded first.
Parameters:
object (trx.catalog.objects). The model object to measure.Returns:
nil where the object carries no model.trx.ui.primitive.model(object, x, y, w, h, [opts])
Draws an object's model in a box on the canvas, fitted into the box. The
model stands where it is painted among the rest of the interface: over what
was painted before it, under what is painted after.
Draws nothing where the level did not load the object, or where the object carries no model.
Parameters:
object (trx.catalog.objects). The object to draw.
opts (table, optional). How to turn it, which meshes to draw and how to light them.
Keys:
rot (trx.math.Rot, optional). How far to turn the model. Not turned by default.mesh_mask (integer, optional). Which of its meshes to draw, one bit each. Every mesh by default.light (table, optional). The light to draw it in. The light the game holds up a pickup in by default.held (boolean, optional). Whether to tilt and turn it first as the game holds up a pickup, which shows its face. true by default; false draws it as it was built.tilt (trx.math.Angle, optional). How far to tilt it towards the viewer before anything else, about the screen's horizontal axis, as a camera looking down on it would. Not tilted by default.Example:
trx.ui.primitive.model(trx.catalog.objects.small_medipack_option,
100, 50, 64, 48, { rot = { x = 0, y = 30 * trx.math.DEG_1, z = 0 } })
trx.ui.primitive.world_model(object, opts)
Draws an object's model where it stands in a world of its own, as that
world's camera sees it over the whole canvas: placed by moves and turns
applied in order, the way the engine places a model, so that a script can
show a model as the game would have shown it. It stands behind the whole
interface, over what went behind it before, such as a background.
Draws nothing where the level did not load the object, or where the object carries no model.
Parameters:
object (trx.catalog.objects). The object to draw.
opts (table). Where it stands, the camera that sees it, and its light.
Keys:
camera (table). The camera that sees the model.pose (a list of table). The steps that place the model, applied in order from the world's origin, up to sixteen.frame (integer, optional). The frame of the model's first animation to pose it in, counted from 0. The first by default.next_frame (integer, optional). The frame to blend towards. The same frame by default.blend (number, optional). How far to blend towards the next frame, from 0 to 1. 0 by default.bones (a list of table, optional). Turns that bones take on top of the frame, up to eight.at_pivot (boolean, optional). Whether to draw the model about its pivot, without the offset its frame stands it at. false by default.opacity (number, optional). How solid the model is, from 0 for unseen to 1. 1 by default.mesh_mask (integer, optional). Which of its meshes to draw, one bit each. Every mesh by default.mesh_opacity (table, optional). How solid to draw some of its meshes, from 0 to 1, keyed by the mesh counted from 0. A mesh not named is solid.light (table, optional). The light to draw it in, with its directions in the model's world. A plain white light by default.trx.ui.primitive.darken(opacity)
Darkens the screen behind the whole interface, edge to edge, as the game
darkens it behind a menu and fades it to black. It goes over what went
behind the interface before it, such as a background or a model in a world
of its own, and under the whole interface.
Parameters:
trx.ui.primitive.backdrop(style, opacity, [path])
Draws a backdrop behind the whole interface, as the game draws the ones
behind its menus, part way in by the opacity. It goes under any model in a
world of its own drawn after it, as the inventory ring's models stand on
their backdrop.
Parameters:
style (string). The backdrop style, by the names that the ui.inventory_background_style setting takes.opacity (number). How far it has come in, from 0 for not at all to 1.path (string, optional). The picture of an image backdrop, as background takes it.Example:
trx.ui.primitive.backdrop("transparent", 0.5)
trx.ui.primitive.background([path], [mono], [dim])
Draws an image behind the whole interface, as the game draws the pictures
behind its screens, fitted to the screen's shape and darkened by the dim.
Without an image, or where it does not exist, the screen behind the
interface is black. The game's scene behind the canvas is drawn over.
Parameters:
path (string, optional). The image file, named from the images directory, or as a screen reports it.mono (boolean, optional). Whether to draw it without its colour.dim (number, optional). How much to darken it, from 0 for not at all to 1 for black. Not darkened by default.Returns: boolean. Whether the image exists.
Example:
trx.ui.primitive.background("india.webp", true, 0.5)
trx.ui.primitive.sprite(object, sprite_num, x, y, z, scale, color)
Draws one sprite of an object on the canvas.
Raises where the level did not load the object, so check
trx.objects.get(object).loaded first.
Parameters:
object (trx.catalog.objects). The sprite object to draw from.sprite_num (integer). Which sprite of the object to draw, counted from 0.x (number). The left edge.y (number). The top edge.z (integer). The draw order.scale (number). Multiplies the sprite size. At 1 the sprite draws at its own size on the canvas.color (trx.math.Color or table). What color to tint it with, in either form that quad takes.Example:
trx.ui.primitive.sprite(
trx.catalog.objects.assault_digits, 3, 100, 20, 0, 1,
trx.math.color("ffffff"))
trx.ui.primitive.sprite_rect(object, sprite_num, x, y, z, w, h, color)
Draws one sprite of an object stretched over a box. Unlike
sprite, it ignores the edges the sprite declares, which
suits sprites that carry none, as the TR4 interface sprites do.
Parameters:
object (trx.catalog.objects). The sprite object to draw from.sprite_num (integer). Which sprite of the object to draw, counted from 0.x (number). The left edge.y (number). The top edge.z (integer). The draw order.w (number). The width.h (number). The height.color (trx.math.Color or table). What color to tint it with, in either form that quad takes.trx.ui.primitive.gradient_sprite(object, sprite_num, x, y, z, scale, tl, tr, bl, br)
Draws one sprite of an object, with a color at each corner.
Raises where the level did not load the object, so check
trx.objects.get(object).loaded first.
Parameters:
object (trx.catalog.objects). The sprite object to draw from.sprite_num (integer). Which sprite of the object to draw, counted from 0.x (number). The left edge.y (number). The top edge.z (integer). The draw order.scale (number). Multiplies the sprite size. At 1 the sprite draws at its own size on the canvas.tl (trx.math.Color or table). The top-left color, in either form that quad takes.tr (trx.math.Color or table). The top-right color, in either form that quad takes.bl (trx.math.Color or table). The bottom-left color, in either form that quad takes.br (trx.math.Color or table). The bottom-right color, in either form that quad takes.trx.ui.regions.place(region, widget, [options])
Places a widget in a region.
If the region argument is a signal, the widget moves when the signal changes. Placing a widget that is already placed moves it.
Parameters:
region (any). The target region, or a signal that holds one.widget (trx.ui.Widget). The widget to place.options (trx.ui.regions.place.options, optional). How it stands among the others.Example:
trx.ui.regions.place(trx.ui.Region.TOP_LEFT, health_bar)
trx.ui.regions.remove(widget)
Takes a widget out of its region and keeps it, so that it can be placed
again.
To be done with a widget, release it with trx.ui.Widget:release instead,
which takes it out of its region as well. Widgets that a level script placed
are released when the level ends.
Parameters:
widget (trx.ui.Widget). The widget to remove.Returns: boolean. Whether the widget was in a region.
trx.ui.screens.define(screen, open, [options])
Defines how a script draws a screen.
The function receives a trx.ui.ScreenContext when the engine opens the
screen. It pushes the screen's layers through the context and returns the
first one. Returning nothing leaves the screen to the engine.
A screen has one definition. Defining it again is an error unless the
options say override = true. The new definition then replaces the old one,
which comes back when a level script's definition goes with its level.
Parameters:
screen (trx.ui.Screen). The screen.
options (table, optional). The definition options.
Keys:
object (trx.catalog.objects, optional). The ring entry that the definition draws, for trx.ui.Screen.RING_ENTRY. Without it, the definition draws every entry that has no definition of its own.override (boolean, optional). Whether to replace a definition that exists. false by default.Example:
trx.ui.screens.define(trx.ui.Screen.RING_ENTRY, function(ctx)
return ctx:push({
root = trx.ui.widgets.Label({ text = "North" }),
on_input = function(_, keys)
if keys:pressed(trx.input.Role.MENU_BACK) then
ctx:cancel()
end
end,
})
end, { object = trx.catalog.objects.COMPASS_OPTION })
trx.ui.screens.open(screen, fields, [on_end])
Opens a screen from a script, as the engine opens one, with its definition
drawing it. This is how a menu that a script draws opens what an entry
leads to, such as trx.ui.Screen.EXAMINE.
The fields are what the screen reports to its definition, such as the
object of a ring entry's screens. The function given runs once the screen
ends, after its layers have closed, and is told whether it ended with
trx.ui.ScreenContext:confirm.
Parameters:
screen (trx.ui.Screen). The screen.fields (table). What the screen reports to its definition.on_end (function, optional). Runs once the screen ends, with whether it ended confirmed.Returns: trx.ui.ScreenContext or nil. The screen's context, or nil where no definition draws the screen, in which case the function given never runs.
Example:
trx.ui.screens.open(trx.ui.Screen.EXAMINE, { object = object }, function(confirmed)
trx.log.info(confirmed and "confirmed" or "put away")
end)
trx.ui.ease.linear(ratio)
The same pace throughout.
Parameters:
Returns: number. How far the value has gone.
trx.ui.ease.quad_in(ratio)
Slow to start.
Parameters:
Returns: number. How far the value has gone.
trx.ui.ease.quad_out(ratio)
Slow to finish.
Parameters:
Returns: number. How far the value has gone.
trx.ui.ease.quad_in_out(ratio)
Slow at both ends, fastest in the middle.
Parameters:
Returns: number. How far the value has gone.
trx.ui.tween([value])
Creates a tween that rests at a value.
Parameters:
Returns: trx.ui.Tween. The tween.
trx.ui.widgets.Bar(settings)
One of the game's bars, drawn with the player's bar settings.
The bar uses the same theme, border, and fill bands as the engine UI. Use a signal for a fill value that changes.
Parameters:
settings (table). The bar settings.
Keys:
type (any). The trx.ui.BarType theme to use, or a signal that holds it.value (any). The fill amount from 0 to 1, or a signal that holds it.w (any, optional). The width, in canvas units at the default bar size, or a signal that holds it. The size its look gives it by default.h (any, optional). The height, in canvas units at the default bar size, or a signal that holds it. The size its look gives it by default.smooth (any, optional). Whether the fill shades one band into the next, or a signal that holds that value. The player's smooth bars setting by default.preview (any, optional). Whether the bar takes the size of the text around it rather than the player's bar size and the size its style gives it, as a bar shown beside its setting does, or a signal that holds that value. false by default.Returns: trx.ui.Widget. The bar.
trx.ui.widgets.Carousel(settings)
A row of items turned to the one in the middle, as the inventory ring
offers what to combine an entry with. The item in the middle is drawn at its
own size, those beside it smaller, and the rest out of sight. Setting the
selected signal slides the row there, the short way round.
Parameters:
settings (table). The carousel settings.
Keys:
items (a list of any). What the row holds, in order.selected (trx.signal.Signal). The place in the row, counted from 1, of the item in the middle. Setting it slides the row there.build (function). Makes the widget for an item. It receives the item and its place in the row, and returns a widget.w (any). The width of the row, in canvas units at the default text size, or a signal that holds it.h (any). The height of the row, in canvas units at the default text size, or a signal that holds it.spacing (any). How far apart the middles of two neighbours stand, in canvas units at the default text size, or a signal that holds it.side_size (any, optional). How large the items beside the middle are drawn, as a share of their own size, or a signal that holds it. 0.6 by default.ticks (any, optional). How many ticks a slide takes, or a signal that holds it. 8 by default.curve (any, optional). The curve of a slide, one of trx.ui.ease, or a signal that holds it. trx.ui.ease.quad_in_out by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Carousel. The carousel.
Example:
local selected = trx.signal.new(1)
trx.ui.widgets.Carousel({
items = objects,
selected = selected,
build = function(object)
return trx.ui.widgets.Model({ object = object, w = 100, h = 120 })
end,
w = 260,
h = 150,
spacing = 90,
})
trx.ui.widgets.Custom(settings)
A widget that measures and draws itself through functions the script gives.
Use it for drawing that the other widgets do not cover. The widget
remeasures when a signal that measure read changes.
Parameters:
settings (table). The widget settings.
Keys:
measure (function). Returns the width and the height the widget wants, in canvas units.paint (function). Draws the widget with trx.ui.primitive. It receives the left edge, the top edge, the width and the height of the box the widget was given.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The widget.
Example:
local mark = trx.ui.widgets.Custom({
measure = function()
return 8, 8
end,
paint = function(x, y, w, h)
trx.ui.primitive.quad(x, y, 0, w, h, trx.math.color("#ffffff"))
end,
})
trx.ui.widgets.Digits(settings)
A line of text drawn from an object's sprites, one sprite per character.
The object supplies the ten digits, then a colon, a full stop, a T and an
s, in that order, which is how the assault course digits are laid out. A
space and a dash move the pen without drawing.
The widget measures nothing where the level did not load the object, so a script can keep it on screen for a level that has no digits.
Parameters:
settings (table). The digit settings.
Keys:
object (any). The sprite object to draw the characters from, or a signal carrying it.text (any). The text, or a signal carrying it.color (any). What color to draw the characters in, or a signal carrying one.color_bottom (any, optional). The color the characters fade to down their height. The main color by default, which draws them flat.mark_color (any, optional). What color to draw the T in. The main color by default.mark_color_bottom (any, optional). The color the T fades to. Its own color by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The digits.
Example:
trx.ui.widgets.Digits({
object = trx.catalog.objects.assault_digits,
text = timer:map(format_time),
color = trx.math.color("ffffff"),
})
trx.ui.widgets.Image(settings)
A picture from an image file, at a size the script gives.
Give the width, the height, or both. Where one of them is left out, it follows the other in the image's own shape. The widget keeps its room even where the game ships no such image, so a screen built around it does not move when the image is missing; a size left out is then 0.
Parameters:
settings (table). The image settings.
Keys:
path (any). The image file, named from the images directory, or a signal carrying it.w (any, optional). The width, in canvas units, or a signal that holds it. Without it, the width follows the height in the image's own shape.h (any, optional). The height, in canvas units, or a signal that holds it. Without it, the height follows the width in the image's own shape.opacity (any, optional). How solid the image is, from 0 to 1, or a signal that holds that value. 1 by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The image.
Example:
local logo = trx.ui.widgets.Image({ path = "logo.webp", w = 512 })
trx.ui.widgets.InputHint(settings)
The keys bound to an input role, as the game shows them, and what they do.
The keys follow the player's bindings and controller.
Parameters:
settings (table). The hint settings.
Keys:
input (any). The input role whose keys to show, a list of roles shown side by side, or a signal carrying either.text (any, optional). What the keys do, as a string or a trx.locale.Text, or a signal carrying either.scale (any, optional). Multiplies the text size, or a signal that holds it. 1.0 by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The hint.
Example:
trx.ui.widgets.InputHint({
input = trx.input.Role.MENU_BACK,
text = trx.locale.text("general/actions/cancel"),
})
trx.ui.widgets.Label(settings)
A line of text. Use a signal for text that changes. A trx.locale.Text
follows the player's language without one.
Parameters:
settings (table). The label settings.
Keys:
text (any). The text, a trx.locale.Text, or a signal carrying either.scale (any, optional). Multiplies the text size, or a signal that holds it. 1.0 by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The label.
trx.ui.widgets.Resize(settings)
Gives a child widget an explicit size.
Parameters:
settings (table). The resize settings.
Keys:
child (trx.ui.Widget). The child widget.w (any, optional). The width, in canvas units, or a signal that holds it. Its own by default.h (any, optional). The height, in canvas units, or a signal that holds it. Its own by default.scaled (any, optional). Whether w and h are at the default text size, and follow the text scale as Spacer does, or a signal that holds that value. false by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The resized widget.
trx.ui.widgets.Blank(settings)
Leaves a child widget blank while a condition holds: it keeps its room, so
nothing around it moves, and draws nothing.
Parameters:
settings (table). The settings.
Keys:
child (trx.ui.Widget). The child widget.when (any). Whether to leave the child blank, or a signal that holds that value.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The widget.
Example:
trx.ui.widgets.Blank({ when = ~can_step_left, child = left_arrow })
trx.ui.widgets.Spacer([settings])
Keeps empty room, which follows the text scale the same way the widgets
beside it do. With no size, it takes no room, which suits a layer that shows
nothing yet.
Parameters:
settings (table, optional). The spacer settings.
Keys:
w (any, optional). The width, in canvas units at the default text size, or a signal that holds it. 0 by default.h (any, optional). The height, in canvas units at the default text size, or a signal that holds it. 0 by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The spacer.
Example:
trx.ui.widgets.Stack({
children = { title, trx.ui.widgets.Spacer({ h = 5 }), body },
})
trx.ui.widgets.Pad(settings)
Keeps a margin around a child widget.
The margin is in canvas units at the default text size, and follows the text scale the same way the widgets inside it do.
Parameters:
settings (table). The padding settings.
Keys:
child (trx.ui.Widget). The child widget.x (any, optional). The margin at the left and the right, or a signal that holds it. 0 by default.y (any, optional). The margin at the top and the bottom, or a signal that holds it. 0 by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The padded widget.
trx.ui.widgets.Frame(settings)
Draws one of the game's frames behind a child widget.
The frame takes the whole box the child asks for, so pad the child where the
text would otherwise sit against the edge. While trx.ui.frames_shown is
off, no frame is drawn, and the child of the box around the option the
player is on draws its text in the picked colour instead.
Parameters:
settings (table). The frame settings.
Keys:
child (trx.ui.Widget). The child widget.style (any, optional). Which trx.ui.FrameStyle to draw, or a signal that holds it. false draws no frame, as for a row that the cursor is not on. The dialog box by default.z (any, optional). The draw order, or a signal that holds it. 160 by default, which is behind text.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The framed widget.
trx.ui.widgets.Fit(settings)
Shrinks a child widget until it is within the screen.
Text keeps the size the player chose while it fits, and everything below this widget is drawn smaller where it does not. A dialog that has to hold a fixed body on a small screen wants this; a line of text that can simply wrap does not.
Parameters:
settings (table). The fit settings.
Keys:
child (trx.ui.Widget). The child widget.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The fitted widget.
trx.ui.widgets.Stack(settings)
Lays widgets out one after another.
Widgets that are not shown take no room and leave no gap.
Parameters:
settings (table). The stack settings.
Keys:
children (a list of trx.ui.Widget). The widgets, in the order they are laid out.orientation (any, optional). The trx.ui.Orientation to lay out in, or a signal that holds it. Vertical by default.spacing (any, optional). The gap between one and the next, in canvas units at the default text size, or a signal that holds it. 0 by default.align (any, optional). The trx.ui.HAlign, or a signal that holds it, that says where the children sit across the width. In a vertical stack, it places each narrower child. In a horizontal stack, it places the whole row, and trx.ui.HAlign.DISTRIBUTE spreads the children out. Left by default.v_align (any, optional). The trx.ui.VAlign, or a signal that holds it, that says where the children sit down the height. In a horizontal stack, it places each shorter child. In a vertical stack, it places the whole column, and trx.ui.VAlign.DISTRIBUTE spreads the children out. Top by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The stack.
trx.ui.widgets.List(settings)
A column of rows that the player picks one entry from. Its lengths are in
canvas units at the default text size.
The list keeps the cursor and the scroll position. Read the player's input
with trx.ui.List:control from the input callback of the layer that holds
the list.
Parameters:
settings (table). The list settings.
Keys:
rows (a list of trx.ui.ListRow, optional). The rows. None by default.page_rows (any, optional). How many rows to show at once, or a signal that holds that value. Every row by default.reserve (any, optional). Whether to keep room for the rows of a page when the list holds fewer, or a signal that holds that value. false by default.min_w (any, optional). The least width, in canvas units at the default text size, or a signal that holds it.row_pad (any, optional). The room on each side of a row's text, or a signal that holds it. 4 by default.row_spacing (any, optional). The gap between two rows, or a signal that holds it. 3 by default.row_height (any, optional). The height of a row, or a signal that holds it. 15 by default.hint_height (any, optional). The height of the arrows that say the list runs past its rows, or a signal that holds it. 7 by default.hint_color (any, optional). The colour of those arrows, as the text markup names a colour, or a signal that holds it. The colour text is drawn in where it names none by default.rule_overhang (any, optional). How far a rule between rows reaches past each side of the list, or a signal that holds it. 7 by default.frame_overhang (any, optional). How far the frame of the row under the cursor reaches above and below the row, or a signal that holds it. 0 by default.scroll_hints (any, optional). Whether to show arrows where the list runs past its rows, or a signal that holds that value. true by default.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.List. The list.
Example:
local list = trx.ui.widgets.List({
rows = { { text = "Yes" }, { text = "No" } },
})
trx.ui.widgets.Model(settings)
An object's model, fitted into a box and lit as the game lights a model held
up to the camera.
Parameters:
settings (table). The model settings.
Keys:
object (any). The object to draw, or a signal carrying it.w (any). The width of its box, in canvas units at the default text size, or a signal that holds it.h (any). The height of its box, in canvas units at the default text size, or a signal that holds it.size (any, optional). How large to draw the model within its box, from 0 to 1, or a signal or trx.ui.Tween carrying it. The box keeps its room whatever the size. 1 by default.rot_x (any, optional). How far to tilt the model, or a signal or trx.ui.Tween carrying it.rot_y (any, optional). How far to turn the model, or a signal or trx.ui.Tween carrying it.rot_z (any, optional). How far to roll the model, or a signal or trx.ui.Tween carrying it.spin (any, optional). How far the model turns each tick, on top of rot_y , or a signal carrying it. It turns smoothly between ticks, and picks up where it stopped when the spin starts again.mesh_mask (any, optional). Which of its meshes to draw, one bit each, or a signal that holds the mask. Every mesh by default.light (any, optional). The light to draw it in, or a signal carrying it, as trx.ui.primitive.model takes it.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The model.
Example:
trx.ui.widgets.Model({
object = trx.catalog.objects.small_medipack_option,
w = 64,
h = 48,
spin = 4 * trx.math.DEG_1,
})
trx.ui.widgets.SleekBar(settings)
A thin bar that shows progress, as the game draws it under a button that the
player holds.
The bar is a dark frame with a fill in the game's own colour. It takes the width of the box that it is given, and its height follows the text size. Use a signal for progress that changes.
Parameters:
settings (table). The bar settings.
Keys:
progress (any). How full the bar is, from 0 to 1, or a signal that holds it.visible (any, optional). Whether the widget is visible, or a signal that holds that value. A widget that is not visible keeps no room and leaves no gap. Blank keeps the room instead.Returns: trx.ui.Widget. The bar.
Example:
local held = trx.signal.new(0)
local bar = trx.ui.widgets.SleekBar({ progress = held })