Bongos - Scripting

[Tuller]

With WoW 2.0 (The Burning Crusade), things like showing, hiding, and moving action buttons in combat will most likely no longer work. In response to this, I have the scripting functionality from Bongos

Note: This thread is a work in progress. Ask questions

"I want to make another actionbar change when I change stances."
"I want to make an actionbar hide when I have no target."
"I want to make all bongos bars become transparent when I'm in town."
"I want to make <bar> do <action> when <event> happens."

With the release of Bongos 6.8.23, all of those things are now possible via scripting. Scripting is a feature intended for advanced users. You're going to want to know a bit about Lua, the WoW API, in game events, and the code of Bongos itself.


Writing a Script

Open up the options menu, and go to the scripts tab. You'll see three sections: bar, event, and action.

Bar - The barID we want listening for the event, or "all" for all bongos bars. You can figure out a bar's ID, if the bar is shown, by unlocking bar positions. bags is for the bag bar, 1 for the actionbar 1, menu for the menu bar, etc. You can also specify a group of bars, ex bags menu key for the menu, bags and key bars, and a range of bars, ex 1-10 for actionbars 1 through 10.
Event - What event we're watching for. A good list of events can be found at the wiki
Action - What we do when the specified event happens. This part is written in Lua. You have access to the normal globals for an event (event, arg1, arg2, etc), as well as the bar the event is being called for (bar).
Run At Load - This checkbox makes the given action run right after all bars have been created.
Saving - Click the save button. Code will only be saved if there were no errors in it.


Useful Bongos Stuff

bar

• The bar a script is being run for.
• A bar is a frame. You have access to all frame functions.
• You can access a bar's ID via bar.id, or the function BBar.GetID(bar).

BBar - These functions work on all Bongos bars (action, class, bags, etc)

• BBar.Show(bar [, save])
  • Shows the given bar.
  • If save is true, then save the bar's settings
• BBar.Hide(bar [, save])
  • Hides the given bar.
  • If save is true, then save that the bar's hidden.
• BBar.Toggle(bar [, save])
  • Show the bar if it's hidden, hide the bar if it's shown.
  • If save is true, then save its new setting.
• BBar.Lock(bar)
  • Stops the given bar from moving, and hides its drag frame.
• BBar.Unlock(bar)
  • Lets the given bar move, shows its drag frame.
• BBar.SetScale(bar [, scale [, save]])
  • Sets the bar's scale.
  • This is different than frame:SetScale(scale) in that the top left position of the bar should remain constant
  • Prevents the drag frame's scale from changing.
• BBar.SetAlpha(bar [, alpha [, save]])
  • Sets the bar's opacity.
  • This is different than UIObject:SetAlpha(alpha) in that the drag frame for any given bar will not become completely transparent.
• BBar.GetID(bar)
  • Returns the barID of a given bar.
• BBar.IDToBar(barID)
  • Takes a barID, ex menu, bags, or pet, and returns its related bar.
• BBar.ForAll(action, arg1, arg2, ...)
  • Does action(bar, arg1, arg2, ...) to every bongos bar
  • If you wanted to say, make every bar transparent, you could do BBar.ForAll(BBar.SetAlpha, 0.5)

BActionBar - These functions only work on action bars.

• BActionBar.SetStanceOffset(barID, offset)
  • Switches a bar's page to barID + offset
  • It will not switch pages if you're manually paged (shift + number)
  • So, BActionBar.SetStanceOffset(2, 1) would change the second actionbar to have the same buttons as the third actionbar.
• BActionBar.SetContextOffset(barID, offset)
  • Switches a bar's page to barID + offset
  • It will not switch pages if you're manually paged (shift + number), and also not in a stance
  • So, BActionBar.SetContextOffset(2, 1) would change the second actionbar to have the same buttons as the third actionbar.

BProfile - These functions are used for loading and saving Bongos layouts. I don't have an exact time, but I would suggest not frequently loading profiles

• BProfile.Load(profileName)
  • Loads the given Bongos layout, if it exists.
• BProfile.GetDefault()
  • Returns the name of the default profile, if one exists.

BScript - These functions are used to define event actions for Bongos completely in Lua.

• BScript.AddEventAction(event, action [, runNow])
  • Adds a function for Bongos to run on the given event.
  • Any event can have multiple functions. These are called in the order they were added
  • When the event is called, the function that is being called is passed to the function, but not currently the event being called (note to self: Do that)
  • If runNow is true, then the event action will be run immediately after being saved.
• BScript.AddStartupAction(action [, runNow])
  • Adds an event action to run right after all addons have been loaded.
  • Right now, its equivalent to BScript.AddEventAction("VARIABLES_LOADED", action [, runNow])
• BScript.AddBarEventAction(barList, event [, action [, runNow]])
  • Adds an event action to be run for the given barList.
  • A bar list can be a single barID, ex class, a set of barIDs, ex class pet bags, a range of barIDs, ex 1-10, or all for all bars
  • Does not run if no bars currently exist in the given barList.
  • Currently, you can only have one action per bar event
  • If runNow is true, then the action will be run for the bar immediately after being saved.
  • When run, the action is passed both the event and bar, ex action(event, bar)
• BScript.RemoveEventAction(event, action)
  • Removes the given action from the list of things to run when the given event happens.
• BScript.RemoveEventForBar(event, barList)
  • Removes any event actions for all barIDs in the given barList on the given event
• BScript.CallEvent(event)
  • Runs all event scripts for the given event
• BScript.CallBarEvent(event)
  • Runs all bar event scripts for the given event
• BScript.CallBarEventForBar(event, barList)
  • Triggers the bar event script for all barIDs in the given barList

Examples

Making the second actionbar switch when you shapeshift/change stances:

bar:      2
event:   UPDATE_BONUS_ACTIONBAR
action:
BActionBar.SetStanceOffset(bar.id, GetBonusBarOffset())

Make the first actionbar hide when you don't have a target:

bar:      1
event:   PLAYER_TARGET_CHANGED
action:
if UnitExists("target") then
    bar:Show()
else
    bar:Hide()
end
Run at Load:  Checked

Make the tenth bar transparent when in combat. This one requires two scripts, one for entering combat, and one for leaving combat:

bar:      10
event:   PLAYER_REGEN_DISABLED
action:
BBar.SetAlpha(10, 0.5)
Run at Load:  Checked

bar:      10
event:   PLAYER_REGEN_ENABLED
action:
BBar.SetAlpha(10, 1)
Run at Load:  Checked