Bongos3

{{Addon Infobox }}
 * Name=Bongos3
 * TOC=2.4.0 (20400}
 * Category=Action Bars
 * Summary=A main action bar replacement
 * Author=Tuller
 * Bugtracker=Google Code
 * Changelog=Google Code
 * Releases=Google Code
 * WoWI=8419

Bongos3 is a main action bar replacement developed by Tuller in 2005. Bongos3 takes the main action bar, as well as some related components like the casting bar, and breaks them up into movable components. From there, Bongos3 then adds in some basic features, like the ability to create more action bars, make a bar transparent, or change the scale of each bar. Additionally, the action bars in Bongos3 are enhanced over the default interface. Right click selfcast, buff and debuff highlighting, customizable bar switching conditions, an enhanced out of range indicator, and a more intuitive binding method are also included.

Using Bongos3
The minimap button is your main hub for doing Bongos3 configuration. It'll be the one with the Bongos3 icon. Right click to open the options menu, shift left click to enter and exit binding mode, and left click to enter and exit configuration mode.

The Options Menu
The options menu is where general settings are set in Bongos3. The menu is split into two parts: General and Action Bars. The general panel contains all non action bar specific settings such as enabling or disabling sticky bars, bar visibility, and profile management.

You can access interface options via doing any of the following:
 * The /bongos slash command
 * Right clicking the Bongos3 minimap button
 * The AddOns tab of the interface options menu



Profiles
A profile in Bongos3 stores all Bongos3 related settings. It does 'not' currently save action button placement. By default, each character has a separate profile. Four profile operations are implemented: set, save, copy, and delete. Set will change the current active character to the selected profile. This allows the user to have multiple characters set to using the same settings. Save will create a copy of the user's current profile as a given name, then set the current user to that profile. Copy will copy all settings from the selected profile to the current profile. Delete will remove a profile.

Configuration Mode
Configuration mode is where it is possible to move bars around, adjust a bar's settings, or create new action bars. To adjust a bar's settings, enter configuration mode, then right click the desired bar to bring up the bar's right click menu. Every Bongos3 bar has a right click menu for adjusting settings. It is encouraged that all users look through the right click menus for each bar to discover all configuration options.

You can access configuration mode via doing any of the following
 * The '/bongos config' or '/bongos lock' slash commands
 * Left clicking the Bongos3 minimap button

To exit configuration mode, just use the same command you used to enter it.

Bindings Mode
Bindings mode is where it is possible to set hotkeys for all action bars, the pet bar, the class bar, the macro menu, and the spell book. To bind a key, hover over the button and press desired key combination, such as Alt + 1, W, or Mouse Wheel down. It is possible to bind keys to any mouse button recognized by the game, other than the left and right buttons. All bindings, except for the action bar, are saved in the same way as the standard binding system does, and respects the same per character option. Action bar bindings are treated as an overlay of the normal binding system, and are attached to a Bongos3 profile.

You can access bindings mode by doing any of the following:
 * Typing the '/keybound or '/kb' slash command
 * Shift-Left clicking the Bongos minimap button

To exit binding mode, use whichever command you used to enter it.

Slash Commands
Bongos3 features a fairly rich set of slash commands. All bongos commands, with the exception of the binding mode toggle, can start with either /bongos, /bob, /bgs, or /bg3. The parameter  can be either a single bar id, ex 'menu'; a space separated list of bar ids, ex 'bags pet 1'; a range of bars, ex '1-10'; 'all'; or any combination, ex '1-10 menu bags pet all'


 * No arguments: Shows the options menu, if enabled.
 * config: Toggles configuration mode
 * sticky: Toggles the ability to dock bars to each other in configuration mode
 * scale  : sets 's scale to . 1 is normal scale
 * setalpha  : sets the opacity of . 0 is completely transparent, 1 is completely opaque
 * setfade  : sets the faded opacity of . A bar's faded opacity is what opacity a bar has when not moused over
 * show : shows 
 * hide : hides 
 * toggle : toggles 
 * set : switches to
 * save : saves current settings as, and switches to
 * copy : copies settings from to current profile
 * delete : deletes
 * reset: returns the current profile to default settings
 * list: lists all available profiles
 * version: prints the current Bongos version
 * /keybound: toggles binding mode (only available with Bongos_AB)

The 120 Button Limit
Bongos3 is a traditional action bar addon, and thus subject to the 120 action button limit. A bar consumes the amount of action buttons based on the following formula: * *. Delete or reduce the effective size of a bar to free up action buttons.

The Possess Bar
The possess bar is a special state which causes your action bar to change when you lose control of your character and gain control of another. This is used, for example, during the Karazhan chess event, the Priest's Mind Control ability, or Hunter's Eyes of the Beast ability. You can set which action bar should act as the posses bar via checking the "Act as Possess Bar" option in the given bar's right click menu. If no bar is set to be the possess bar, then it will default to the pet bar.

