Portfolio

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

PortfolioDocs are included in the download, but is not inside the addon folder itself to save space when embedding.

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

More implementation details soon...

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

-- 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.