Skip to content

ax.util

Source: gamemode/framework/util/util_text.lua

Utility helpers used across the Parallax framework (printing, file handling, text utilities, etc.).

Section: text_utilities

Documented functions: 6

Functions

ax.util:CapText(text, maxLength)

Utility helpers used across the Parallax framework (printing, file handling, text utilities, etc.).

Text utilities.

Truncates text to a maximum character count, appending "..." when cut.

If the text is already within maxLength characters it is returned unchanged. When truncation is needed, the text is cut to maxLength - 3 characters and "..." is appended, so the returned string is always at most maxLength characters long in total. Returns "" and prints an error when either argument is invalid.

Realm: shared

Parameters

Name Type Description
text string The text to truncate.
maxLength number The maximum number of characters allowed (inclusive of the "..." suffix).

Returns

  • string: The original text, or a truncated version ending with "...".

Usage

ax.util:CapText("Hello, World!", 8)  -- "Hello..."
ax.util:CapText("Hi", 10)                   -- "Hi" (unchanged)

ax.util:CapTextWord(text, maxLength)

Truncates text at a word boundary to avoid splitting words mid-character.

Splits the text by spaces and accumulates words until the next word would exceed maxLength. The result always has "..." appended, even when the boundary falls exactly at maxLength. As a result the returned string may be shorter than maxLength if the last fitting word ends well before it.

Returns "" and prints an error when either argument is invalid.

Realm: shared

Parameters

Name Type Description
text string The text to truncate.
maxLength number The maximum number of characters to aim for.

Returns

  • string: Words that fit within maxLength, followed by "...".

Usage

ax.util:CapTextWord("the quick brown fox", 12)  -- "the quick..."
ax.util:CapTextWord("hi", 50)                          -- "hi" (unchanged)

ax.util:GetTextHeight(font)

Returns the line height of a font in pixels.

Measures the height of the capital letter "W" as a representative character that occupies the full ascender height of the font. The result is the number of vertical pixels a single line of text in this font occupies. Calls surface.SetFont(font) as a side effect.

Realm: client

Parameters

Name Type Description
font string The font name to measure.

Returns

  • number: The line height in pixels.

Usage

local lineH = ax.util:GetTextHeight("DermaDefault")

ax.util:GetTextSize(font, text)

Returns the rendered pixel dimensions of a string in a given font.

Convenience wrapper that calls surface.SetFont(font) then returns both values from surface.GetTextSize(text) in one call. Use this when you need both width and height to avoid two separate font sets.

Realm: client

Parameters

Name Type Description
font string The font name to measure with.
text string The string to measure.

Returns

  • number: Width of text in pixels.
  • number: Height of text in pixels.

Usage

local w, h = ax.util:GetTextSize("DermaDefault", "Hello World")

ax.util:GetTextWidth(font, text)

Returns the rendered pixel width of a string in a given font.

Calls surface.SetFont(font) as a side effect, changing the active surface font state. Use GetTextSize if you need both dimensions at once.

Realm: client

Parameters

Name Type Description
font string The font name to measure with.
text string The string to measure.

Returns

  • number: The width of text in pixels when rendered in font.

Usage

local w = ax.util:GetTextWidth("DermaDefault", "Hello World")

ax.util:GetWrappedText(text, font, maxWidth)

Splits text into lines that each fit within a pixel width limit.

Measures text using surface.GetTextSize with font to determine where line breaks should occur. Words are added to the current line until adding the next word would exceed maxWidth, at which point a new line is started. When a single word is wider than maxWidth, it is split character-by-character so it always fits. If the entire text fits on one line, a single-element table is returned immediately.

Returns false (with a printed error) when any argument is invalid.

Realm: client

Parameters

Name Type Description
text string The text to wrap.
font string The font name used for pixel-width measurement. Must be a font registered with surface.CreateFont or a GMod built-in.
maxWidth number The maximum line width in pixels.

Returns

  • table|false: An ordered array of line strings, or false on invalid input.

Usage

local lines = ax.util:GetWrappedText("Hello world, how are you?", "DermaDefault", 100)
for _, line in ipairs(lines) do draw.SimpleText(line, ...) end