This file contains a reference for all of MSBT's publicly accessible functions and structures.
Table of Contents:
Displaying Messages Overview

Return to TOC
MSBT allows you to output messages via the MikSBT.DisplayMessage function. You can either output the messages using one of the existing fonts, which can be obtained with the MikSBT.GetRegisteredFontList function, or first use the MikSBT.RegisterFont function to use your own custom font.
Additionally, you may call the MikSBT.GetScrollAreaList function to get a list of valid scroll areas in which the message may be displayed.
MikSBT.RegisterFont

Return to TOC
Registers a font with MSBT.
Font registration is not permanent. It must be done each load. In this manner if the user were to remove a mod that registers custom fonts, the fonts would simply no longer be available. If anything in MSBT has a custom font selected that is no longer registered, MSBT will recognize that an invalid font is specified and use the default font accordingly.
Syntax
MikSBT.RegisterFont(fontName, fontPath)
Parameters

fontName (Required) | The name to use for the font. This name will be displayed in the font selection dialogs, and also is the name to be referenced when displaying messages via the MikSBT.DisplayMessage function.
fontPath (Required) | The filesystem path to where the font resides.

Return Values
None.
Example
-- Registers a font named "MyUberFont" with MSBT.
MikSBT.RegisterFont("MyUberFont", "Interface\\AddOns\\MyModName\\Fonts\\MyUberFont.ttf");
Remarks
If you attempt to register a font name that already exists, the function will quietly fail.
MikSBT.DisplayMessage

Return to TOC
Displays the passed message with the passed formatting options.
Syntax
MikSBT.DisplayMessage(message [, scrollArea, isSticky, colorR, colorG, colorB, fontSize, fontName, outlineIndex])
Parameters

message (Required) | The string to display.
scrollArea (Optional) | Specifies the scroll area index or scroll area name in which to display the message. You can get a list of available scroll areas with the MikSBT.GetScrollAreaList function, or use one of the following predefined values: MikSBT.DISPLAYTYPE_INCOMING MikSBT.DISPLAYTYPE_OUTGOING MikSBT.DISPLAYTYPE_NOTIFICATION If the parameter is omitted or invalid a default of MikSBT.DISPLAYTYPE_NOTIFICATION will be used.
isSticky (Optional) | Specifies whether or not the message should be displayed sticky style. This must be either true or false. If the parameter is omitted a default of false will be used.
colorR (Optional) | The red component of the color to display the message with. Value range is 0-255. If the parameter is omitted a default of 255 will be used.
colorG (Optional) | The green component of the color to display the message with. Value range is 0-255. If the parameter is omitted a default of 255 will be used.
colorB (Optional) | The blue component of the color to display the message with. Value range is 0-255. If the parameter is omitted a default of 255 will be used.
fontSize (Optional) | The font size to use. Value range is 12-32. If this value is omitted or an invalid value is passed the settings for the scroll area will be used.
fontName (Optional) | The name of the font to use. You can get a list of available font names with the MikSBT.GetRegisteredFontList function. If the parameter is omitted or an invalid font name is passed the font for the scroll area will be used.
outlineIndex (Optional) | The index of the outline to use. The valid values are: 1 - No Outline 2 - Thin 3 - Thick If the parameter is omitted or an invalid index is passed the outline index for the scroll area will be used.

Return Values
None.
Examples
-- Displays "Test Message" in the notification scroll area in white.
MikSBT.DisplayMessage("Test Message");
-- Displays "Another Message" in the incoming scroll area in white as a sticky.
MikSBT.DisplayMessage("Another Message", MikSBT.DISPLAYTYPE_INCOMING, true);
-- Displays "Uber Damage!" in the outgoing scroll area in blue.
MikSBT.DisplayMessage("Uber Damage!", MikSBT.DISPLAYTYPE_OUTGOING, false, 0, 0, 255);
-- Displays "Enemy begins to flee in fear" in the notification scroll area in green with the scroll area's
-- font size, the font set to Yellowjacket, and no outline.
MikSBT.DisplayMessage("Enemy begins to flee in fear", nil, false, 0, 255, 0, nil, "Yellowjacket", 1);
Remarks
Since this function specifies the font name to use, you can use custom fonts by first registering them via the MikSBT.RegisterFont function.
MikSBT.GetRegisteredFontList

Return to TOC
Returns a new table array containing a list of registered fonts.
Syntax
registeredFonts = MikSBT.GetRegisteredFontList()
Parameters
None.
Return Values

registeredFonts | A new table array containing a list of registered fonts. The format is as follows: [1] = "First Font Name" [2] = "Second Font Name"

