LibAvion-2.0

From WowAce Wiki

LibAvion-2.0 and LibAvionEmbed-2.0 - API Documentation

Miscellaneous notes

LibAvion-2.0 is a library that allows you to easyly trigger visual effects/animations while LibAvionEmbed-2.0's main purpose is to support developers in managing lists of animations, giving tools to add and delete animations and make them easyly editable. You can see an example addon using LibAvion-2.0 here

Example addon

-- Create a Rocky addon
MyAddon = Rock:NewAddon("AvionTest1", "LibRockConfig-1.0", "LibAvionEmbed-2.0")

-- Grap yourself some Libs
local LibAvion = LibStub:GetLibrary("LibAvion-2.0")

-- This are my saved Variables
MyAddonDB = {
	animationTables = {}
}

-- Ignore me
local onlyAnimation

-- Register addon with avion
function MyAddon:OnInitialize()
	self:LinkAnimationDB(MyAddonDB.animationTables)
	
	local avionOpts = self:GetAvionOptionTable()
	
	self:SetConfigTable({
		order = 1,
		type = 'group',
		name = "Avion Options",
		desc = "Imba leet addon",
		icon = [[Interface\WorldMap\UI-World-Icon]],
		args = avionOpts,
	})
end


-- Add new anim when enabling
function MyAddon:OnEnable()
	self:RegisterCallback("LibAvion_DeleteAnimation", "OnDelAnimation")
	
	onlyAnimation = self:NewAnimation(nil, "MyAddon_Anim1")
end


-- Delete anim when disabling 
function MyAddon:OnDisable()
	self:UnregisterCallback("LibAvion_DeleteAnimation")
	LibAvion:StopAllAnimations(false)
	
	self:DelAnimation(onlyAnimation)
end


-- Do something
function MyAddon:ON_WORLDS_END()
	self:TriggerAnimationByID("WORLDS_END_OH_NOSSS", onlyAnimation)
end


-- Anim deleted, see if there's something to do
function MyAddon:OnDelAnimation()
	for animationID, animationName in MyAddon:AnimationIterator() do
		if (onlyAnimation == animationID) then
			onlyAnimation = nil
		end
	end
end


-- Wanna have some options menu
function MyAddon:OptionMenu()
	self:OpenConfigMenu()
end

LibAvion-2.0 - API

:TriggerAnimation(triggerID, animationTable)

Arguments

triggerID

string - a unique identifier, to allow to stop animation if needed.

animationTable

table - table that contains animations information, see extra section.

Notes

• Will trigger the animation given by animationTable. As long as animation is still active it can be canceled with the given triggerID.

Example

LibAvion:TriggerAnimation("HelloWorld", {...})

:StopAnimation(triggerID, fadeOut)

Arguments

triggerID

string - a unique identifier.

fadeOut

boolean - wether or not the frame should be smoothly faded out or just disapear.

Notes

• Will cancel the given animated refered to by triggerID.
• If fadeOut is true, frame will (slowly) fade out. (Will have no effect when frame is allready fading)

Example

LibAvion:StopAnimation("HelloWorld", true)

:StopAllAnimations(fadeOut)

Arguments

fadeOut

boolean - wether or not the frame should be smoothly faded out or just disapear.

Notes

• Will cancel all animation.
• If fadeOut is true, frame will (slowly) fade out. (Will have no effect when frame is allready fading)

Example

LibAvion:StopAllAnimations(false)

:IsAnimationRunning(triggerID)

Arguments

triggerID

string - a unique identifier.

Notes

• Will return if animation with given identifier is allready running

Example

if (LibAvion:IsAnimationRunning("HelloWorld")) then

LibAvion:StopAnimation("HelloWorld", true)

end

LibAvionEmbed-2.0 - API

:AddTexture(key, value)

Arguments

key

string - the name you want to give the texture.

value

string - the path and filename of the texture.

Notes

• This will add a new texture thus it can be used in the options panel

Example

MyAddon:AddTexture("HelloWorld", "Interface\\AddOns\\HelloWorld\\HellWorld.tga")

:AddSound(key, value)

Arguments

key

string - the name you want to give the sound.

value

string - the path and filename of the sound.

Notes

• This will add a new sound thus it can be used in the options panel

Example

MyAddon:AddSound("HelloWorld", "Interface\\AddOns\\HelloWorld\\HellWorld.mp3")

