Post #1 - What is Macaroon?
Post #2 - Features of Macaroon
Post #3 - Installing Macaroon
Post #4 - Configuring Macaroon
Post #5 - Memory Usage and Macaroon
Post #6 - Advanced Topics
Post #7 - Of Macros, Mages and Multiboxing...mmm???

Macaroon is a macro-based "action bar" addon. Up until Macaroon, even considering Trinity Bars, all bar addons were action ID based (at least "out-of-the-box" they were). Macaroon aims to expand beyond the limitations of the action ID system through maximum use of the macro-based button which was introduced in WoW 2.x.

Macaroon is designed to be many things to many users. It can stand on its own as a full-fledged bar addon. Or it can even run side-by-side with other bar addons. It can be an addon for keybinders or even clickers. The whole of the addon is designed to be as feature rich as a user may need, without needing to "fuss" with options one does not care about.

Macaroon is centered around the WoW macro. However, you do not need to know how to write a single WoW macro to use Macaroon! All buttons accept drag-n-drop spells from your spellbook and "feel/function" much like any other button in the default UI or other action bar addons. But if you do decided to expand into the world of macros, be prepared, for you are about to "Feel the power of the macro side..."

• Macaroon offers an unlimited number of macros and an unlimited number of bars of arbitrary length. Create as many bars/buttons as you want/need per character with as many buttons per bar as you want. If you are a major button clicker, you can have at it.

• Players who are considered "Key Binders", people who's style of play is to have minimal buttons (or none at all) on the screen, using hidden key bound buttons to play, can find Macaroon extremely "Key Binder" friendly with the button storage area. The button storage area merges some key features that "Key Binders" should enjoy -

Consolidated area for all buttons, up to 144 buttons (visible).

Edit your macros directly on the buttons in the storage area.

Edit your key binds directly on the buttons in the storage area.

• In-game macros are limited to 255 character in length. This is a limit of Blizzard's macro interface, not of macros themselves. The Blizzard internal macro system can actually handle macros of up to 1024 characters in length, and Macaroon makes full use of that fact on each and every macro

• Uses Maul's unique mouseover key-binding system - where the mouseover binding system was born!

• Many other of the favorite desired bar addon features and then some. You can scale, pad, "sticky" bars together and much more.

• Macaroon is completely Button Facade compatible and supported.

Macaroon is distributed as two addons, Macaroon and MacaroonProfiles. MacaroonProfiles is only needed is you decide to save profiles of Macaroon setups. MacaroonProfiles does not even load unless you go to the Profiles configuration menu or load a profile.

Once downloaded, simply unzip the file into your Interface\AddOns folder so that you see both addons in the file structure as

Interface\AddOns\Macaroon

Interface\AddOns\MacaroonProfiles

Make sure that you are fully exited out of WoW when you install new addons.

When you enter WoW after an initial install of Macaroon, you will not see any major difference on your screen save for a newly added minimap button on your minimap. Macaroon starts you off with a clean slate, letting you, the user, decide what you want out of Macaroon instead of me, Maul, deciding for you what you should have and where.

To configure Macaroon, there are two ways to go about it. Via slash commands and the path of command lines or via the minimap button and the path of GUI. Please note that I endeavor to have as many configuration options doable via slash command or GUI, but may overlook some in my zeal to work on addons!

The Path of Command Lines -

There are two primary slash commands that Macaroon recognizes, "/macaroon" and "/mac". The syntax of the commands is as follows -

/macaroon <command> [<options>]

The current command set is -

