Module PrimeUI
Functions
addTask (func) | Adds a task to run in the main loop. |
resolve (...) | Sends the provided arguments to the run loop, where they will be returned. |
clear () | Clears the screen and resets all components. |
setCursorWindow (win) | Sets or clears the window that holds where the cursor should be. |
getWindowPos (win, x, y) | Gets the absolute position of a coordinate relative to a window. |
run () | Runs the main loop, returning information on an action. |
borderBox (win, x, y, width, height, fgColor, bgColor) | Draws a thin border around a screen region. |
button (win, x, y, text, action, fgColor, bgColor, clickedColor) | Creates a clickable button on screen with text. |
centerLabel (win, x, y, width, text, fgColor, bgColor) | Draws a line of text, centering it inside a box horizontally. |
checkSelectionBox (win, x, y, width, height, selections, action, fgColor, bgColor) | Creates a list of entries with toggleable check boxes. |
drawImage (win, x, y, data, index, setPalette) | Draws a BIMG-formatted image to the screen. |
drawText (win, text, resizeToFit, fgColor, bgColor) | Draws a block of text inside a window with word wrapping, optionally resizing the window to fit. |
horizontalLine (win, x, y, width, fgColor, bgColor) | Draws a horizontal line at a position with the specified width. |
inputBox (win, x, y, width, action, fgColor, bgColor, replacement, history, completion, default) | Creates a text input box. |
interval (time, action) | Runs a function or action repeatedly after a specified time period until canceled. |
keyAction (key, action) | Adds an action to trigger when a key is pressed. |
keyCombo (key, withCtrl, withAlt, withShift, action) | Adds an action to trigger when a key is pressed with modifier keys. |
label (win, x, y, text, fgColor, bgColor) | Draws a line of text at a position. |
progressBar (win, x, y, width, fgColor, bgColor, useShade) | Creates a progress bar, which can be updated by calling the returned function. |
scrollBox (win, x, y, width, height, innerHeight, allowArrowKeys, showScrollIndicators, fgColor, bgColor) | Creates a scrollable window, which allows drawing large content in a small area. |
selectionBox (win, x, y, width, height, entries, action, selectChangeAction, fgColor, bgColor) | Creates a list of entries that can each be selected with the Enter key. |
textBox (win, x, y, width, height, text, fgColor, bgColor) | Creates a text box that wraps text and can have its text modified later. |
timeout (time, action) | Runs a function or action after the specified time period, with optional canceling. |
Functions
- addTask (func)
-
Adds a task to run in the main loop.
Parameters:
- func function The function to run, usually an `os.pullEvent` loop
- resolve (...)
-
Sends the provided arguments to the run loop, where they will be returned.
Parameters:
- ... any The parameters to send
- clear ()
- Clears the screen and resets all components. Do not use any previously created components after calling this function.
- setCursorWindow (win)
-
Sets or clears the window that holds where the cursor should be.
Parameters:
- win window |nil The window to set as the active window
- getWindowPos (win, x, y)
-
Gets the absolute position of a coordinate relative to a window.
Parameters:
- win window The window to check
- x number The relative X position of the point
- y number The relative Y position of the point
Returns:
- number The absolute X position of the window
- number The absolute Y position of the window
- run ()
-
Runs the main loop, returning information on an action.
Returns:
-
any
... The result of the coroutine that exited
- borderBox (win, x, y, width, height, fgColor, bgColor)
-
Draws a thin border around a screen region.
Parameters:
- win window The window to draw on
- x number The X coordinate of the inside of the box
- y number The Y coordinate of the inside of the box
- width number The width of the inner box
- height number The height of the inner box
- fgColor color |nil The color of the border (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
- button (win, x, y, text, action, fgColor, bgColor, clickedColor)
-
Creates a clickable button on screen with text.
Parameters:
- win window The window to draw on
- x number The X position of the button
- y number The Y position of the button
- text string The text to draw on the button
- action function |string A function to call when clicked, or a string to send with a `run` event
- fgColor color |nil The color of the button text (defaults to white)
- bgColor color |nil The color of the button (defaults to light gray)
- clickedColor color |nil The color of the button when clicked (defaults to gray)
- centerLabel (win, x, y, width, text, fgColor, bgColor)
-
Draws a line of text, centering it inside a box horizontally.
Parameters:
- win window The window to draw on
- x number The X position of the left side of the box
- y number The Y position of the box
- width number The width of the box to draw in
- text string The text to draw
- fgColor color |nil The color of the text (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
- checkSelectionBox (win, x, y, width, height, selections, action, fgColor, bgColor)
-
Creates a list of entries with toggleable check boxes.
Parameters:
- win window The window to draw on
- x number The X coordinate of the inside of the box
- y number The Y coordinate of the inside of the box
- width number The width of the inner box
- height number The height of the inner box
- selections
table
A list of entries to show, where the value is whether the item is pre-selected (or `"R"` for required/forced selected) - action function |string|nil A function or `run` event that's called when a selection is made
- fgColor color |nil The color of the text (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
- drawImage (win, x, y, data, index, setPalette)
-
Draws a BIMG-formatted image to the screen. This does not support transparency,
and does not handle animation on its own (but the index parameter may be
used by apps to implement animation).
Parameters:
- win window The window to draw on
- x number The X position of the top left corner of the image
- y number The Y position of the top left corner of the image
- data string |table The path to the image to load, or the image data itself
- index number |nil The index of the frame to draw (defaults to 1)
- setPalette boolean |nil Whether to set the palette if the image contains one (defaults to true)
- drawText (win, text, resizeToFit, fgColor, bgColor)
-
Draws a block of text inside a window with word wrapping, optionally resizing the window to fit.
Parameters:
- win window The window to draw in
- text string The text to draw
- resizeToFit boolean |nil Whether to resize the window to fit the text (defaults to false). This is useful for scroll boxes.
- fgColor color |nil The color of the text (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
Returns:
-
number
The total number of lines drawn
- horizontalLine (win, x, y, width, fgColor, bgColor)
-
Draws a horizontal line at a position with the specified width.
Parameters:
- win window The window to draw on
- x number The X position of the left side of the line
- y number The Y position of the line
- width number The width/length of the line
- fgColor color |nil The color of the line (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
- inputBox (win, x, y, width, action, fgColor, bgColor, replacement, history, completion, default)
-
Creates a text input box.
Parameters:
- win window The window to draw on
- x number The X position of the left side of the box
- y number The Y position of the box
- width number The width/length of the box
- action function |string A function or `run` event to call when the enter key is pressed
- fgColor color |nil The color of the text (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
- replacement string |nil A character to replace typed characters with
- history string []|nil A list of previous entries to provide
- completion function |nil A function to call to provide completion
- default string |nil A string to return if the box is empty
- interval (time, action)
-
Runs a function or action repeatedly after a specified time period until canceled.
If a function is passed as an action, it may return a number to change the
period, or `false` to stop it.
Parameters:
- time number The amount of time to wait for each time, in seconds
- action function |string The function to call when the timer completes, or a `run` event to send
Returns:
-
function
A function to cancel the timer
- keyAction (key, action)
-
Adds an action to trigger when a key is pressed.
Parameters:
- key key The key to trigger on, from `keys.*`
- action function |string A function to call when clicked, or a string to use as a key for a `run` return event
- keyCombo (key, withCtrl, withAlt, withShift, action)
-
Adds an action to trigger when a key is pressed with modifier keys.
Parameters:
- key key The key to trigger on, from `keys.*`
- withCtrl boolean Whether Ctrl is required
- withAlt boolean Whether Alt is required
- withShift boolean Whether Shift is required
- action function |string A function to call when clicked, or a string to use as a key for a `run` return event
- label (win, x, y, text, fgColor, bgColor)
-
Draws a line of text at a position.
Parameters:
- win window The window to draw on
- x number The X position of the left side of the line
- y number The Y position of the line
- text string The text to draw
- fgColor color |nil The color of the text (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
- progressBar (win, x, y, width, fgColor, bgColor, useShade)
-
Creates a progress bar, which can be updated by calling the returned function.
Parameters:
- win window The window to draw on
- x number The X position of the left side of the bar
- y number The Y position of the bar
- width number The width of the bar
- fgColor color |nil The color of the activated part of the bar (defaults to white)
- bgColor color |nil The color of the inactive part of the bar (defaults to black)
- useShade boolean |nil Whether to use shaded areas for the inactive part (defaults to false)
Returns:
-
function
A function to call to update the progress of the bar, taking a number from 0.0 to 1.0
- scrollBox (win, x, y, width, height, innerHeight, allowArrowKeys, showScrollIndicators, fgColor, bgColor)
-
Creates a scrollable window, which allows drawing large content in a small area.
Parameters:
- win window The parent window of the scroll box
- x number The X position of the box
- y number The Y position of the box
- width number The width of the box
- height number The height of the outer box
- innerHeight number The height of the inner scroll area
- allowArrowKeys boolean |nil Whether to allow arrow keys to scroll the box (defaults to true)
- showScrollIndicators boolean |nil Whether to show arrow indicators on the right side when scrolling is available, which reduces the inner width by 1 (defaults to false)
- fgColor number |nil The color of scroll indicators (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
Returns:
-
window
The inner window to draw inside
- selectionBox (win, x, y, width, height, entries, action, selectChangeAction, fgColor, bgColor)
-
Creates a list of entries that can each be selected with the Enter key.
Parameters:
- win window The window to draw on
- x number The X coordinate of the inside of the box
- y number The Y coordinate of the inside of the box
- width number The width of the inner box
- height number The height of the inner box
- entries string [] A list of entries to show, where the value is whether the item is pre-selected (or `"R"` for required/forced selected)
- action function |string A function or `run` event that's called when a selection is made
- selectChangeAction function |string|nil A function or `run` event that's called when the current selection is changed
- fgColor color |nil The color of the text (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
- textBox (win, x, y, width, height, text, fgColor, bgColor)
-
Creates a text box that wraps text and can have its text modified later.
Parameters:
- win window The parent window of the text box
- x number The X position of the box
- y number The Y position of the box
- width number The width of the box
- height number The height of the box
- text string The initial text to draw
- fgColor color |nil The color of the text (defaults to white)
- bgColor color |nil The color of the background (defaults to black)
Returns:
-
function
A function to redraw the window with new contents
- timeout (time, action)
-
Runs a function or action after the specified time period, with optional canceling.
Parameters:
- time number The amount of time to wait for, in seconds
- action function |string The function to call when the timer completes, or a `run` event to send