Creating and Deleting Action Bars
Bongos3 allows the user to divide the 120 available action slots into as many bars as desired. To create a new bar, enter configuration mode, and simply hold down alt and drag to create a bar. A green or red rectangle will be displayed showing the currently selected size, such as 1x12 for an action bar with 1 row and 12 columns. If the box is green, then there are enough action slots available to create a new bar of the desired size. If the box is red, there are not.

To free up action slots, one must reduce the size of an action bar, or delete it entirely. Reducing the size of a bar can be done via lowering the rows, columns, and action sets values for a given bar in its right click menu. Deleting a bar is done via  in configuration mode.

Changing an Action Bar Under a Given Condition (Paging)


A page, in Bongos3, is a set of actions. Each action bar have multiple pages. For each state condition, you tell Bongos3 either which page of an action bar to display, or to ignore the state completely (disable). All sliders for paging are contained in each action bar's right click menu, organized by category. Bindings are action bar specific, and thus will stay the same no matter what page an action bar is displaying.

Here are the default states Bongos3 can page in, and in which order:
 *  Down: Occurs when you press control, alt, or shift
 * Action Page : Occurs when you press a paging binding. These are bound, by default, to shift + 1-6 and shift + mouse wheel. Shift + 1 returns to your normal state
 * Prowl (Druids Only): Occurs when prowling
 * Stances, Forms, Stealth: Occurs when you're in Defensive stance, Cat form, stealth, etc.
 * Friendly/Enemy Target: Occurs when you're targeting a friendly or enemy target

So alt will be checked before page 2, which will be checked before cat form, which will be checked before friendly/enemy targeting.

Differences from Bongos2
The bar switching systems in Bongos2 and Bongos3 are very different. In Bongos2, you would say, "This bar should show the buttons on bar3 when in cat form, and bar2 when in bear form" Lets call this bar mirroring. Bongos2 could get away with bar mirroring, since every bar has the same effective size. Bongos3, however, does not have that limitation. So telling Bongos3 that you would want bar 1 to show the buttons on bar 2, when bar 2 is a single button, and bar 1 is 30, would not make very much sense. So instead, you tell Bongos3, "This bar should have three pages of buttons. When I'm in cat form, use set two, when I'm in bear form, use page three, otherwise use page one"

The Druid Example
Say, you're a druid, and want to have a bar change dependent on if you're in bear, cat, or caster form. Here's what you'd do:
 * First determine how many pages we need. For our example, we'll need three pages (one for cat, caster, and bear).  So, we'll enter configuration mode, right click the bar we want to switch, and set the Pages slider to 3.
 * If, for some reason, we cannot increase the pages slider to 3, it means we don't have enough action buttons around to give the bar three pages. We have two options:  We can delete a bar, or resized this one.
 * Once we've set the pages slider to 3, its time to set which page to use for which form. To do so, select the druid panel from the action bar's right click menu.
 * Next, adjust the slider for Cat Form to page 2.
 * Next, adjust the slider for Bear Form to page 3.
 * Set all other sliders to disabled. This will tell Bongos3 to ignore all other states.
 * Your bar will now switch to page 2 of the action bar we've changed when in cat form, and page 3 when in bear form, and page 1 when in caster form. Try it out.

You may notice that there was no slider for caster form. This is because, on druids, caster form is the default state. The default state for an action bar will always use the first page of an action bar.

Showing An Action Bar Only Under Certain Conditions


Suppose, for example, you wish to make an action bar show only when in combat. This is possible in Bongos3. First, enter configuration mode, and right click the bar you wish to edit. Next, choose the show states option from the dropdown. You'll see an edit box and an okay button. In the text box, enter in [combat], then press the okay button. If you're not in combat, then the bar should immediately hide. To remove the setting, simply clear the edit box, and press okay. The bar should then immediately reappear.

All macro options are valid conditions for show states.

Plug-Ins
There are some addons that may enhance Bongos3:
 * Bongos Cornucopia: Provides many extra Bongos3 bars
 * Fubar - Bongos3Fu: Adds a menu in FuBar for quick access to Bongos configuration.
 * CyCircled / ButtonFacade: These 2 mods change the look of various buttons, including Bongos3 action buttons.

Using Bongos3 Bars in Lua
Bongos3 bars are all nameless. To retrieve a bar use: local bar = Bongos3.Bar:Get() Where <id> is the name of the bar you see when in configuration mode, like 1, bags, or menu.

To perform an operation on a bar use: Bongos3.Bar:ForBar(<barList>, 'Method', arg1, arg2, ...) The parameter <barList> can be either a single bar id, ex 'menu'; a space separated list of bar ids, ex 'bags pet 1'; a range of bars, ex '1-10'; 'all'; or any combination, ex '1-10 menu bags pet all'

Custom Paging Conditions
Say, for example, you wish to make a bar switch when under a certain condition, like when mounted, but that condition is not found within the right click menu in Bongos. It is possible to still have your action bar change, provided that condition is a valid macro option, but it will require a bit of Lua hacking. Please take a look at the example addon I've created for this, located here