Module ui

These functions help in retrieving information about or manipulating UI elements.

UI functions are the profile API table `ui` (br.api.profile.ui); profiles use it by name. The profile's options page and toggle bar are built with ui.section, ui.checkbox, ui.spinner, ui.doubleSpinner, ui.dropdown, ui.text and ui.toggle in its options and toggles functions (Rotations/sample rotation.lua); every field each takes is listed in System/UI/Elements and System/UI/Toggles/ToggleFunctions.lua.

Functions

alwaysCdAoENever (thisOption[, minUnits=3[, enemyCount]]) Checks if the passed option is set to "Always, AOE/CD, CD, or Never"
alwaysCdAoENeverRange (thisOption[, minUnits=3[, range=8[, useTarget="player"]]]) Convenience wrapper: compute enemy count from a range and delegate to ui.alwaysCdAoENever
alwaysCdNever (thisOption) Checks if the passed option is set to "Always, CD, or Never"
chatOverlay (text) Displays the passed text as an overlay on the chat windows
checkbox () Adds a checkbox.
checked (thisOption[, optionPage]) Checks if the passed option is enabled
debug (text) Displays the text as a debug message in chat (if Addon Debug Messages option is enabled)
doubleSpinner () Adds two spinners on one row.
dropdown () Adds a dropdown (with a checkbox unless checkbox = false).
isMouseDown ([mouseButton]) Checks if the mouse button specified is down, or any if none are specified
lastError () The game's last error message (the red text): its key as the game names it (ERR_NO_LOOT, SPELL_FAILED_BAD_TARGETS, ...), the message shown and when (util.time()); nil before the first.
lastLoot () The last loot or money message in chat: its text, when (util.time()) and whether it was money; nil before the first.
pause () Returns true if special conditions are met to pause
pauseKey () Returns true while the player holds the Pause Mode key (Base Options)
print (msg) Shows the specified message in chat.
section (name) Starts a group of options; pass it to each option after it.
spinner () Adds a spinner (with a checkbox unless checkbox = false).
text () Adds a line of text.
toggle (name, options) Adds a button to the toggle bar.
toggleKey (thisOption) Checks if the key chosen in a key option (a ui.dropOptions.Toggle dropdown) is held
useAOE ([range=8[, minCount=3[, useTarget="player"]]]) Checks if the specified parameters are valid for AOE, based on Rotation toggle setting.
useCDs () Check if Cooldowns should be used or not based on CD toggle setting.
useDefensive () Check if Defensives should be used or not based on Defensive toggle setting.
useInterrupt () Check if Interrupts should be used or not based on Interrupt toggle setting.
useST ([range=8[, minCount=3[, useTarget="player"]]]) Checks if the specified parameters are valid for Single Target, based on Rotation toggle setting.
useTrinkets (trinket) Checks if the option to use trinkets are valid per each Trinket slot.
value (thisOption[, optionPage]) Returns the value of the specified option.
setToggle (toggleName, toggleValue) Sets a toggle to the specified value and updates the UI

Tables

dropOptions The choices of BR's shared dropdowns (Toggle: the key names, ...).


Functions

alwaysCdAoENever (thisOption[, minUnits=3[, enemyCount]])
Checks if the passed option is set to "Always, AOE/CD, CD, or Never"

Parameters:

  • thisOption string - Name of the option from the defined profile options.
  • minUnits number - Minimum number of units required to treat this as AOE. (default 3)
  • enemyCount number - A precomputed enemy count (e.g. `#enemies.yards8`) provided by the caller. (optional)

Returns:

    boolean - Returns true based on selected option and current combat conditions

