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

[Khuas]

This is beautiful, Tuller.

Please bear with me as I'm a newb at this and don't have access right now to my WoW machine.

With the examples you list, are the functions SetStanceOffset(), Show() and Hide() specific to Bongos or are they Blizz/WoW functions? I don't see them at the Wiki but then I might not be looking in the right place.

If they are Bongo specific, do you have a list of functions available?

In the second example with the target/hide, I know that bar is a reference to the bar the event has occurred on - are there other globals you have available for use here?

Again, forgive me if my questions are dumb, just started replaying WoW after a year off and probably trying to learn too much at a time.

[shadowknight456]

Nice, this is one thing i was lookin to use in Bongos, but i was wondering if instead of just hiding the bar, i could changes it's transperancy?

[brotherhobbes]

Originally Posted by shadowknight456 Nice, this is one thing i was lookin to use in Bongos, but i was wondering if instead of just hiding the bar, i could changes it's transperancy?

should be able to use http://www.wowwiki.com/API_UIObject_SetAlpha

[shadowknight456]

Originally Posted by brotherhobbes should be able to use http://www.wowwiki.com/API_UIObject_SetAlpha

Yay! It works, but (i know, i have too many questions )if i could make it so when my health is below a certain percent it shows the bar, also, instead of having a target it would set the alpha, when i enter /leave combat it would change the alpha, i almost got it to work, but it wouldnt switch back when i went out of combat, if i could have some help that would be awesome!

[Tuller]

Whenever an event occurs, you have access to:

• bar - What bar the event is being fired for
• event - What event is being fired
• Any args an event has. You can figure out what these are by looking at the events list

With the examples you list, are the functions SetStanceOffset(), Show() and Hide() specific to Bongos or are they Blizz/WoW functions? I don't see them at the Wiki but then I might not be looking in the right place.

Show() and Hide() are frame functions
Bongos functions will look like BBar.Funct, or BActionBar.Funct. I'll end up making a list of the useful ones soonish.

if i could make it so when my health is below a certain percent it shows the bar, also, instead of having a target it would set the alpha, when i enter /leave combat it would change the alpha, i almost got it to work, but it wouldnt switch back when i went out of combat, if i could have some help that would be awesome!

For health, you need to use the event UNIT_HEALTH. Scroll down a bit to find the event.
For combat, you need to make two scripts: One that fires on PLAYER_REGEN_DISABLED (in combat), PLAYER_REGEN_ENABLED (out of combat)

[Flarin]

I will try this myself, I am curious to see the effect with my Troll- I think I regen a little while still in combat.

[backslash83]

I'have just a question, is there a way to make one bar switch page when the target in in melee range and then switch back when he leaves melee range, i'm just waiting for this to switch from dab to bongos even with my hunter

[Delsphynx]

Is it correct to assume that the UNIT_HEALTH event would cause a script to be fired any time a unit health changes - meaning, target health, your health, party health, raid health, etc. etc.?

What I'm trying to figure out is an eloquent way to have a button appear when, say, something can be Executed. The script itself is pretty straightforward, using UnitHealth("target") < 20. The part I can't get past is how to set up the event to run the script. What I really need is an event for the target's health changing, only. It just seems there has to be a way to do that, without tying in to every unit health change that is happening. Maybe I'm assuming that lots of unit health event firings is a performance issue, and it really isn't that bad?

[Tuller]

Welcome to the land of conditionals

event: UNIT_HEALTH
action:
if arg1 == "target" then
    if UnitHealth("target") <= 20 then
        bar:Show()
    elseif not bar:IsShown() then
        bar:Hide()
    end
end

This event WILL still fire on every unit health event, but it won't do much on it. I'm going to end up upgrading the event system a bit so you can specify a group of bars like you can in slash commands.

It's possible to do custom events via the function BScript.CallBarEvent(event), and here's how the previous code would probably look like using one:

event: UNIT_HEALTH
action:
if arg1 == "target" then
    arg1 = UnitHealth("target")
    BScript.CallBarEvent("BONGOS_TARGET_HP_UPDATE")
end

event: BONGOS_TARGET_HP_UPDATE
action:
if arg1 <= 20 then
    bar:Show()
elseif not bar:IsShown() then
    bar:Hide()
end

[Delsphynx]

Aaah, so that is how you would use the arguments passed from the event. Simple!