Examples
-- Get a list of registered fonts from MSBT.
local registeredFonts = MikSBT.GetRegisteredFontList();
-- Loop through all of the entries and print the font names.
for index, fontName in ipairs(registeredFonts) do
DEFAULT_CHAT_FRAME:AddMessage(fontName);
end
Remarks
None.
MikSBT.GetScrollAreaList

Return to TOC
Returns a new table array containing a list of scroll areas.
Syntax
scrollAreas = MikSBT.GetScrollAreaList()
Parameters
None.
Return Values

scrollAreas | A new table array containing a list of available scroll areas. The format is as follows: [1] = "First Scroll Area Name" [2] = "Second Scroll Area Name"

Examples
-- Get a list of scroll areas from MSBT.
local scrollAreas = MikSBT.GetScrollAreaList();
-- Loop through all of the entries and print the scroll area names.
for index, scrollAreaName in ipairs(scrollAreas) do
DEFAULT_CHAT_FRAME:AddMessage(scrollAreaName);
end
Remarks
None.
Custom Animation Styles Overview

Return to TOC
MSBT has a custom animation style registration system that allows other mod authors to create new animation styles.
The system works by using callback functions that you specify at the time you register the animation style with the MikSBT.RegisterAnimationStyle and MikSBT.RegisterStickyAnimationStyle functions. The callback functions receive recycled DisplayEvent tables that contain all information about an animating event such as it's x and y position, it's alpha (opacity), the height of the scroll area it's animating in, how long it's been animating, and the user specified animation speed.
There are three callback functions:

InitDisplayEvent | This function receives a new DisplayEvent table and an array of DisplayEvents that are currently active for the scroll area using the same animation style. It should establish the initial settings for the new DisplayEvent table and create any additional fields you need for your animation code. It should also move any of the passed active DisplayEvents that are now colliding due to the newly added event.
Animate | This function moves the DisplayEvent at each update interval by modifying the .PositionX and .PositionY fields. The opacity is controlled by modifying the .Alpha field. Once the animation has completed the function MUST return true so that the objects in use for the animation may be reused and the mod stops calling the function.
AnimateReverse | This function is the same as the Animate callback except it should move the text in a reversed direction. Just as the normal Animate callback, once the animation has completed the function MUST return true.

MikSBT.RegisterAnimationStyle

Return to TOC
Register a new animation style with MSBT.
Custom animation style registration is not permanent. It must be done each load. In order to remove a custom animation style, all that needs to be done is no longer register it on subsequent loads. If any of the scroll areas have a custom animation style selected that is no longer registered, MSBT will recognize that an invalid animation style is specified and use the default animation style accordingly.
Syntax
MikSBT.RegisterAnimationStyle(styleID, initFunc, animateFunc, animateReverseFunc, localizedName)
Parameters

styleID (Required) | A unique string that identifies the animation style. This is also the name that will appear for the animation style in the interface if the localizedName parameter is omitted.
initFunc (Required) | Your InitDisplayEvent callback function.
animateFunc (Required) | Your Animate callback function.
animateReverseFunc (Required) | Your AnimateReverse callback function.
localizedName (Optional) | The name that will appear in the interface for the animation style.

Return Values
None.
Examples
-- Register a new animation style with MSBT.
MikSBT.RegisterAnimationStyle("MyModNameUberAnimation", myInitFunc, myAnimateFunc, myAnimateReverseFunc, "Uber Animation");
Remarks
If you attempt to register a styleID that already exists, the function will quietly fail. An easy way to make sure you have a unique styleID is to preprend your mod's name to it as demonstrated in the example.
MikSBT.RegisterStickyAnimationStyle

Return to TOC
Register a new sticky animation style with MSBT.
Custom animation style registration is not permanent. It must be done each load. In order to remove a custom animation style, all that needs to be done is no longer register it on subsequent loads. If any of the scroll areas have a custom animation style selected that is no longer registered, MSBT will recognize that an invalid animation style is specified and use the default animation style accordingly.
Syntax
MikSBT.RegisterStickyAnimationStyle(styleID, initFunc, animateFunc, animateReverseFunc, localizedName)
Parameters

styleID (Required) | A unique string that identifies the animation style. This is also the name that will appear for the animation style in the interface if the localizedName parameter is omitted.
initFunc (Required) | Your InitDisplayEvent callback function.
animateFunc (Required) | Your Animate callback function.
animateReverseFunc (Required) | Your AnimateReverse callback function.
localizedName (Optional) | The name that will appear in the interface for the animation style.

Return Values
None.
Examples
-- Register a new sticky animation style with MSBT.
MikSBT.RegisterStickyAnimationStyle("MyModNameUberStickyAnimation", myInitFunc, myAnimateFunc, myAnimateReverseFunc, "Uber Sticky Animation");
Remarks
If you attempt to register a styleID that already exists, the function will quietly fail. An easy way to make sure you have a unique styleID is to preprend your mod's name to it as demonstrated in the example.
InitDisplayEvent Callback