:AddFunc(key, value)

Arguments

key

string - the name you want to give the function.

value

string - the path and filename of the function.

Notes

• This will add a new function thus it can be used in the options panel
• Function can be used to give an animation some uniqueness, think of it as an interpolation. The function determins how to interpolate between animation steps.
• Param is the value that the function gets passed by the UpdateAnimation handler. For a resently start animation its 0 and for one thats nearly finished its 1.

Example

MyAddon:AddFunc("x^5", "param*param*param*param*paran")

:LinkAnimationDB(animationList)

Arguments

animationList

table - link to your saved variable or a sub-table.

Notes

• This will tell to use animationList as its internal animation database.
• If you want to save animation data accross session, you should add a sub-table of your saved-variables.

Example

TOC:
## SavedVariables: MyAddonDB
LUA:
MyAddonDB = {

myDB = {}

}
...
MyAddon:LinkAnimationDB(MyAddonDB.myDB)

:AnimationIterator()

Arguments

Notes

• Will return an iterator function that will return all available animations by name and id

Example

for animationID, animationName in MyAddon:AnimationIterator() do

...

end

:GetAvionOptionTable()

Arguments

Notes

• Will return a LibRock-1.0 like table containing options to manage, create and edit your addons animation database.

Example

local ops = MyAddon:GetAvionOptionTable()
MyAddon:SetConfigTable({

order = 1, type = 'group', name = "MyOptions", desc = "Here stands nothing", args = ops,

})
MyAddon:OpenConfigMenu()

:NewAnimation(animationTable, newName)

Arguments

name

string - name for the animation.

animationTable

table - animation data.

Notes

• Will create a new animation with default options an add it to the database if animationTable is nil otherwise it will add data from animationTable to database.
• Will also fire "LibAvion_NewAnimation" return the unique id of the created animation.
• Will also return animationID (unique key for this animation) that it got assigned to.

Example

MyAddon:NewAnimation("HelloWorld")

:DelAnimation(animationID)

Arguments

animationID

string - unique id of animation in database.

Notes

• Will delete this animation from database.
• Will also fire "LibAvion_DeleteAnimation" return the unique id of the animation.

Example

MyAddon:DelAnimation(10)

:TriggerAnimationByID(triggerID, animationID)

Arguments

triggerID

string - unique id of animation that can be used to cancel it.

animationID

string - unique id of animation in database.

Notes

• Will trigger the animation from database with id animationID and give it the unique id triggerID, which can be used to cancel the running animation.
• More specificly this will call LibAvion:TriggerAnimation(triggerID, MyAddon.SavedVariables.animationTables[animationID])

Example

MyAddon:TriggerAnimationByID("HelloWorld", 10)

:BuildAnimationOption(animationID)

Arguments

animationID

string - unique id of animation in database.

Notes

• This will return the options table for this animation

Example

myOps = self:BuildAnimationOption(10)

:ShowGuideFrame(animationID)

Arguments

animationID

string - unique id of animation in database.

Notes

• Will show the Guide-Frame for this animation
• Guide-Frame is an easy way to setup some basic anmation values

Example

self:ShowGuideFrame(10)

:HideGuideFrame(animationID)

Arguments

animationID

string - unique id of animation in database.

Notes

• Will hide the Guide-Frame for this animation

Example

self:HideGuideFrame(10)

:UpdateGuideFrame(animationID)

Arguments

animationID

string - unique id of animation in database.

Notes

• Will update the Guide-Frame for this animation, eg. this is called whenever a setting for this animation was changed

Example

self:UpdateGuideFrame(10)

:UpdateAllGuideFrames()

Arguments

Notes

• Will update all (active) Guide-Frames

Example

self:UpdateAllGuideFrames()

:IsGuideFrameShown(animationID)

Arguments

animationID

string - unique id of animation in database.

Notes

• Will return true if the Guide-Frame for this animation is currently active

Example

if (self:IsGuideFrameShown(10)) then

self:UpdateGuideFrame(10)

end

Callback API

 :RegisterCallback()

myAddon:RegisterCallback("eventName"[, method[, arg]])
library.RegisterCallback(myTable, "eventName"[, method[, arg]])
library.RegisterCallback("myAddonId", "eventName"[, method[, arg]])

 :UnregisterCallback()