menu: Toggle the main menu
storage: Open the button storage area
create: Create a blank bar
delete: Delete the currently selected bar
config: Toggle configuration mode for all bars
add: Adds buttons to the currently selected bar (add or add #)
remove: Removes buttons from the currently selected bar (remove or remove #)
edit: Toggle edit mode for all buttons
bind: Toggle binding mode for all buttons
scale: Scale a bar to the desired size.
snapto: Toggle SnapTo for current bar
autohide: Toggle AutoHide for current bar
shape: Change current bar's shape
name: Change current bar's name
strata: Change current bar's frame strata
alpha: Change current bar's alpha (transparency)
alphaup: Set current bar's conditions to 'alpha up'
arcstart: Set current bar's starting arc location (in degrees)
arclen: Set current bar's arc length (in degrees)
columns: Set the number of columns for the current bar
padh: Set current bar's horizontal padding
padv: Set current bar's vertical padding
padhv: Adjust both horizontal and vertical padding of the current bar incrementally
showgrid: Toggle the current bar's showgrid flag
x: Change current bar's horizontal axis position
y: Change current bar's vertical axis position
state: Toggle states for the current bar (/mac state <state>). Type /mac statelist for valid states
statelist: Print a list of valid states
load: Load a profile
lock: Lock buttons

Examples -

/mac menu - this will bring up the main options menu

/mac create bar - this will create a standard bar

The Path of GUI -

The Minimap Button - This button is the gateway to several options via a click and/or modified click.

Left Click: Toggles bar configuration mode
Right Click: Opens a minimenu with these options -

Bar Edit: Toggles bar configuration mode
Bind Edit: Toggles binding mode
Button Edit: Toggles button edit mode
Create Bar: Create a new bar
Delete Bar: Delete the currently selected bar
Main Menu: Open to the main options menu
Storage: Open to the button storage menu
Close: Close the minimap minimenu

Shift Click: Toggles binding mode
Alt Click: Toggles button edit mode
Ctrl Click: Opens the main options menu

Editing Bars -

After you enter the bar configuration mode, all bars become visible. When you mouseover a bar, you will see a tooltip (by default) detailing how most options are currently set for that particular bar. All deselected bars will be a very light gray color. When you select a bar for editing, it will turn blue.

While a bar is selected, it will respond to clicks and modified clicks. These clicks will do different tasks

Left Click: If a bar has more than one state, left clicking on a bar will manually cycle through all available states. A state is a certain condition in which to show buttons, such as bar pages or stances/form.

Right Click: This will bring up a bar editor. The bar editor is the gateway to many configurable options for a bar. Initially, on the left side of the editor is a list of options that can have a varied range of values. On the right side of the editor is a list of on/off options. At the bottom of the editor are next/prev buttons that will take you to an additional set of options that are text-based.

Left-hand options -

Scale: Scale a bar to the desired size
Shape: Change current bar's shape
Columns: Set the number of columns for the current bar
Strata: Change current bar's frame strata
Alpha: Change current bar's alpha (transparency)
AlphaUp: Set current bar's conditions to 'alpha up'
Arc Start: Set current bar's starting arc location (in degrees)
Arc Length: Set current bar's arc length (in degrees)
Arc Preset: Chose from preset arc settings
Pad Horz: Set current bar's horizontal padding
Pad Vert: Set current bar's vertical padding
Pad Horz+Vert: Adjust both horizontal and vertical padding of the current bar incrementally
Button Count: Add/Remove buttons to the currently selected bar

Right-hand options -

Paged Bar: Toggles bar paging, allowing for up to 6 unique pages.
Stance: Toggles stance paging for classes that have stances/forms.
Prowl: Toggles a special stance state for druid prowling.
Pet: Toggles pet paging based on pet's existence.
Stealth: Toggles paging based on any stealth condition except for druid prowl.
Reaction: Toggles a bar switching states based on current target's hostile/friendly reaction.
Combat: Toggles a bar that will switch states based on combat status.
Group: Toggles a bar that will switch states based on group status.
Possess: Toggles a state to show special buttons when possessing another creature.
Vehicle: Toggles a state to show special buttons when using a vehicle.
Alt Key: Toggles a state to show when the alt key is held down.
Ctrl Key: Toggles a state to show when the ctrl key is held down.
Shift Key: Toggles a state to show when the shift key is held down.
Custom: Allows for defining custom states using the macro system conditionals.
Autohide: Toggle AutoHide for current bar
Showgrid: Toggle the current bar's showgrid flag
SnapTo: Toggle SnapTo for current bar
Hidden: Toggle a bar as always hidden while not in configuration mode.
Dual Spec: Toggle a bar to allow it's buttons to update data based on current spec.

Text-based options -

Bar Name: Assign a unique name to a bar.
Bar Target: Set a bar's target so that it will show/hide based on that unit's existence.

Linked To: Link a bar to another bar. The linked bar will obey the state conditions of the bar it is linked to.
State: Determine a specific state to link a bar to.

Bar State: Select a bar state to remap.
Remap To: Determine which state to remap the above state to.

Custom States: Allows the entry of custom bar state conditionals using the in-game macro syntax. Place a new state condition on a new line. For example -

[stance:1, mod:shift]
[stance:1, mod:alt]
[stance:1, mod:ctrl]
[stance:1]

Editing Buttons -

After you enter button edit mode, all visible buttons will display their button type. There are three possible button types -

Macro: A button that utilizes the in-game macro sytax to cast spells/perform actions.

Action: A button that uses a unique action ID to indicate what spell/action it contains. The contents of an action ID are stored server-side. There are only 120 (1-120) unique ID's for character spells. A special case are possess buttons which can use the action ID's 121-132.

Pet: A button that uses a unique pet action ID to inidacte which pet spell/action it containts. The contents of a pet action ID are stored server-side. There are only 10 (1-10) unique ID's for pet spells.

To change a button's button type, simply left click the button. As you left click, it will cycle through all button types.

Each button type has its own specific button editor. To enable the editor for a button, right click on the button and the appropriate button editor will be displayed. As with the bar editor, there are next/prev buttons at the bottom of the editor. These are additional button options that are not tied to the button's particular type.

The Macro Button Editor -

Macro Icon: Allows the selection of a unique icon for the macro. Using the ? icon will use the spell's default icon.

Macro Name: Allows for the naming of a macro, but is not needed for a macro to function.

Macro Master: The macro master stores unique user-created macros per account. All characters on an account can pull macros from the macro master.

Macro Edit Area: The area to edit your macros.

Expand: Allows for the ability to expand laterally the macro edit area for easier reading of longer macros.

Macro Note: Allows for the adding of a note to a macro.

Use Note as Tooltip: Allows the note to be used as the button's tooltip.

The Action/Pet Button Editor -

Action ID: Allows the selection of the action ID for a button.

Propagate: Clicking on this option will set the action ID's in sequential order for the entire bar of the current state.

Additional Options Editor -

(Note: The click/Mouse anchors are not functional as I wait for some changes to the Blizzard code to make it possible)

Click Anchor: Sets a button to hide/show a bar's button when it is clicked (even in combat)

Mouse Anchor: Sets a button to hide/show a bar's button when it is moused-over (even in combat)

Anchored Bar: Set the bar to anchor to the current button.
Delay: Set the delay to hide a anchored bar for a mouse anchor.

Scale: Set the individual scale of a button.

XOffset: Set the individual x offset in relation to the bar of a button.

YOffset: Set the individual y offset in relation to the bar of a button.

Up Clicks: Set the button to respond to up-clicks.

Down Clicks: Set the button to respond to down-clicks.

Spell Counts: Show the number of times a spell/ability can be used before your character's power is depleated (Rage, Mana, Energy, Runic)

Combo Counts: Show the current number of combo points on a target (druids and rogues only)

Editing Bindings -

/start random fact
At the risk of being immodest and for historical reasons, I shall state here that the mouseover binding method that is so popular now got its start in the early days of Trinity Buttons, for those who don't know :) The concept first showed up in the early Trinity Buttons days of beta for The Burning Crusade. It was Tuller of Bongos/Dominos fame that refined the system and made it popular in his bar addons. Just some FYI :)
/end random fact

After you enter binding mode, all visible bind-able buttons will display either "bind", meaning that button can have its bindings adjusted, or "locked", meaning that whatever bindings that buttons has cannot be changed until it is unlocked.

While in binding mode, simply mouse-over the button you would like to assign a bind to, and hit the key. You may give a button any number of binds you want. The first bind is the one that will display on the button.

Once a binding is set for a button, you have the option to lock that button's binding so they cannot be changed by left clicking the button. If you dabble in the more advanced features of Macaroon, the need to lock bindings will become more apparent.

The Main Menu -

The main menu is for options that are not bar/button specific. Some may affect bars/buttons, others may not. The following explains what each option does.

The Storage Area -

The storage area serves two purposes. The primary purpose is to be a place where button frames go when not in use by any bar. Frames, once created, cannot be destroyed. Also, as one sets up their bars, they may go back and forth adding and removing buttons. The storage area is just a holding area for those buttons.

However, the storage area can be useful for holding buttons that you want to use, but not have shown. Each row of buttons in the storage area has a lock toggle. This toggle is designed to prevent buttons on that row from becoming part of the "pool" of buttons that bars pull from and add to as bars are adjusted.

For the users convenience in regards to this secondary purpose, some options are provided at the bottom -

Binding Mode: To toggle binding mode.

Edit Mode: To toggle button edit mode.

Create Button: Create a new button that is placed into storage immediately.

Delete Button: To delete unused/unwanted buttons. Note, buttons are not really deleted until you re-log or reload your UI. Until such time, they are merely flagged for deletion. You cannot un flag a specific button once deleted.

The Profile Manager -

(Note: currently profiles are not directly shared between characters as they are in other addons. This is a feature that is in the works)

These options are for setting up and storing specific profiles for use by any character on the current account. These are "dumb" profiles. That means, once you load one, any changes you make on that character are not re-saved to the profile unless you specifically re-save it yourself.

There are four different sets of data you can save for each profile -

Bar Layout: This option merely saves the location of bars, nothing else.

Button Layout: This option saves how many buttons are saved on each bar and in which states. Specific button data is not saved with this option.

Settings: This option saves your main menu settings.

Button Data: This option saves the actual button data such as spells, button scale and keybindings for the button. Right now, keybindings are integrated into the button's data and is problematic to have them saved separately. This is a known issue that is being worked on.

For each profile, you can name it (in fact you must give it a name for it to save) and you can add notes to remind you what the profile is for. In the profile list, you can see all data needed to understand what a profile contains.

At the bottom of the profile manager is the new dual spec feature being added in patch 3.1. Enabling this feature will allow the current character to swap full profiles upon a spec change.

Note: This feature is optional. If you do not need to change bar layouts, button counts or global settings upon a dual spec swap, Macaroon will natively handle the button data swapping without this option being set. Just make sure you have dual specs enabled in the main menu.

Macaroon is a complex addon, with many features. It can use a larger amount of memory compared to other similar addons. However, one thing to understand is that memory usage in an addon has no direct impact on game performance. What impacts game performance is CPU usage.

The WoW client itself uses magnitudes more memory than the most memory intensive addons. If your computer can handle running WoW well, added memory usage by addons will not affect its performance. If your computer struggles to run WoW even at minimum settings, then addons are merely a straw on the proverbial camel's back.

CPU usage is another story. Addons do use CPU time, and the more they do, the more time they use. Macaroon, because of its nature, tends to use more CPU time than other addons of a similar nature. However, I am very, very focused on insuring CPU usage is within reason. If you ever experience an FPS drop and deem it to be related to Macaroon, please give me information on the FPS drop so that I may improve Macaroon!

So remember, in the majority of cases, especially if your computer already runs WoW well (set at average or above average settings) without addons, and you experience FPS issues, your addons are using more CPU time than your computer can keep a decent frame rate at. It is not a memory issue :)

This area discusses some of the more advanced possibilities of Macaroon.

Custom States: (article still to be written)

Bar Linking: (article still to be written)

Macro Extensions:

/doafter command -

This command allows for the execution of an unsecure chat line after a specified event for a given spell

Format -

/doafter <spell>:<spell event>:<unsecure command line>

Example -

/doafter flash heal:heal:/say Flash Heal has been cast

List of available events and associated data -

damage

data index - 1: amount, 2: overkill, 3: school, 4: resisted, 5: blocked, 6: absorbed, 7: critical, 8: glancing, 9: crushing

missed

data index - 1: misstype, 2: amount missed

heal

data index - 1: amount, 2: overheal, 3: critical

energize
drain
leech
interrupt
stolen
start
success
failed
instakill
create
summon
resurrect

/in command -

This command allows for the execution of an unsecure chat line after the specified amount of time

Format -

/in <wait time>:<unsecure command line>

Example -

/in 5:/say It has been 5 seconds!

/repeat command-

This command allows for the execution of an unsecure chat line at repeated intervals for the specified number of times.

Format -

/repeat <interval>:<count>:<unsecure command line>

Example -

/repeat 5:3:/g Be careful not to spam!

/select command -

This command allows for the creation of a popup menu of items/spells for selection to be used by the macro button

Format -

/select <type>:<keys>:<shape>:<attach point>:<relative point>:<columns|radius>:<click|mouse>

Examples -

/select item:trinket:linear:right:left:6

/select item+:quest item:circular:center:center:15

/select companion:mount:linear:right:left:6

Most options may be abbreviated -

/select i+:quest item:c:c:c:15:c

Types:

item
spell
companion

add + to scan the type's tooltip instead of the type's data

Keys:

Use as many comma-delimited keys as you want (ex: "quest item,use,blah,blah,blah")

The "companion" type must have "critter" or "mount" in the key list

Use ! in front of a key to exclude anything containing that key

Use ~ in front of a key to make that key optional

Shapes:

linear
circular

Points:

left
right
top
bottom
topleft
topright
bottomleft
bottomright
center

Substitutions -

Targets - returns the name of the specificed target

%p = "player",
%t = "target",
%f = "focus",
%tt = "targettarget",
%p1 = "party1",
%p2 = "party2",
%p3 = "party3",
%p4 = "party4",
%pt = "pet",
%mo = "mouseover",

Modifiers - returns additional information about the specified target or "target" if not specified

c = class
n = name
l = level
g = gender
r = race
h = health
m = mana
rt = raid target

+ = verbose feedback

Examples -

%f:n:c:l - returns the name, class and level of your focus target. If the information does not exist, nothing is returned.

%f:n:c:l+ - same as above, but if the information does not exist, feedack is given on what information does not exist.

%tt - returns the name of your target's target.

Notes -

Multiple subsititutions may be included on the same line -

%f:n:c:l

is the same as

%f:n %f:c+ %f:l

but allows for the feedback to be unique for each returned datum.

The following is a post I made on WoWInterface in answering the "whys" of discontinuing "Trinity Bars" and making "Macaroon". By this time, the "shock" should have subsided, but I post it here for the curious :)

