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:
- name string
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:
- 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