Description

MagnetButtons is an addon that can create any number of free moving action buttons. Any magnet button can be individually moved around anywhere on the screen, and will also snap (like a magnet) to any side of another magnet button that is the same scale. Each magnet button can do five different things based on the assigned button click (left, right, middle, button 4, or button 5) it receives; each of those clicks can also be assigned a hotkey.

MagnetButtons supports items, spells, trinkets, macros, flyouts, pet spells and actions, mounts, and toys. Support for companions is coming eventually; although in the meantime, you can implement them as macros. Macros can be defined right in the button's properties. For the sake of this addon and related documentation, attributes and properties are used interchangeably.

MagnetButtons REQUIRES the DoIt addon to run. Twitch will (hopefully) install the DoIt dependency automatically now, but keep this in mind when installing manually and/or updating. I write both addons, but they are separate addons.

Creating Buttons

You can create buttons automatically by mouse dragging something and dropping it right on to the background window, if you hold down the shift button on the drop. There is also a slash command "/newb" that will create a new empty button in the middle of the screen and a keyboard binding available for the /newb command.

Manipulating Buttons

Buttons can be changed at anytime (while not in combat) by using them as a drop target.
Press Control+LeftClick (over the button) to display a button's properties frame.
You can delete a single button from the button's properties frame.
Press Shift+LeftClick (over the button) to drag the button around. You can drag a button in-combat, but it will be unable to magnet-lock until combat ends.
Press Shift+Control+LeftClick (over a button) to drag an entire block of buttons (magnet locked together) to a new location.
Using the "Alt" key with a button will act normally (self-cast or cast).
You can delete all magnet buttons with the "/clearbuttons" or "/resetbuttons" slash command.

Properties

Button properties are divided into six tabs: General, Left Click, Right Click, Middle Button, Button 4, and Button 5. Most properties are not required (and will be ignored if set); the only required property is "type".

Let's walk though a button design from scratch... Type "/newb" slash command and MagnetButtons creates a new empty button in the center of the screen. Next, it's properties need to be set. While written for developers, SecureActionButtonTemplate has a lot of helpful information regarding which properties/attributes are used together.

Example: Show the macro dialog (left click), or toggle the game menu (right click). When entering the macro, don't enter the quotes. For additional macros, or to share your macros; check the Macro wiki page. The "+/" syntax is used to chain multiple slash commands in to the macrotext property (like multiple line macros), it's an addon specific way to show a new line.

Type (left) = "macro"
Macro Text (left) = "/macro"
Type (right) = "macro"
Macro Text (right) = "/cleartarget +/stopcasting +/script ToggleGameMenu(); StaticPopup1:Hide()"
Texture = 133741 (or any other)
Tooltip = "Show macro dialog (left click), or toggle the game menu (right click)"

Tooltips for Macros

Instead of a plain text tooltip for macros, you can instead specify the item or spell property to specify the tooltip. Blizzard will ignore that property for a macro, but MagnetButtons will use it to display the tooltip of the spell or item. Keep in mind, if you set the tooltip property; that overrides everything so keep tooltip property blank to do this. Example...

type = "macro"
spell = "Bear Form"
macrotext = "/stand +/cancelform +/cast Bear Form"

Targeting

MagnetButtons supports using specific spell-targets for a button. Unit targets can be set in the button's properties. Valid values for the unit property can be found here.

Global Settings

Global settings can be found in Interface -> Addons -> MagnetButtons or with the "/mbconfig" slash command.

Resources

Features In-Progress

Full support for all the bell's and whistles of other buttons (range dots, border flash, sparkle when cool-down expires, etc...)
The ability to control visibility, transparency, or enabled; based on spec, specific pet, or zone type (dungeons, raids, world, pvp, arena).
Support for companions in retail (in classic companions are items, and are supported by MagnetButtons)
Hide unusable properties for whatever the type specified is and constraining property values to valid values

Future Plans

Make an easy-mode, where the button editor looks kind of like the macros frame, with a multi-line editor and a dynamic texture (icon) selection.
Use addon messaging to quickly send buttons to people in your group.

Known Bugs and Issues

Cooldown times don't appear in the tooltips.
Setting the "unit" attribute seems to mess with the cursor changes when holding down ctrl or shift over a magnet button. This seems to be a Blizzard API issue.
A button's cooldown overlay is white instead of the normally black/dark color.
After a cinematic, MagnetButtons can't be clicked again until after a /reload. This seems to effect many addons. [April 2019]
This is unavoidable because of Blizzard restrictions... If you get on "combat devices" (a cannon for example) the remapping of keys 1-6 (if assigned to a MagnetButton as a hotkey) might not change for the device being used (if in combat); those key bindings might or might not take hold. Try to mount such devices/vehicles before you personally start combat. (Retail Only)

Debugging

When reporting bugs, debugging information will help me track down the problem, also state if bug is specific to retail, classic, or both.

-- To Enable Debugging
/script DoIt_Saved.Debug = true
/script SetCVar("ScriptErrors", "1")
/reload

-- To Disable Debugging
/script DoIt_Saved.Debug = false
/script SetCVar("ScriptErrors", "0")
/reload

Also it you are debugging I suggest BugGrabber and BugSack.

Credits

HUGE thanks to Semlar, author of AdvancedInterfaceOptions, for allowing me to use their widget to produce the properties editor! With having so many properties, an editor like this is invaluable.

Also a shout-out to imershon and mezz1945 who helped me by reporting issues that were lowering frame rates! Thanks, I appreciate all bug reports! :)

Discord (under construction): https://discord.gg/zSfX8HN