First, I need to make an addon that was easier to maintain. The direction I was going with the whole TrinityUI thing was taking that in the wrong direction. I was making things too complex for myself where I almost got to the point that I had to document for myself my own "API".

Second, two things made me delve deeper into the world of macros - playing my mage to 70 and multi-boxing. Prior to that, I was not a heavy macro user. However, while going through the above, I found myself using the macro side of Trinity more and more and began to feel how "clunky" it felt to keep macros up-to-date. So I decided to make a macro-only bar addon - Macaroon.

Third, there are already action bar addon choices out there. I saw a hole for a macro addon. People want more of them. They want longer macros. They want an easier way to manage them. True, there are some macro solutions out there, but there was yet to be a "macro-bar" addon. So I decided to make the first truly macro-focused bar addon. So I started throwing it together, basically starting fresh where I knew I had issues in Trinity (I call them coding knots), but re-using Trinity's code where it was proven to be rock-solid. Macaroon, to me, has proven to be a much more enjoyable addon to code and maintain than Trinity, so I started to see what I could add to it. And I have not stopped adding yet. To date, Macaroon is almost as functional as Trinity. Only a few key features are missing, but I plan to add them as well (like anchor buttons).

I intended to update Trinity, but as I developed Macaroon more, it became obvious to me that the differences to the end user were small. To me, maintaining such addons as an author, the differences were huge. And I was getting plenty of positive feedback from Trinity users, such as being much easier to configure.