This is great for me, because aside from setting up some really cool UIs, it is also teaching me a lot about events and such, how they fire, and all that jazz.

This is cool

[backslash83]

ok i menaged to get an idea on how to do the range thingy, something like:

 
bar:      1
event:  [here is the problem]
action:
if IsActionInRange(100) then
    BActionBar.SetStanceOffset(1, 2)
else
   BActionBar.SetStanceOffset(1, 0)
end
Run at Load:  Checked

but i don't understand on witch event should it be checked and if the second BActionBar.SetStanceOffset il correct to switch the bar on it's original state.

[moniker]

Originally Posted by backslash83 I'have just a question, is there a way to make one bar switch page when the target in in melee range and then switch back when he leaves melee range, i'm just waiting for this to switch from dab to bongos even with my hunter

I'm really looking forward to this functionality as well, if it's possible.

I took a look at the events, but I don't see one that would fire when in range/out of range, as I guess it depends on a particular action. If I'm missing it, please correct me!

If there isn't, is there any way we could get a couple of custom events? Maybe something like:
BONGOS_IN_RANGE_ATTACK (for melee)
BONGOS_IN_RANGE_SHOOT (for ranged)

Thanks!

moniker

[Tuller]

If there isn't, is there any way we could get a couple of custom events? Maybe something like: BONGOS_IN_RANGE_ATTACK (for melee) BONGOS_IN_RANGE_SHOOT (for ranged)

I'll probably end up making a plugin to add those events. I'm fairly sure that its based on watching a skill for changes in usability.

[Scae]

I love the new ability to page a bar other than the main bar on stance changes.

However. With bar 1 paging to bar 7, 8, 9 on stance changes. Followed by bar 2 paging to 3, 4, 5. Meaning 8 bars are taken up by stance changes. Leaving two.

Now, I wondered if there's a way to get more bars out of my setup (well, just need one more really). Seems a waste to have 1 and 2 essentially empty and *just* used to paging, rather than being used for the first stance with two bars following for other stances.

Is this possible? Or is that just the way?

[aythya]

This is great. I switched from flex to bongos a while ago to have something a little more light weight, and I've been missing some of it's functionality.

Specifically, is there any way to show/hide bars on mouse enter/leave? Or show/hide bars on keybinding down/up?

I've looked at the event api wiki, and don't really see anything that would do that by default, without really digging into the bongo's xml.

[darkforce898]

found a bug, related to scripting i think. i can still use the buttons but all the icons are gone, if i move the spell, the icon reapeers

[Tuller]

Now, I wondered if there's a way to get more bars out of my setup (well, just need one more really). Seems a waste to have 1 and 2 essentially empty and *just* used to paging, rather than being used for the first stance with two bars following for other stances.

You can't have more than 120 buttons, that's a blizzard limit. But I think you just want to make it so that if you're on a certain stance, then bar 1 and bar 2 don't change pages. Here's how that'll look:

if GetBonusBarOffset() == <whatever your default stance is> then
    BActionBar.SetStanceOffset(bar.id, 0)
else
    BActionBar.SetStanceOffset(bar.id, GetBonusBarOffset())
end

found a bug, related to scripting i think. i can still use the buttons but all the icons are gone, if i move the spell, the icon reapeers

Bongos bug. I don't update the textures for bars that aren't shown when paging, and forgot to do it OnShow. I fixed it in 6.8.28.

Specifically, is there any way to show/hide bars on mouse enter/leave? Or show/hide bars on keybinding down/up?

I'm going to have to hardcode autohiding. The show on key press is something that can only be done via macros at this point, and I'm not absolutely sure how to do keypress events short of making keybindings for 120 bars.

[darkforce898]

but i dont use paging, i only use show on target, and it happens everytime i log out

[Khahli]

Is it possible if you could post a screenshot of the scripting GUI with a function script in it?

I'm trying to make the following code run:

bar: class
event: PLAYER_REGEN_DISABLED

action:
BBar.SetAlpha(class, 0.5)
BBar.SetAlpha(9, 1)

Run at Load: Checked


I receive the following error:

Interface\AddOns\Bongos\bar.lua:262:attempt to index local `bar'(a string value)


Using the following code results in the same error:

bar: 9
event: PLAYER_REGEN_ENABLED

action:
BBar.SetAlpha(9, 0.5)
BBar.SetAlpha(class, 1)

Run at Load: Checked