WowAce

LibToast-1.0

LibToast can create numerous "toast" frames, complete with customization. LibToast can be embedded into your AddOn, either explicitly by calling LibToast:Embed(MyAddOn) or by specifying it as an embedded library in your AceAddon. All functions will be available on your AddOn object and can be accessed directly, without having to explicitly call LibToast itself.

Note

Method names are different depending on whether you embed LibToast in your AddOn object or not; embedded, they all end with "Toast". For example, an AddOn which embeds LibToast has a :RegisterToast() method, whereas a direct LibToast declaration has a :Register() method.

AddOn:RegisterToast(template_name, constructor[, is_unique])

LibToast:Register(template_name, constructor[, is_unique])

Registers a template for the given toast. Templates are stored by the library for the duration of the session to be spawned at any time.

Arguments

template_name

string - Unique name for the toast template.

constructor

function - All toast API is invoked here. Occurs whenever the template is spawned.

is_unique

boolean - if true, no other instances of this toast template may be spawned while one is in existence.

Example

local function CloseToast()
end

-- Creates a template called "ExampleToast" which sets the text to whatever
-- is passed to "...", creates a button with the text "OK", and does not go
-- away until the button is pressed.
AddOn:RegisterToast("ExampleToast", function(toast, ...)
    toast:SetTitle("Example Toast")
    toast:SetText(...)
    toast:SetIconTexture([[Interface\FriendsFrame\Battlenet-WoWicon]])
    toast:MakePersistent()
    toast:SetPrimaryCallback(_G.OKAY, CloseToast)
end)

AddOn:SpawnToast(template_name[, ...])

LibToast:Spawn(template_name[, ...])

Arguments

template_name

string - Pre-existing unique name for the toast template to be spawned.

...

vararg - extra data which is passed to the toast's constructor function.

Example

-- Spawn an instance of the "ExampleToast" toast and passes
-- "Hello, world!" to its constructor.
LibToast:Spawn("ExampleToast", "Hello, world!")

AddOn:DefineSinkToast([display_name][, texture_path])

LibToast:DefineSink([display_name][, texture_path])

Defines the title and icon for toasts produced by your AddOn when embedding LibSink-2.0 and has "Toast" set as its :Pour() target. This also prompts LibToast to create a Sink using LibSink-2.0 if it has not already done so.

Arguments

display_name

string - The title of the toast.

texture_path

string - path where the desired icon texture file resides.

Toasts

Once the constructor has run, a toast is limited to manipulation from the following methods.

:SetUrgencyLevel(urgency)

Arguments

urgency

string - "very_low", "moderate", "normal", "high", "emergency" - Underscored may be omitted, case does not matter.

:UrgencyLevel()

Return value

urgency

string - The current urgency level of the toast object.

:SetTitle(title)

Arguments

title

string - the title of the toast.

:SetFormattedTitle(title_format, ...)

Arguments

title_format

string - the format for the title of the toast.

...

varags - variable number of arguments for the format.

:SetText(text)

Arguments

text

string - the text body of the toast.

:SetFormattedText(text_format, ...)

Arguments

text_format

string - the format for the text body of the toast.

...

varags - variable number of arguments for the format.

:SetIconAtlas(atlas)

Arguments

atlas

string - icon atlas value

:SetIconTexture(texture_path)

Arguments

texture_path

string - path where the desired icon texture file resides.

:SetIconTexCoord(minX, maxX, minY, maxY)

Arguments

minX

number - Left edge of the scaled/cropped image, as a fraction of the image's width from the left.

maxX

number - Right edge of the scaled/cropped image, as a fraction of the image's width from the left.

minY

number - Top edge of the scaled/cropped image, as a fraction of the image's height from the top.

maxY

number - Bottom (or maxY) edge of the scaled/cropped image, as a fraction of the image's height from the top.

:SetIconTexCoord(ULx, ULy, LLx, LLy, URx, URy, LRx, LRy)

ULx

number - Upper left corner X position, as a fraction of the image's width from the left.

ULy

number - Upper left corner Y position, as a fraction of the image's height from the top.

LLx

number - Lower left corner X position, as a fraction of the image's width from the left.

LLy

number - Lower left corner Y position, as a fraction of the image's height from the top.

URx

number - Upper right corner X position, as a fraction of the image's width from the left.

URy

number - Upper right corner Y position, as a fraction of the image's height from the top.

LRx

number - Lower right corner X position, as a fraction of the image's width from the left.

LRy

number - Lower right corner Y position, as a fraction of the image's height from the top.

:SetPrimaryCallback(label, handler)

Arguments

label

string - Label for the button that will be created for this callback.

handler

function - Function to be executed when the button is pressed. Accepts no arguments.

:SetSecondaryCallback(label, handler)

Arguments

label

string - Label for the button that will be created for this callback.

handler

function - Function to be executed when the button is pressed. Accepts no arguments.

:SetTertiaryCallback(label, handler)

Arguments

label

string - Label for the button that will be created for this callback.

handler

function - Function to be executed when the button is pressed. Accepts no arguments.

:SetPayload(...)

Arguments

...

vararg - Data which all callback buttons may use.

:Payload()

Return value

payload

variable - Data which was set as the toast object's payload.

:MakePersistent()

: The toast will not automatically fade out after being displayed. The user must click the close button in the corner or invoke a handler button.

:SetSoundFile(file_path)

Arguments

file_path

string - path where the desired sound file resides.