ButtonFacade (was LibButtonSkin-1.0)

[jjsheets2]

Authors: JJSheets, a little help from Nevcairiel and StormFX.
Input: Just about anybody who posted in this thread.
Skins: StormFX, JJSheets

Wiki Links:
Basic Wiki Page
For Actionbar Authors
For Module Authors
For Skin Authors

Note: the first few pages are from the design stage. Not terribly informative about what ButtonFacade is today. Might want to skip them unless you're masochistic or just plain curious.

[Phanx]

Reposting my last post from the InfiniBar thread:

I'm don't think a bar-skinning solution should be a library.

For one, libraries don't (or at least shouldn't) have their own options (since when used embedded the lib doesn't get any savedvars), whereas the bar-skinning addon would definitely have options for the user to switch skins and change colors (i.e. normal color, hover color, active color, etc); if I have 5 addons that are being skinned, and I want to change something, I absolutely do not want to have to go change the exact same settings 5 times in 5 different places. Ideally, the more specific options for each addon would also be available in a centralized location; I have some ideas on this but I'll wait for the separate thread to start making API suggestions. I'm on my way out the door now, but I'll post some API ideas later tonight.

Plus, it wouldn't really be feasible to embed something like this, for two reasons: a) if it includes any "default" skin(s), it's wasteful to embed the same texture files in multiple addons, and b) it's needlessly confusing to have LibBarSkins, and BarSkins, and BarSkins_MySkin as a plugin; the current system of cyCircled and cyCircled_MySkin is simple and doesn't leave users confused about what they need to get functionality.

Also, with the sort of API we're discussing, it would not only give the authors the choice to control the skinning from within their own addon (and control over how much control to give the user; i.e. limit it to a simple "apply selected skin to everything" or provide separate options for components), but it would still allow third-party developers to create plugins for addons whose authors (for whatever reason) chose not to implement native support. So you could have your SuperBar, whose author was too lazy to add a few options, and a third-party developer could write SuperBar_BarSkins to provide support. If we have an embeddable lib that includes no skins, and we emphatically do not want addons internally creating skins (we want them external as in BarSkins_MySkin), it's silly to embed LibBarSkins and then still depend on BarSkins. If you have an external dependency, just put all the functionality in one place, in the external dependency.

[Phanx]

Alright, I have some time to post now. Here's how I"m envisioning this to work (heavy use of pseudocode):

1. Register your addon with the skinner:
BarSkinner:RegisterAddon(addonName)

2. Register each component of your addon (for example, this would be a button group in InfiniBar):
BarSkinner:RegisterComponent(addonName, groupName)

3. For each component, provide a way to add/remove the actual objects for the skinner to apply skins to (the buttons in the group):
BarSkinner:AddElements(addonName, groupName, object1, object2, object3)
BarSkinner:RemoveElements(addonName, groupName, object1, object2, object3)

Now you have nice logical groupings of stuff, so you can skin/colorize components (groups) individually or globally. Addon authors have a nice simple API to hook into to skin their buttons and provide options within their addon's menu. Third-party plugin authors could easily skin addons whose authors were unwilling to provide native support. And since everything was heirarchically registered with the skinner, you could provide centralized skin management from the skinner itself, as well as easy global skin changes.

Obviously you'd need API methods for actually applying the skins and such, too.

I'm not sure if I think saved variables should belong in the skinner addon or the bar addon/plugin. Maybe store global preferences in the skinner's saved vars, and specific preferences (i.e. which components to skin) in the addon's saved vars.

[jjsheets2]

Here's my concept of it:

LibButtonSkin

• :ListSkins() Returns the list of skins in LibRockConfig/LibAceOptions format.
• :AddSkin(...) Adds a definition of a skin to the list of skins. The only skin made available in the library will be the Blizzard skin, which will replicate a standard Blizzard styled button.
• :RegisterReskinCallback(AddonName,Callback,Callbac kArg) Registers the callback that allows an addon to store the new skin choice in response to the Reskin function below. Callback is called like: Callback(CallbackArg,SkinName,GroupID,ButtonID).
• :ApplySkin(SkinName,AddonName,GroupID,ButtonID,<bu tton details>) This will apply the skin identified by SkinName to the button presented in <button details>. Each button is categorized by addon, group, and individual buttons. This allows skins to be set externally per addon, per addon/group combo, or per specific button. GroupID and ButtonID can be nil. If GroupID is nil, ButtonID must be nil, and this indicates that all buttons supplied by the addon are to be configured the same by any external skin chooser (More on this later). If GroupID is not nil, but ButtonID is, then the button can be skinned externally only when skinning the entire group. ApplySkin will not work if the Reskin callback has not been registered for the given AddonName.
• :ListAddons() Returns the Options formatted list of Addons that have skinned buttons using LibButtonSkin.
• :ListGroups(AddonName) Returns the Options formatted list of groups skinned with the associated AddonName.
• :ListButtons(AddonName,GroupID) Returns the Options formatted list of buttons skinned with the associated AddonName, and GroupID, and that were skinned with an associated ButtonID.
• :Reskin(SkinName,AddonName,GroupID,ButtonID) Reskins a selected set of buttons or an individual button. AddonName can be nil, and if so, GroupID and ButtonID must also be nil, and this will reskin all buttons skinned by the lib. GroupID can be nil, and if so ButtonID must be nil, and this indicates that all buttons originally skinned with the AddonName will be Reskinned with the chosen Skin. If only ButtonID is nil, it will reskin all buttons originally skinned with AddonName and GroupID. Obviously, if none of the three are nil, then it will reskin a specific button.