myAddon:UnregisterCallback("eventName")
library.UnregisterCallback(myTable, "eventName")
library.UnregisterCallback("myAddonId", "eventName")

 :UnregisterAllCallbacks()

:UnregisterAllCallbacks()
library.UnregisterAllCallbacks("myAddonId", myTable, ...)

Callbacks Fired

LibAvion_MenuUpdate

Arguments

Notes

• Is fired everytime the options table need to be/is updated, eg. new animation was added oder something important changed.

LibAvion_MenuRequest

Arguments

animationID

number - unique ID of the animation that was added to internal database

guideFrame

frame - the Guide-Frame that is currently displayed for this animation

Notes

• Is fired when someone presses the "menu-button" unter the Guide-Frame

LibAvion_NewAnimation

Arguments

animationID

number - unique ID of the animation that was added to internal database

Notes

• Is fired whenever a new animation was added.

LibAvion_DeleteAnimation

Arguments

animationID

number - unique ID of the animation that was deleted from internal database

Notes

• Is fired whenever an animation was deleted.

AnimationTable format

Below you can see an overview of how the table needs to be formated, that is passed to ":TriggerAnimation(triggerID, animationTable)". You only should need to bother about this, when triggering an animation "by hand" without using all the neat addition in LibAvionEmbed-2.0.

{
	alpha 			= Alpha value when its shown (number)
	color 			= {
		r		= Red color when its shown (number)
		g 		= Green color when its shown (number)
		b 		= Blue color when its shown (number)
	}
	position 		= {
		x 		= X-Position on screen when its shown (number)
		y 		= Y-Position on screen when its shown (number)
	}
	size 			= {
		width 		= Width when its shown (number)
		height 		= Height when its shown (number)
	}
	rotation 		= Rotation of texture when its shown (number)
	isAnimated 		= {
		color 		= Should color be animated? (bool)
		position 	= Should position be animated? (bool)
		scale 		= Should scale be animated? (bool)
		rotation 	= Should rotation be animated? (bool)
	}
	animation 		= {
		color 		= {
			r 	= Red color that is beeing animated to (number)
			g 	= Greem color that is beeing animated to (number)
			b 	= Blue color that is beeing animated to (number)
		}, 
		position 	= {
			x 	= X-Position that is beeing animated to (number)
			y 	= Y-Position that is beeing animated to (number)
		}, 
		scale 		= Scale that is beeing animated to (number)
		rotation 	= Rotations of texture that is beeing animated to (number)
	}
	animationFunc		= {
		alpha 		= Smoothness/speed of alpha animation (function)
		color 		= Smoothness/speed of color animation (function)
		position 	= Smoothness/speed of position animation (function)
		scale 		= Smoothness/speed of scale animation (function)
		rotation 	= Smoothness/speed of rotation animation (function)
	}
NOTE: All of this function HAVE to be pointers to function with head 
"function (param, rnd)", where param gonna be a value between 0 (start)
and 1 (end), depending on the time the animation is still running.
rnd is the value that can be set in the options dialogue under "Randomness",
its meant to add some random effect.
	addRandom 		= {
		alpha 		= Add some randomness to alpha animation (number)
		color 		= Add some randomness to color animation (number)
		position 	= Add some randomness to position animation (number)
		scale 		= Add some randomness to scale animation (number)
		rotation 	= Add some randomness to rotation animation (number)
	}
	animateAndFade 		= Continue animation when fading out 
NOTE: This will NOT work when Fade-Stopping the animation! (bool)
	animationTime 		= The time the "animation" phase should take
	fadeTime 		= The time it should take the frame to fade 
				out after completion (number)
	waitTime 		= The time it should take from triggering the 
				animation until the actual animation should start 
NOTE: Can be used to create difficult multi-animations. (number)
	showWhileWait 		= Allready show the frame/animation while
				 "waitTime" is yet running (bool)
	textureFile 		= Texture file (file link, no SharedMedia!) to 
				the texture that should be used (string)
	soundFile 		= Sound file (file link, no SharedMedia!) to 
				the sound that is triggered as soon as the 
				animation starts (string)
	mirror 			= {
		x 		= Mirror texture on x-axis (bool)
		y 		= Mirror texture on y-axis (bool)
	}
	noEnd 			= The animation won't fade when its finished, but
				will rather need to be stopped with 
				LibAvion:StopAnimation(...) (bool)
}