Fourth, I decided this time around to get all those extra items put into a totally separate addon, Macaroon Xtras. Those bars had been the most irritating for me to deal with in Trinity, mostly because of mistakes I made in how I set up handling them. But it was not easy to undo those mistakes without doing exactly what I did with Macaroon. Re-write with a clearer direction of where to go and remembering lessons learned.

Fifth, WoW 3.0 brings some big changes to action bar addons, almost to the same level as WoW 2.0. At least from an author's perspective. The whole internal mechanisms had to be re-coded from scratch. I was initially using Macaroon as a "test-bed" for learning the new API. However, it soon became apparent to me that really if I were to keep a "Trinity" addon going, all it would be is a Macaroon addon with a Trinity name. I was faced with possibility of maintaining two addons that were virtually identical for the sake of a name.

Why the name change, then? Why not keep "Trinity"? Well, I felt "Trinity" was feeling heavy. I wanted something that sounded more fun and light. I knew it was going to be a macro-bar addon, so I was looking for Mac-somthing. I went over a bunch in my head. And since I happen to *love* macaroons, it was the name that took. I also wanted to back away from the uni-name titles of my addons. It was a neat idea at first, thinking I would release a whole suite of "Trinity" addons (and indeed during WoW 2.0 I had many more "Trinity" addons I had never released), but yet again, the effort to maintain my own libraries across all the addons was becoming some serious work. So, in the end, I wanted to break away from the Trinity name (not because I don't like it, but because I want to be more creative and flexible in my addon making endeavors) and not lock myself down to a mono-theme name.

So, here we have Macaroon. It is, for all intents and purposes, really Trinity Bars 3.0, but with a new name and a new coding structure that will make it easier for me. So far during the public testing phase of Macaroon, issues have been minimal. And I don't get daily messages of "well, this is broken now, but thanks for fixing this!" which kinda stressed me out, to be honest. I needed to break away from where it was all going or I was just going to throw in the towel and stop publicly making a bar addon. I make addons for enjoyment, and Trinity was not heading in that direction.

Macaroon has been a new invigoration in terms of coding. Everything is falling into place and tough issues I had in Trinity are just being naturally solved via the new coding. The key to this all is that I am aiming to get to a point where I can release a version of Macaroon and it will stay stable for many months until Blizzard API changes affect it, not because I am constantly trying to undo tightly-tied coding knots I made in Trinity's code.

Macaroon is a new breed of bar addon, as well: a macro-bar addon. "Feel the power of macros" is a good catch phrase for it. Trinity was a highly involved action-bar addon that happen to do macros as well. My bar addon focus has shifted, and Macaroon reflects that in both design and name.

I can only hope that most Trinity users will like Macaroon as much as Trinity. The spirit and soul of Trinity is indeed in Macaroon. And I also hope that those who enjoyed the Trinity journey will join me on the Macaroon journey, as it is already going places Trinity has not.

-Maul