Interface Option Creation Utility
Library to register Blizzard Option Panels with an option table syntax.
Purpose
Portfolio was made to act as a bridge to accept a recognizable option table format (similar to Khaos and Ace) and convert it into a fully functional Blizzard Options Panel. Any Ace or Khaos registration should be fairly painless for an author to convert to use Portfolio, and new option sets should be easy to understand and construct without having to make any frames or manually manage controls.
LuaDocs
http://www.karlkfi.com/PortfolioDocs/
PortfolioDocs are also included in the download, but is not inside the addon folder itself to save space when embedding.
Feedback & Support
The best way you can help would be to try and write your own Portfolio config options and see if it behaves the way you'd expect. Report any bugs or confusing implementation using the Report Bugs button or Comments. I'm also always open to suggestions and code donations via the Feature Request link.
If you'd like to donate to show your support, that can be done through paypal with a paypal account or by credit card. Remember donations are much appreciated but non-contractual. Thank you!
Implemented Option Types
- Header - CONTROLTYPE_HEADER
- Text - CONTROLTYPE_TEXT
- Checkbox - CONTROLTYPE_CHECKBOX
- Slider - CONTROLTYPE_SLIDER
- Button - CONTROLTYPE_BUTTON
- DropDown - CONTROLTYPE_DROPDOWN
- ColorPicker - CONTROLTYPE_COLORPICKER
- EditBox - CONTROLTYPE_EDITBOX
- Window - CONTROLTYPE_WINDOW
Option Attributes
Common Option Table Attribute Descriptions- id - Unique option id. Used to create the names of the option frames (No Spaces!). Key used to store the value in the saved variables table if cvar/uvar/tvar are nil.
- type - Type Variable. ex: CONTROLTYPE_HEADER
- text - Option text. String (with optional format string like %s or %.2f to insert value), function(control, key) returning a string, or both.
- tooltipText - (Optional) Text used in hover tooltip. String, String with %s for value, or function(value) returning a String
- init - (Optional) function(control) called after the option is created, for customization.
- defaultValue - Default value for options
- callback - (Optional) function(color, isGUI, isUpdate) called when the value is changed
Note: isUpdate is true when control:Update() is called, when the callbacks are initialized after variables load.
- cvar - (Optional) CVar, SetCVar(cvar, value)
- event - (Optional) SetCVar argument, SetCVar(cvar, value, event), requires cvar
- uvar - (Optional) Global Variable Name, setglobal(uvar, value)
- tvar - (Optional) Table Variable Key, for optionsFrameRef.savedVarTable[self.tvar] = value or varTable[tvar] = value
- varTable - (Optional) Custom Variable Table, requires tvar
Header- id
- type - CONTROLTYPE_HEADER
- text
- subText - (Optional) Subheader Text
- init
Text- id
- type - CONTROLTYPE_TEXT
- text
- init
Checkbox- id
- type - CONTROLTYPE_CHECKBOX
- text - Text shown to the right of the checkbox
- tooltipText
- init
- defaultValue - "0" or "1"
- invert - (Optional) inverts the value of the checkbox, "1" means unchecked, "0" means checked
- callback
- dependentControls - (Optional) Table of frames to disable when this one is set to "0"
- dependentOptions - (Optional) Table of id's of other options to disable when this one is set to "0"
- cvar
- event
- uvar
- tvar
- varTable
Slider- id
- type - CONTROLTYPE_SLIDER
- text - Text shown above the slider
- tooltipText
- init
- minText - (Optional) Text used under the left arrow
- maxText - (Optional) Text used under the right arrow
- minValue - Number (Used for minText if minText = nil)
- maxValue - Number (Used for maxText if maxText = nil)
- valueStep - Number, slider granularity, divides evenly into maxValue - minValue
- defaultValue - Number, between minValue and maxValue
- callback
- cvar
- event
- uvar
- tvar
- varTable
Button- id
- type - CONTROLTYPE_BUTTON
- text - Text shown on the button
- tooltipText
- init
- callback
Dropdown- id
- type - CONTROLTYPE_DROPDOWN
- text - (Optional) Text shown on the button
- headerText - (Optional) Text shown above the button
- tooltipText
- defaultValue
- menuList - List of buttons
- width - (Optional) static width of the control
- minWidth - (Optional) min width of the control, larger text will resize the contol. Default 100.
- nochecks - (Optional) Boolean, don't initialize empty menuItem.checked
- nofuncs - (Optional) Boolean, don't initialize empty menuItem.func
- init
- callback
- cvar
- event
- uvar
- tvar
- varTable
ColorPicker- id
- type - CONTROLTYPE_COLORPICKER
- text - Text shown to the right of the color swatch
- tooltipText
- init
- defaultValue - color table {r=#, g=#, b=#, opacity=#} (opacity is optional)
- callback
- hasOpacity - (Optional) boolean to show opacity slider
- cancelFunc - (Optional) function to call when the color change is canceled, after it's reset to the previous color
- cvar
- event
- uvar
- tvar
- varTable
EditBox- id
- type - CONTROLTYPE_EDITBOX
- headerText - (Optional) Text shown above the button
- tooltipText
- init
- defaultValue
- callback
- cvar
- event
- uvar
- tvar
- varTable
Window- id
- type - CONTROLTYPE_WINDOW
- init
- options - List of option tables
- width - (Optional) Number, defaults to calculated based on parent width
- height - (Optional) Number, defaults to 200
Notes on Dropdowns
This implementation of dropdowns is about half way between managed and unmanaged. It has some shortcuts, but is essentially blizzard's dropdown code at its core. Because of this it is very powerful and can be customized by advanced users to do almost anything. But for those of you new to dropdowns you don't have to be intimidated, because I've done all the setup for you. The minimum you have to supply is a table formatted list of buttons. Each button should have a text, and a value. The checks and callback will be managed if left empty.
For advanced users the func and checked attributes can be overriden. You can also use any of the normal dropdown attributes. See FrameXML/UIDropDownMenu.lua for a full list of menu item attributes. And as will all controls you can override any of the settings or methods using the init function if you need something more customized.
I've also simplified the dropdown button itself, using UIDropDownMenuTemplate as a template on top of which I've added shortcuts and modifications. Texture anchors have been modified to play nicely with control:SetWidth(x) so that you don't have to use UIDropDownMenu_SetWidth. The clickable/tooltip area has also been extended to cover the whole button.
Saved Variables
Portfolio uses
LibDefaults to manage your defaults for you if you wish. The normal way to handle defaults is to put the name of your saved variable table in optionSetTable.savedVarTable, but you can also supply individual options with their own varTable. Then you can supply a tvar to be the index to that saved variable table, otherwise the id will be used as the index. Alternately you can supply an option with a cvar or uvar (global variable name) to use instead. Note that if you supply none of the above Portfolio simply won't handle your variables. You can then manually update the options using the callbacks and init functions. You can also supply optionSetTable.initCallbacks = false in order to disable callbacks being fired when after the variables load.
Since Portfolio has no saved variables of its own and allows you to be flexible with your saved variable structure you can easily use the same saved variables with or without Portfolio. Your Portfolio GUI options can be truly optional. I'd suggest using LibDefaults to save live memory and avoid saving/loading in default values, but you don't have to.
Registration
lua Code:
-- Get a reference to the lib from LibStub
-- If LibStub doesn't exist this will fail silently
-- If LibStub exists but Portfolio does not this will print an error in chat and then fail
-- Use LibStub("Portfolio", true) to fail silently if you want Portfolio options to be optional.
local Portfolio = LibStub and LibStub("Portfolio")
if not Portfolio then return end
-- Create the option table for registration.
local optionSetTable = {
-- option frame id, unique, no spaces
id = "PortfolioDemo";
text = "Header/Tab Title Text";
subText = "Sub header Text"
-- AddOn name for variable loading, if different from id
addon = "PortfolioDemo";
options = {
-- list of option tables goes here!
{
id = "option1";
-- option attributes go here
};
-- more option tables
};
-- (Optional) String or table of your addon's saved variables. Use SavedVariables in your toc!
savedVarTable = "PortfolioDemo_SavedVars";
}
local optionsFrame = Portfolio.RegisterOptionSet(optionSetTable)
Embedding
See PortfolioDocs for more information.
Examples
The PortfolioDemo addon is included in this package. It is disabled by default so it won't bother users, but it should be an invaluable resource to those of you who learn by example. It should have a variety of usages for each implemented option type.