This file contains a reference for all of MSBT's publicly accessible functions and structures.
Table of Contents:
MikSBT.IsModDisabled
Return to TOC
Returns a flag indicating if the mod is disabled.
Syntax
isDisabled = MikSBT.IsModDisabled()
Parameters
None.
Return Values

isDisabled | A flag that indicates if the mod is disabled. The return value will be one of the following: true - The mod is disabled. nil - The mod is enabled.

Example
-- Do something special if MSBT is disabled.
if MikSBT.IsModDisabled() then
-- Do something special here.
end
Remarks
None.
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.IterateFonts function, or first use the MikSBT.RegisterFont function to use your own custom font.
Additionally, you may call the MikSBT.IterateScrollAreas function to get an iterator for the 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, texturePath])
Parameters

message (Required) | The string to display.
scrollArea (Optional) | Specifies the scroll area key or scroll area name in which to display the message. You can get an iterator for the available scroll areas with the MikSBT.IterateScrollAreas function, or use one of the following predefined values: MikSBT.DISPLAYTYPE_INCOMING MikSBT.DISPLAYTYPE_OUTGOING MikSBT.DISPLAYTYPE_NOTIFICATION MikSBT.DISPLAYTYPE_STATIC 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 4-38. 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.IterateFonts 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.
texturePath (Optional) | The path to a texture file to display. If the parameter is omitted or an invalid path is passed, no texture will be displayed.

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, no outline, and the icon for fear.
MikSBT.DisplayMessage("Enemy begins to flee in fear", nil, false, 0, 255, 0, nil, "Yellowjacket", 1, "Interface\\Icons\\Spell_Shadow_Possession");
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.IterateFonts
Return to TOC
Returns an iterator function for the table containing the registered fonts.
Syntax
for fontName, fontPath in MikSBT.IterateFonts() do
Parameters
None.
Return Values

iterator | An iterator function for the table containing the registered fonts. The format of the table is as follows: ["FontName1"] = "Font Path 1" ["FontName2"] = "Font Path 2"

Examples
-- Print the font names registered with MSBT.
for fontName, fontPath in MikSBT.IterateFonts() do
DEFAULT_CHAT_FRAME:AddMessage(fontName);
end
Remarks
This function has superseded the MikSBT.GetRegisteredFontList function. The old function created a new table and returned it every time it was called which was wasteful.
MikSBT.IterateScrollAreas
Return to TOC
Returns an iterator function for the table containing the available scroll areas.
Syntax
for scrollAreaKey, scrollAreaName in MikSBT.IterateScrollAreas() do
Parameters
None.
Return Values

iterator | An iterator function for the table containing the available scroll areas. The format of the table is as follows: ["FirstKey"] = "First Scroll Area Name" ["SecondKey"] = "Second Scroll Area Name"

Examples
-- Print MSBT's available scroll area names.
for scrollAreaKey, scrollAreaName in MikSBT.IterateScrollAreas() do
DEFAULT_CHAT_FRAME:AddMessage(scrollAreaName);
end
Remarks
This function has superseded the MikSBT.GetScrollAreaList function. The old function created a new table and returned it every time it was called which was wasteful.
Sounds Overview
Return to TOC
MSBT allows you to register sounds which the user can assign to be played when events and triggers occur.
The MikSBT.RegisterSound function is used to register the sounds, and the registered sounds may be obtained by using the MikSBT.IterateSounds function.
MikSBT.RegisterSound
Return to TOC
Registers a sound with MSBT.
Sound registration is not permanent. It must be done each load. In this manner if the user were to remove a mod that registers custom sounds, the sounds would simply no longer be available.
Syntax
MikSBT.RegisterSound(soundName, soundPath)
Parameters

soundName (Required) | The name to use for the sound. This name will be displayed in the sound selection dialogs.
soundPath (Required) | The filesystem path to where the sound resides.

Return Values
None.
Example
-- Registers a sound named "MyUberSound" with MSBT.
MikSBT.RegisterSound("MyUberSound", "Interface\\AddOns\\MyModName\\Sounds\\MyUberSound.mp3");
Remarks
If you attempt to register a sound name that already exists, the function will quietly fail.
MikSBT.IterateSounds
Return to TOC
Returns an iterator function for the table containing the registered sounds.
Syntax
for soundName, soundPath in MikSBT.IterateSounds() do
Parameters
None.
Return Values

iterator | An iterator function for the table containing the registered sounds. The format of the table is as follows: ["SoundName1"] = "Sound Path 1" ["SoundName2"] = "Sound Path 2"