Return to TOC
Each time a new DisplayEvent is added to a scroll area, this function is called with it and an array of other DisplayEvents that are currently active for the scroll area.
The purpose of this function is to initialize the starting position, alpha, and any other information you need for the new DisplayEvent, and to move any other DisplayEvents that are now colliding due to the new event.
Syntax
function myInitFunction(newDisplayEvent, activeDisplayEvents, isReversed)
Parameters

newDisplayEvent (Required) | A DisplayEvent table that represents a new event.
activeDisplayEvents (Required) | An array of DisplayEvent tables that represent the other events that are currently active for the scroll area.
isReversed (Required) | A boolean flag that specifies whether or not the animation direction should be reversed.

Return Values
None.
Examples
-- Create an InitDisplayEvent callback function.
local function myInitFunc(newDisplayEvent, activeDisplayEvents, isReversed)
-- Do stuff in here to initialize the newDisplayEvent and move any activeDisplayEvents that are colliding according to your custom animation style.
end
Remarks
Take a look at the init functions in the MSBTAnimations.lua file that comes with the mod for an example of how MSBT initializes the default animation styles.
Animate Callback

Return to TOC
This function is called continously (typically every 15 or so milliseconds) for every active DisplayEvent that is animating using the animation style the function was registered against until the function returns true to indicate the animation is complete.
The DisplayEvent is positioned by setting its .PositionX and .PositionY fields, and it's opacity is controlled by setting its .Alpha field.
The x and y positions should be calculated based upon how much time it has been animating which is available in the .ElapsedTime field and the height of the scroll area available in the .ScrollHeight field. Additionally, the .AnimationSpeed field should be used to scale the speed of the animation.
By basing your calculations on the elapsed time, the animation will remain consistent under diverse performance situations. If you were to base it simply on moving a set number of pixels each update (like MSBT used to) then the actual scroll speed would vary greatly. These fields are further described in the DisplayEvent Table section.
This function MUST return true when the animation is complete.
Syntax
animationComplete = function myAnimateFunction(displayEvent)
Parameters

displayEvent (Required) | A DisplayEvent table that represents the animating event.

Return Values

animationComplete (Required) | Return true if the animation is complete and false if it is not.

Examples
-- Create an Animate callback function.
local function myAnimateFunc(displayEvent)
-- Do stuff in here to animate the displayEvent.
end
Remarks
Take a look at the scroll functions in the MSBTAnimations.lua file that comes with the mod for an example of how MSBT animates the default animation styles.
AnimateReverse Callback

Return to TOC
This function is exactly like the Animate Callback function with the exception that it should animate the event in the reverse direction.
This function MUST return true when the animation is complete.
Syntax
animationComplete = function myAnimateReverseFunction(displayEvent)
Parameters

displayEvent (Required) | A DisplayEvent table that represents the animating event.

Return Values

animationComplete (Required) | Return true if the animation is complete and false if it is not.

Examples
-- Create an AnimateReverse callback function.
local function myAnimateReverseFunc(displayEvent)
-- Do stuff in here to animate the displayEvent in the reverse direction.
end
Remarks
Take a look at the scroll functions in the MSBTAnimations.lua file that comes with the mod for an example of how MSBT animates the default animation styles.
DisplayEvent Table

Return to TOC
This table respresents an animating event.
Fields

.ScrollHeight (Read-Only) | This field contains the scroll height of the scroll area the event is animating in.
.FontSize (Read-Only) | This field contains the size of the font used for the event.
.FontString (Read-Only) | This field contains the <FontString> object that the event is using to display the text. A dynamic pool of font strings is maintained and reused by MSBT.
.AnimationSpeed (Read-Only) | The user selected animation speed. This is a decimal representation of a percentage. For example, 0.5 means that the animation should animate at 50% of the normal speed, 1.0 means it should animate at normal speed, and 2.5 means it should animate at 250% of normal speed.
.PositionX (Read-Write) | The x position of the event to be set once the function returns. MSBT handles all scroll area offsetting. x = 0 will refers to the text's attachment point (left, right, or center). Negative values for x move the text to the left, and positive values moves the text to the right.
.PositionY (Read-Write) | The y position of the event to be set once the function returns. MSBT handles all scroll area offsetting. y = 0 refers to the bottom point of the scroll area and increases upward.
.Alpha (Read-Write) | The opacity of the event to be set once the function returns. The value range is from 0 (invisible) to 1 (fully visible).
.ElapsedTime (Read-Write) | The amount of time the event has been animating.

Remarks
Technically the fields marked as read-only are normal fields just like the rest, however they should be treated as read-only. Altering them can cause unexpected behavior. I didn't want to add the extra overhead it would take to truly make them read-only. There are also other a few other internal fields that should not be altered.