Custom Options

Introduction

WeakAuras version 2.10 and later supports custom option panels. This allows authors of complex auras with lots of code to let users modify the behavior of those auras, without having to worry about the user editing code. Please note that WeakAuras only provides a space for you to build this panel of options, and does not assist you in designing your GUI to look presentable, or be easy to understand for your users. For assistance in designing a decent UI, see Tips & Tricks, or visit our discord server for advice from a human.

Table of Contents

• Author Mode
• Common Option Fields
• Option Types
• User Mode
• aura_env.config
• Tips & Tricks

---

Author Mode

To begin making your own options, open WeakAuras Options to the aura you wish to add custom options, click on the Custom Options tab, and then click on Enter Author Mode to enter Author Mode. In Author Mode, you will be presented with a list of options which you can edit to suit your needs. At first, you will only have the ability to Enter User Mode, or Add Option. Enter User Mode toggles back into User Mode, while Add Option ... adds an option. The first option you add will look something like this in Author Mode:

Option Controls

Each of these controls will change how the option is rendered and behaves while in User Mode. Since a comprehensive User Mode option panel generally takes a lot of options to create, there are some basic Quality of Life style controls in the header, which you can see at the top of the above image:

• The chevron on the left of the Title is a toggle button, which will collapse the option entry for ease of navigation. While collapsed, only the option header is visible.
• The up and down arrows will move the option up and down, respectively. The order of the options in Author Mode determines the order in which they are shown in User Mode, so you can use this to fine tune the design of your options panel.
• Finally, the red X will delete the option. Note that currently, this cannot be undone, so take care to not accidentally click that button!

---

Common Option Fields

Below the option header are several inputs which control the behavior and appearance of the option in User Mode. Some of these are common to all option types:

• Display Name - The title that the user will see for this option in User Mode.
• Option Key - The key by which you can access the user's choice for this option in custom code. See aura_env.config for details. This is always interpreted as a string valued key. Warning: WeakAuras does not check to ensure that the option key is unique. If you have duplicate option keys in your Options, then the value that you will access will not be well defined. Always ensure that all of the option key values in a given aura are unique.
• Option Type - The type of widget which the user will see. This also determines any additional controls which appear in Author Mode. See Option Types for details on what each option type supports and expects.
• Width - The width of the option. WeakAuras uses AceConfigDialog to render Custom Options (and most of the rest of the options interface, for the record). A width of 1 represents half of the width of the panel, and a width of 2 represents the whole width. Think of it as 2 columns, side by side. If the remaining width in one row is insufficient for an option, then it will be rendered on the next row.
• Default - The default value. In User Mode, once the user has begun to modify the controls, a button labeled Reset To Default will appear. Clicking it will reset all of the values to the default that you choose here.
• Tooltip - These two options (the toggle and the text input) determine what tooltip will be shown when the user mouses over the option in User Mode. Toggling the tooltip checkbox off will disable the tooltip; while toggled on, you can edit the text which will be shown. This is best used for explaining what an option does when the Display Name is insufficient to explain on its own.

---

Option Types

Each option type adds its own controls to Author Mode, representing the special values which it requires in order to function properly. They are listed here:

Description

This option type will place a non-interactive chunk of text of your choice into User Mode. Since it is non-interactive, the Option Key, Option Name, Default, and Tooltip controls are irrelevant and not shown.

Description Fields

• Description Text - The text to be shown. This can support multiple lines of text, so you are given a large editbox to write your text into.
• Font Size - The font size to be used. Currently, only Small, Medium, and Large are supported.

Space

This option qype will create a space in the UI. This renders in User Mode to a description element with no text, but is helpful to provide here as an easy shortcut to create space quickly.

Space Fields

• Variable Size - If the toggle box is unchecked, then the space will fill the remainder of the line that it falls on. Otherwise, it will have a width as set by the slider.

Toggle

A simple checkbox. There are no additional fields for this option. Values can be the boolean values of true (checked) or false (unchecked).

Toggle List

A collection of checkboxes. There are no additional fields for this option. This is useful for if you have a lot of toggle options which are similar to each other in purpose. NOTE: The user's choices for each checkbox will be found at aura_env.config[optionKey][index], where index is a positive integer. So in the screenshot above, the user choice for val1 would be found at aura_env.config[optionKey][1], since it is the first checkbox in this toggle list.

Color