Actionbar addons will use ListSkins, RegisterReskinCallback, and ApplySkin to work with the library. Skin Packages will use AddSkin to add new skins to the library's list. Skin Chooser Addons (And even Actionbar addons) will use ListAddons, ListGroups, ListButtons, and Reskin.

The actionbar addon, much like when using LibSharedMedia, will store the skinname in its saved vars.

The library will only act as the glue between the three components. Skin Choosers, much like cyCircled, will have access to the info needed to allow a person to reconfigure all of their buttons, either all at once, or more specifically. Skin Packages will have a simple interface to register the skin's settings. Actionbar addons will have a simple method of applying skins, a way to recognize when an external change to the chosen skin is made, and the option to reskin their buttons in a similar fashion to a Skin Chooser.

The major reason why I want a library is because I feel there should be a separation between the Skin Chooser addon, and the Skinning functionality itself. Those who, like me, only use one addon for buttons, will not need to load a skin chooser just to get skinning. Those who use more than one actionbar mod will have the option to get a Skin Chooser to configure everything at once. The addition of extra skins will be simple enough, and I even suggest that common or major skins be an embed in a skin chooser, so that embedded versions of the skin chooser come pre-equipped with a good selection of skins. And this won't effect those of us who never use embedded addons, since we can just grab the skin(s) we want. Finally, an actionbar addon alone with the library embedded will still just support the one standard button skin (Blizzard), and thus those who don't want skinning at all never have to worry about any of this stuff.

[Phanx]

I still foresee the same kind of confusion that exists already with LibSharedMedia/SharedMedia, even more so when you consider that not only might SomeBar itself use your proposed LibButtonSkin, but you might also have a third-party SomeBar_ButtonSkin if the author of SomeBar didn't support the system directly himself, and that the skin chooser and extra skin packs add yet more components to the scattered system.

Personally I'd say that addon authors should do exactly what they do now if they want to support, but not require, the skinning system. For example, in my addons, I don't embed LibSharedMedia; if the user has it, then I use the Fetch API and create an option for them to change the font, but if they don't have it, I just set the font to "Fonts\\FRIZQT__.ttf" and don't create the option. In the context of the proposed ButtonSkin (which I think needs a less generic name), this would work like so:

- OptDep ButtonSkin
- If the user does not have ButtonSkin, don't do anything. Icons already look like the Blizzard "skin" (it's the equivalent of "Don't skin this") so no special action is required.
- If the user does have ButtonSkin, then register with ButtonSkin, apply a skin, and create/enable your relevant option(s).

It's a less fragmented system, it's less confusing for users ("Do I need LibButtonSkin, or ButtonSkin, or both?" or "I have LibButtonSkin but I can't see any options!" or "I installed ButtonSkin but SuperBar still gives me errors about not finding the library."), and it means that addon authors can support the system without requiring or including any part of it.

[StormFX]

Phanx has pretty much pointed out my reservations about using a "library". However, JJ does a nice job of the benefits of library.

Like he mentioned, the "library" wouldn't actually include any texture files as the default skin would be Blizzard-like (or perhaps "Dream" layout?).

Basically there'd be two "add-ons" (excluding skins, of course):

LibButtonSkin-1.0 would provide the basic (but complete) skinning engine and build a default table for skin data storage while providing access to all three user groups (add-on authors, skin authors and users).

ButtonSkins (or whatever) would be an optional front-end engine that allows fine-tuning of certain aspects of skins and allows for a modular add-on skinning method for unsupported add-ons.

Basically, the difference between this and the current cyCircled would be that the skinning engine could be used by add-on authors without having to include or load the entire application.