Usage:

    -- Preferred (profile-controlled): compute a count and pass it
    local use = ui.alwaysCdAoENever("Bladestorm", 3, #enemies.yards8)
    
    -- Convenience wrapper (helper computes the count for you):
    local use2 = ui.alwaysCdAoENeverRange("Bladestorm", 3, 8, "player")
    -- Both forms return true if the Bladestorm option is set to Always, or set to AOE and there are at least 3 enemies,
    -- or set to AOE/CD and either CDs are enabled or the count meets the threshold.
alwaysCdAoENeverRange (thisOption[, minUnits=3[, range=8[, useTarget="player"]]])
Convenience wrapper: compute enemy count from a range and delegate to ui.alwaysCdAoENever

Parameters:

  • thisOption string - Name of the option from the defined profile options.
  • minUnits number - Minimum number of units required to treat this as AOE. (default 3)
  • range number - Range in yards to check for enemies. (default 8)
  • useTarget string - Reference unit used to evaluate range (defaults to `player`). (default "player")

Returns:

    boolean
alwaysCdNever (thisOption)
Checks if the passed option is set to "Always, CD, or Never"

Parameters:

  • thisOption string - Name of the option from the defined profile options.

Returns:

    boolean - Returns true if the option is set to Always or if CD is selected and CDs are enabled
chatOverlay (text)
Displays the passed text as an overlay on the chat windows

Parameters:

  • text string - The text to display.

Returns:

    nil
checkbox ()
Adds a checkbox. Read it with ui.checked("Name").

Usage:

    ui.checkbox(section, "Use Racial", { tip = "..." })
checked (thisOption[, optionPage])
Checks if the passed option is enabled

Parameters:

  • thisOption string - Name of the option from the defined profile options.
  • optionPage string - The page where the option is located. (optional)

Returns:

    boolean - Returns true if the option is checked
debug (text)
Displays the text as a debug message in chat (if Addon Debug Messages option is enabled)

Parameters:

  • text string - The message to show in chat.

Returns:

    nil
doubleSpinner ()
Adds two spinners on one row.
dropdown ()
Adds a dropdown (with a checkbox unless checkbox = false). Read it with ui.value("Name").

Usage:

    ui.dropdown(section, "Pet Target", { choices = { "Dynamic", "Target", "Any" } })
isMouseDown ([mouseButton])
Checks if the mouse button specified is down, or any if none are specified

Parameters:

  • mouseButton string - Name of the mouse button. (optional)

Returns:

    boolean - Returns true if the specified mouse button is down
lastError ()
The game's last error message (the red text): its key as the game names it (ERR_NO_LOOT, SPELL_FAILED_BAD_TARGETS, ...), the message shown and when (util.time()); nil before the first.

Returns:

    string, string, number

Usage:

    local key, message, at = ui.lastError()
lastLoot ()
The last loot or money message in chat: its text, when (util.time()) and whether it was money; nil before the first.

Returns:

    string, number, boolean

Usage:

    local message, at, money = ui.lastLoot()
pause ()
Returns true if special conditions are met to pause

Returns:

    boolean - Returns true if rotation should be paused

See also:

pauseKey ()
Returns true while the player holds the Pause Mode key (Base Options)

Returns:

    boolean
print (msg)
Shows the specified message in chat.

Parameters:

  • msg string - The message to show in chat.

Returns:

    nil
section (name)
Starts a group of options; pass it to each option after it.

Parameters:

Usage:

    local section = ui.section("General")
spinner ()
Adds a spinner (with a checkbox unless checkbox = false). Read it with ui.value("Name").

Usage:

    ui.spinner(section, "Healing Touch", { value = 50, min = 0, max = 100 })
text ()
Adds a line of text.
toggle (name, options)
Adds a button to the toggle bar. Read it in the rotation with ui.mode..

Parameters:

  • name string
  • options table modes = { { name = ..., icon = ..., overlay = ..., tip = ... }, ... }, key = ...
toggleKey (thisOption)
Checks if the key chosen in a key option (a ui.dropOptions.Toggle dropdown) is held

Parameters:

  • thisOption string - Name of the key option to check.

Returns:

    boolean - Returns true while the key is held (never while typing)
useAOE ([range=8[, minCount=3[, useTarget="player"]]])
Checks if the specified parameters are valid for AOE, based on Rotation toggle setting.

Parameters:

  • range number - The range of the AOE damage in yards. (default 8)
  • minCount number - The minimum number of units to be in range before true (default 3)
  • useTarget string - the reference unit to check range and units against. (default "player")

Returns:

    boolean - Returns true if AOE should be used
useCDs ()
Check if Cooldowns should be used or not based on CD toggle setting.

Returns:

    boolean - Returns true if cooldowns should be used
useDefensive ()
Check if Defensives should be used or not based on Defensive toggle setting.

Returns:

    boolean - Returns true if defensive abilities should be used
useInterrupt ()
Check if Interrupts should be used or not based on Interrupt toggle setting.

Returns:

    boolean - Returns true if interrupts should be used
useST ([range=8[, minCount=3[, useTarget="player"]]])
Checks if the specified parameters are valid for Single Target, based on Rotation toggle setting.

Parameters:

  • range number - The range of the AOE damage in yards. (default 8)
  • minCount number - The minimum number of units to be in range before true (default 3)
  • useTarget string - the reference unit to check range and units against. (default "player")

Returns:

    boolean - Returns true if single target abilities should be used
useTrinkets (trinket)
Checks if the option to use trinkets are valid per each Trinket slot.

Parameters:

  • trinket number - The item id of the trinket to check for.

Returns:

    boolean - Returns true if the trinket should be used
value (thisOption[, optionPage])
Returns the value of the specified option.

Parameters:

  • thisOption string - The name of the option specified in the options section
  • optionPage string - The page where the option is located. (optional)

Returns:

    number - Returns the value of the specified option
setToggle (toggleName, toggleValue)
Sets a toggle to the specified value and updates the UI

Parameters:

  • toggleName string - The name of the toggle to set
  • toggleValue number - The value to set the toggle to (1, 2, 3, etc.)

Returns:

    nil

Tables

dropOptions
The choices of BR's shared dropdowns (Toggle: the key names, ...).
generated by LDoc 1.5.0 Last updated 2026-11-16 01:18:17