A simple color picker the user can click on to open the Color Picker Widget. There are no additional fields for this option. The value in custom code will a table of the form {r, g, b, a}, which represents normalized RGBA. So, a value of {1, 0.5, 0, 1} represents orange, and {1, 1, 1, 1} is white.

Note: the remainder of the option types described will omit the common option fields in their preview images, as they do not change for any other option type.

String

A simple string input.

String Fields

• Max Length - If the checkbox is checked, then the string the user inputs will be trimmed if it is too long. The slider goes up to 20, but you can enter a larger number if you wish by typing into the small input field below the slider.

Number

A simple number input. In User Mode, this is identical in appearance to the string option type, but it will only accept inputs which can be evaluated into a number.

Number Fields

Note that all of these values can be unset if you do not wish to restrict the user's choice in User Mode.

• Min - The minimum acceptable input. Inputs below this minimum are adjusted to the minimum. Defaults to 0.
• Max - The maximum acceptable input. Works the same as Min, but on values larger than what is deemed acceptable. Defaults to 1.
• Step Size - The minimum acceptable step size. If set, then the user input will be adjusted down, until is is equal to min + n * stepSize, for some non-negative integer n (if min is not set, then it is interpreted as 0 for the purposes of stepification). Defaults to 0.05.

Slider

A simple slider. This is an alternative method to get a number value in your configuration.

Slider Fields

Note that all of the following fields are optional, just like in the Number Option Type.

• Min - Identical to Min in the Number Option Type. Defaults to 0.
• Max - Identical to Max in the Number Option Type. Defaults to 1.
• Step Size - Identical to Step Size in the Number Option type. Defaults to 0.05.
• Soft Min - Similar to Min, but affects only the slider. Has no default value. This value must be greater than or equal to Min to have any effect.
• Soft Max - Similar to Max, but affects only the slider. Has no default value. This value must be less than or equal to Max to have any effect.
• Slider Step Size - Similar to Step Size, but affects only the slider. Has no default value. This value must be greater than or equal to Step Size to have any effect.

Dropdown Menu

A Dropdown Menu. This option type is more complex than the other basic option types, so it will take up more space.

• Default - The default value control here is a dropdown menu, whose options are determined by the values you enter into the controls below. Note: in custom code, the value you get will be an integer (starting at 1) which represents the user choice. So, if you have {'val1', 'val2', 'val3'} as choices in a dropdown menu option, and the user picks 'val2', then you will see 2 as the value chosen in custom code.
• Value controls - Each existing value in the dropdown menu will be on its own row. You can edit the string which the user will see, or delete the entry by clicking the red X, or by entering an empty string into the input field.
• New Value - Enter a value here to add a new option to the dropdown menu. The controls in Author Mode will extend to accomodate it.

User Mode

In User Mode, you get to see all the fruits of your labor. Here is an example for you to play with:

!DA1wVTTnu4)lDyaTangYxKDYEln1zRfjozrkTVPAgjkzUrrQsr6KSh0V99DiLKDAlWkwUyZRNZ357CJztZsZsQZskO)WqTZkfkEwYn3NE1h2SolPuRSjI)HNTz6SSKNUPSSLBZU8KtxghppE(8txoF5zrZNNvEYIyifrBJK9Ck)jBwYVMNLK7AT66W8sNk3k0Qx)MUp2Tn8RHBDgv32x)QR0gED3wrtRdFvOLAt32wHTBlRMBFB32CTQLNBPlG1kenI2CHQQBlxkSt62EHH1IjUUT1IE5Gv)KypR2HnaUY5ggKxj3uZvwVAeSAi6V6e4e1AjV1k4DBLbSK7mT0vDK4)GYYnf0L4qg1mCwhRGbXb8HdXYX)4mJMqJrutIvOOZ4Yfp4Ajar64bN0FeTXcjSNSGbuy5sjPuaxHsWa6u88VX61fcnihhiGgVTFoxXzksNCRWDGgD2aBSJRkmCJG4rAT9ozJZYi0wZQumIe5IsCkiS)e44RoSvRUGmtmG1i4q8T8IrxJvOYffoLDK)oIxhmIAM1kiR(wdJ3InH1GOayDCnUN1iaz41fVIO1arqJXULg4EfsjZ7AKKkyMChK2gNFvpN8vh5tT86gVRYqgZEHLbzACwJpi4(GqBTueIzNwLtNLjjvt03gw9bgGiCpK2RLoBdBewLCxLGMk6dfWntigjy(bTfmWjV6n)wR7Hxp9TZIq0oj1p(9)ML88qc1ILtxD2sKoDw0IfRqQuiFYWRqct6ZniN06tIGnxkQ8jRnuY0QSnZIgMCA2MXXtrk7WyiPf4NHPlX1XMBIMmd3o7Y4zZwTkA1PrZwfpD58fq5XlY2m3FOf0N2HRol7D0KdP133uGWOSex)3mh2Gzf5Fwuy3LLCoMJv9j(TeSHtWyXaifeF3pQedB35hJziSOQIBAdWmDCbAyb)bxzzGr(J1xD7L3Ff23pL5mmuKQTbbFFOOniz4f47rGxcUL4PSKVCX5jPFjj987GWCeasOkwq4Jh9wd3F0KBxFfeUFnOmotsgKIs3hqkc)hHMFbYq3ZtdlETUafopzAKFhv(oT5wTGe2fR3KU(oIbqKKIj)eSwqqzBoll5Va3kkFol5Q1xs8fxw2FR3DtA6nxJBH61)oY4ncKjDHUUrYFcd8(eula0aXOpXlc(aeGGOIsdaoysML5Jmc45sA1aBMCXDRxVH2qqoqGMJ8w9uSstDhkGgOd8LWIOUKwb(giSMju)8NE0R)ZDEIVjt)SOy5BUdEJwxwYJAtXNnSMSKppocXGW0UPziMRpiQxCsugLIJqnzP1tfKlnl59gDtH(ruM7AUcs(V5pFixkzpt649cJMmLYCObZiC9yGOPefS8OYk4T5gHxedAjGQUT)Y8xOH5d53P789mOYtOu7H77RprLxrHrQgul6ajrnjnvtTfDOPUpOw0oMSSBRhptoQ9DI)8JanAsmb15)CqDXlG6IbOEoPp7)fEjWy353wYmv8JX8B7bDH29GK)JGT)kJWM4AuqAe0wDvLKpG3u)SUT30BfhH5zhC4V7LER4dstOqpreJ1YFpSJxCWXB3xh9irhpOEQkLQcqMRQOBTiqQKl13M9jQRhTf6FRoM4wmXR0Rc3JQVUz5buLtTBh0XfHEV)alC5bm()O4(XmYkFEVU0EnYLb)0JddtrEIJyhysqcrurcEJNLcI5YLRWJdp7SflMgfhhAMfdpqnjVX0TePOGBO3v5zDVcjbop6OKtQ12rg5QdukrC6(iTh1ojIIEa0CLwxqrygkye1wHo9VrSYODnHGUjKrE6rvDC1pqL))wlB6GHfnjk(4ybVDenyh3kz0l824LYbxZOj8sl40blyJ2)urKR(SgpzLtnc8jjOi4jQEHTJBOCelfa5JodbmIkfEGAXKqnrkzjl5sJ4FONUXkOk8DBtt9VvOqmueeNrQz(N5JoK5(x(dakg6CLlzTTF3QeH9TlAhckdbA(kH0NViKIUlQPY3JIKyLfZOfZ(3d

It will look like this:

---

aura_env.config

In order to read the values which your user chose, you must index aura_env.config in custom code. This is a table which WeakAuras provides to you. For each option you built in Author Mode (except Description elements), there will be a corresponding value at aura_env.config[optionKey], where optionKey is the value that you wrote in the Option Key input field. So, if you had a toggle option which looked like this:

Then you could check if the user wanted to "Show All Debuffs" by checking the value of aura_env.config["showAllDebuffs"].

---

Tips and Tricks

Here guidelines for creating intuitive and easy to read custom option panels:

• Name your options well. If you have a toggle option named Show All Debuffs, then users will expect that this will somehow translate to the aura showing all debuffs. Try not to be vague, and pay special attention to any time that you change the behavior of an option in your code. Make sure that the Display Name, tooltips, and any description texts are updated to reflect this change in behavior!
• Make some room. Don't be afraid to add description texts which don't have any text in them, to make spacers. This can turn a crowded UI into a comfortable UI. Don't just do this blindly, however. Ask friends for feedback on if your design seems crowded.
• Keep it simple. This might seem counterintuitive, given how complex much of WeakAurasOptions can be, and how this feature gets such prime real estate (as it's in its own special tab), but it's really true. The fewer options you can get away with, while still providing the full functionality you need, the better.