Honestly, though I've had some experience with coding, I know little about LUA's interaction with the game engine. I do know the results and as long as the results are what we're looking for, that's all that matters to me.

Edit: Honestly, Phanx's solution sounds the most user-friendly. Let's just keep the name short and effective if possible! :P

[Phanx]

Pretty much any instance where there is both a functional library and an "optional" front-end, you have mass user confusion. Even when users grasp that there is a distinction, they frequently don't understand what the distinction is, and almost invariably use the name of one to refer to either, which in turn leads to mass devloper confusion when trying to figure out what a user is talking about. LibSharedMedia-x.0 vs SharedMedia is one example; Threat-x.0 vs Omen is another. You can patiently explain the difference over and over until the end of time, but most users will keep blurring the line because they don't see it as relevant.

The cyCircled/cyCircled_CoolSkin system is already familiar to users, and doesn't make a backend/frontend distinction that the vast majority of users won't ever understand. Especially since there isn't really a "Blizzard skin" (as previously mentioned, doing nothing at all to the icons results in the default look), it's super easy to add optional support for the system, while keeping the skinning frontend and backend contained in a single, obvious, user-friendly package. LibSharedMedia works because there is Blizzard media to fallback to if no additional media is provided; even if the user does not install SharedMedia, and uses only a single addon that does not provide any custom media, they can still select from the four Blizzard-supplied fonts, and several Blizzard-supplied background textures. The same does not apply to button skins, since Blizzard does not provide any usable textures.

Zoomed and Dreamlayout "skins" are easily doable without the use of a library; Zoomed requires only a single SetTexCoords line, and Dreamlayout is just a few lines of code to CreateTexture/SetBackdropColor/SetPoint/SetHeight/SetWidth. Indeed, such simplistic "skins" would probably require special handling by a system designed to handle multi-layered texture skins.

[StormFX]

Attributes

One of the things that has to be available for skin creation is to be able to adjust the scaling of individual components of the skin/button. For example, the icon size of a button with rounded "borders" will be smaller than that of a square "border".

<More to come, maybe>

Colors

One thing that (ironically) I find annoying (as a skin author) about cyCircled is the option to adjust various colors (highlight, equip, etc). I honestly don't believe this is necessary, as the skin itself designates how it's supposed to look.

Textures

As was previously mentioned, one of the faults of cyCircled is that the border texture is the same as the highlight and/or gloss texture. This, coupled with the ability to adjust the colors, makes some gross-looking effects. So we need to ensure that each part of the overall skin is separate (border, gloss, highlight, etc).

Layers

Another issue with cyCircled is layer order. At the moment, it allows you to adjust the layer order, but only to a certain extent. After playing around, I don't believe this is necessary at all. In fact, I've come up with the following layer order that should work with any design:

(From top layer to bottom layer, in reverse order)

Main Layers
- Macro Name
- Cool Down text (Where applicable)
- Hot Key
- Item Count
- ** Gloss/Glaze ** (See below) (Separate Texture)
- Highlight Texture (Separate Texture) (Mouse-over)
- Active Texture (Separate Texture) (Forms, Auras, etc)
- Border Texture (Separate Texture)

Sub Layers (Below the base texture)
- Auto-Cast Texture (Only applicable on square buttons)
- Auto-Cast-able Texture (Only applicable on square buttons)
- "Pressed" Texture/Color
- Cool Down Animation
- Flash (usually just a color overlay)
- Equip (usually just a color overlay)
- Spell/Skill Icon
- Backdrop (Color or Texture)

(Feedback on the order and/or additional layers is welcome)

** An important thing to note about the glaze/gloss texture is its independence from the rest of the button skin. The reason is mentioned above. Also, by separating the glaze/gloss texture, we no longer have to have TWO separate skins. We can simply add an option to enable/disable the glaze/gloss on that particular skin/bar/button. If a skin doesn't come with a glaze/gloss texture, the option isn't available.

<More to come, maybe...>

[StormFX]

Well, as I mentioned, how it's done doesn't matter. What does matter is that it works as intended and that users aren't too overwhelmed. I'll leave that to you coders. Just keep in mind that us skin authors aren't necessarily LUA gurus so keep the skin set up at least no more complex than that of CC.

One other thing: Use Ace3. Not trying to start a libs war, but personally, I find it has the most user-friendly GUI.

[Phanx]

The only issuse I have with that proposed layer order is the fact that forcing the highlight and active textures below the border texture means you can't actually recolor the border on these states, which is what I wish more skins would do (or at least recolor larger sections so the color is more visible).