Examples
-- Print the sound names registered with MSBT.
for soundName, soundPath in MikSBT.IterateSounds() do
DEFAULT_CHAT_FRAME:AddMessage(soundName);
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 allowing an initialization callback handler, directions, and behaviors for an animation style to be registered with the MikSBT.RegisterAnimationStyle and MikSBT.RegisterStickyAnimationStyle functions. The supplied initialization handler then sets the appropriate animation handler for each new DisplayEvent it receives.
The callback handlers receive recycled DisplayEvent tables that contain information about an animating event such as its x and y position, its 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 two callback handlers:

InitDisplayEvent | This function receives a new DisplayEvent table, an array of DisplayEvents that are currently active for the scroll area using the same animation style, and the currently selected direction and behavior for the scroll area. The most important thing for this function to do is set the .animationHandler field for the new DisplayEvent to an appropriate Animation callback handler. The handler MUST be set. Other things to be done are to establish the initial settings for the new DisplayEvent table, create any additional fields you need for your animation code, and move the active DisplayEvents that are now colliding due to the newly added event if your animation style should avoid overlaps.
Animation | 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.

MikSBT.RegisterAnimationStyle
Return to TOC
Registers 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, initHandler, availableDirections [, availableBehaviors, localizationTable])
Parameters

styleID (Required) | A unique string that identifies the animation style.
initHandler (Required) | Your InitDisplayEvent callback handler.
availableDirections (Required) | A string that contains a semicolon separated list of the available directions for the animation style.
availableBehaviors (Optional) | A string that contains a semicolon separated list of the available behaviors for the animation style.
localizationTable (Optional) | A table that contains translations. The strings provided in the styleID, availableDirections, and availableBehaviors parameters will by used as the key into this table to find an appropriate translation.

Return Values
None.
Examples
-- Register a new animation style with MSBT.
MikSBT.RegisterAnimationStyle("MyModNameUberAnimation", myInitHandler, "Up;Down", "Implode;Explode", myLocalizationTable);
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
Registers 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, initHandler, availableDirections [, availableBehaviors, localizationTable])
Parameters

styleID (Required) | A unique string that identifies the animation style.
initHandler (Required) | Your InitDisplayEvent callback handler.
availableDirections (Required) | A string that contains a semicolon separated list of the available directions for the animation style.
availableBehaviors (Optional) | A string that contains a semicolon separated list of the available behaviors for the animation style.
localizationTable (Optional) | A table that contains translations. The strings provided in the styleID, availableDirections, and availableBehaviors parameters will by used as the key into this table to find an appropriate translation.

Return Values
None.
Examples
-- Register a new sticky animation style with MSBT.
MikSBT.RegisterStickyAnimationStyle("MyModNameUberStickyAnimation", myInitHandler, "Up;Down", "Jiggle;Normal", myLocalizationTable);
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, an array of other DisplayEvents that are currently active for the scroll area, and the currently selected direction and behavior for the scroll area.
The most important thing for this function to do is set the .animationHandler field for the new DisplayEvent to an appropriate Animation callback handler.
The other 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.
This function MUST set the .animationHandler field of the newDisplayEvent parameter to a valid Animation callback handler.
Syntax
function myInitHandler(newDisplayEvent, activeDisplayEvents [, direction, behavior])
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.
direction (Optional) | A string that is the currently selected direction for the scroll area. The default animation direction should be used when this parameter is invalid.
behavior (Optional) | A string that is the currently selected behavior for the scroll area. The default animation behavior should be used when this parameter is invalid.

Return Values
None.
Examples
-- Create an InitDisplayEvent callback handler.
local function myInitHandler(newDisplayEvent, activeDisplayEvents, direction, behavior)
-- 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 MSBTAnimationStyles.lua file that comes with the mod for an example of how MSBT initializes the default animation styles.
Animation Callback
Return to TOC
This function is called continously (typically every 15 or so milliseconds) for every active DisplayEvent that is animating until the function returns true to indicate the animation is complete.
The DisplayEvent is positioned by setting its .positionX and .positionY fields, and its 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 and width of the scroll area available in the .scrollHeight and .scrollWidth fields. 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 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 myAnimationHandler(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 Animation callback handler.
local function myAnimationHandler(displayEvent)
-- Do stuff in here to animate the displayEvent.
end
Remarks
Take a look at the scroll functions in the MSBTAnimationStyles.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 height of the scroll area the event is animating in.
.scrollWidth (Read-Only) | This field contains the width 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.
.anchorPoint (Read-Only) | This field contains anchor point for <FontString> that the event is using to display the text. It will be "BOTTOMLEFT", "BOTTOM", or "BOTTOMRIGHT", corresponding to left, center, and right text alignment.
.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 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 a few other internal fields that should not be altered.