This file contains a reference for all of MSBT's publicly accessible functions and structures.
Mod State:
Displaying Messages:
Sounds:
Custom Animation Styles:
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
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.
Registers a font with MSBT and Shared Media.
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.
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
- 4 - Monochrome
- 5 - Monochrome + Thin
- 6 - Monochrome + 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, "MSBT 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.
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
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.
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.
Registers a sound with MSBT and Shared Media.
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 an mp3 sound named "MyUberSound1" with MSBT.
MikSBT.RegisterSound("MyUberSound1", "Interface\\AddOns\\MyModName\\Sounds\\MyUberSound1.mp3");
-- Registers an ogg sound named "MyUberSound2" with MSBT.
MikSBT.RegisterSound("MyUberSound2", "Interface\\AddOns\\MyModName\\Sounds\\MyUberSound2.ogg");
Remarks
If you attempt to register a sound name that already exists, the function will quietly fail.
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
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, and the animation completion percentage.
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 can also be controlled by modifying the .alpha field.
|
MikSBT.RegisterAnimationStyle
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
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
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 and any additional 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.
Return to TOC
This function is called continously (typically every 15 or so milliseconds) for every active
DisplayEvent that is animating
for the duration of the animation time.
The
DisplayEvent is positioned by setting its
.positionX and
.positionY fields, and its opacity can be controlled by setting its
.alpha field.
The x and y positions should be calculated based upon the completed animation percentage and the height and width of the scroll area available
in the
.scrollHeight and
.scrollWidth fields. By basing your calculations on the completed animation percentage, 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.
Syntax
function myAnimationHandler(displayEvent, percentDone)
Parameters
| displayEvent (Required) |
A DisplayEvent table that represents the animating event.
|
| percentDone (Required) |
A decimal representation of a percentage that indicates how far along the animation has progressed.
|
Return Values
None.
Examples
-- Create an Animation callback handler.
local function myAnimationHandler(displayEvent, percentDone)
-- 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.
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.
|
| .frame (Read-Only) |
This field contains the <Frame> object the event is using.
A dynamic pool of frames is maintained and reused by MSBT.
|
| .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 <Frame> object the event is using.
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.
MSBT automatically scales the scroll time based upon the animation speed, but depending on your animation
you may need to do some manual scaling of different phases.
|
| .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 frame's attachment point (left, right, or center).
Negative values for x move the frame to the left, and positive values moves the frame 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 frame to be set once the function returns.
The value range is from 0 (invisible) to 1 (fully visible).
MSBT automatically fades the animating frame out near the end of the animation. This field can be used for altering the opacity
during the remainder of the animation.
|
| .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.