Hello there! We are conducting a survey to better understand the user experience in making a first edit. If you have ever made an edit on Gamepedia, please fill out the survey. Thank you!

LibSharedMedia-3.0

From WowAce Wiki
Jump to: navigation, search

SharedMediaLib is a library for shared handling of media data (fonts, sounds, textures, ...) between addons.

API Documentation

:Register(mediatype, key, data [, langmask])

Registers a new handle of given type.

Args

mediatype 
string - the type of the data, eg. font or statusbar
key 
string - the handle to get the data from the lib
data 
string - the data to associate with the handle; normaly a filename
[langmask] 
bitmask - only for mediatype 'font'; bits should be set if the font supports that locale (see below)

Returns

boolean - false if data for the given mediatype-key pair already existes, true else

:Fetch(mediatype, key [, noDefault])

Fetches the data for the given handle and type.

Args

mediatype 
string - the type of the data, eg. font or statusbar
key 
string - the handle to get the data from the lib
[noDefault] 
boolean - if true nil will be returned instead of the default handle's data

Returns

string or nil - the current overrite handle's data, the requested handle's data, the default handle's data or nil

:IsValid(mediatype [, key])

Checks if the given type (and handle) is valid.

Args

mediatype 
string - the type of the data, eg. font or statusbar
[key] 
string - the handle of the data

Returns

boolean - true if the type (and handle) is valid

:HashTable(mediatype)

Gets a hash table {data -> handle} to eg. iterate over.

Args

mediatype 
string - the type of the data, eg. font or statusbar

Returns

table - hash table for the given type

:List(mediatype)

Gets a sorted list of handles.

Args

mediatype 
string - the type of the data, eg. font or statusbar

Returns

table - list of handles for the given type

:GetGlobal(mediatype)

Returns the prior set overrite handle.

Args

mediatype 
string - the type of the data, eg. font or statusbar

Returns

string or nil - the current overrite handle for the given type

:SetGlobal(mediatype [, key])

Sets or clears a handle that will be returned on fetch instead of the requested handle

Args

mediatype 
string - the type of the data, eg. font or statusbar
[key] 
string - the handle of the data

Returns

none

:GetDefault(mediatype)

Returns the default return value for nonexistant handles.

Args

mediatype 
string - the type of the data, eg. font or statusbar

Returns

string or nil - default return value for nonexistant handles for the given type

:SetDefault(type, handle)

Sets a default return value for nonexistant handles. Won't replace an already set default.

Args

type 
string - the type of the data, eg. font or statusbar
handle 
string - the handle of the data

Returns

none

Callback API

:RegisterCallback()

myAddon:RegisterCallback("eventName"[, method[, arg]])
library.RegisterCallback(myTable, "eventName"[, method[, arg]])
library.RegisterCallback("myAddonId", "eventName"[, method[, arg]])
"eventName"
(string) - the name of the event you want to listen to
method
(string or function) - which method to call. If string, self["method"] will be called. If left out (nil), self["eventName"] will be called.
arg
(optional) - If present (even nil), this value will be passed to the receiving function.


Registrations are always associated with the supplied self. This means that you'll want to embed the library, or do the call like .RegisterCallback(myTable, ...). Note the use of " . " (period) rather than " : " (colon).

If you do not have a sane self table to associate your registrations with, you can substitute it for a string. Note the use of "." rather than ":".

library.RegisterCallback("myAddonId", "eventName", ...)

This string variant of a self will not be passed to the receiving function.

Callback arguments

If the method is a plain function, it will be called as:

method("eventName", (arguments to the event))
or, with an arg specified when registering:
method(arg, "eventName", (arguments to the event))


If the method is a string (method name), it will be called as:

self["method"](self, "eventName", (arguments to the event))
or, with an arg specified when registering:
self["method"](self, arg, "eventName", (arguments to the event))


:UnregisterCallback()

myAddon:UnregisterCallback("eventName")
library.UnregisterCallback(myTable, "eventName")
library.UnregisterCallback("myAddonId", "eventName")
"eventName"
the name of the event that you no longer wish to receive.

Note that the supplied self must match the self supplied to :RegisterCallback(), or nothing will be unregistered.


:UnregisterAllCallbacks()

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

UnregisterAllCallbacks will unregister all events associated with the given self, as well as with additional arguments given.


Callbacks fired

LibSharedMedia_Registered

fires when a new handle was successfully registered

Args

name 
"LibSharedMedia_Registered"
mediatype 
the type of the new handle
key 
the name of the handle

LibSharedMedia_SetGlobal

fires when a overrite handle was set/cleared

Args

name 
LibSharedMedia_SetGlobal
mediatype 
the type of the new handle
key 
the name of the handle; nil if the overrite handle was cleared

MediaType constants

The library has some build-in constants for media types that can be used in an addon. These are only some official suggestions on types. Feel free to suggest more.

constant                      value                    used for
<lib>.MediaType.BACKGROUND    background               background textures
<lib>.MediaType.BORDER        border                   border textures
<lib>.MediaType.FONT          font                     fonts
<lib>.MediaType.STATUSBAR     statusbar                statusbar textures
<lib>.MediaType.SOUND         sound                    sound files

Language Mask constants

These constants should be used to indicate if a font supports the charset of a specific locale. If none is passed to :Register(...) Western is assumed by default. To use multiple of them simply add them together.

<lib>.LOCALE_BIT_koKR
<lib>.LOCALE_BIT_zhCN
<lib>.LOCALE_BIT_zhTW
<lib>.LOCALE_BIT_western

Predefined data

The following data is predefined inside the library. There is no need to define it again yourself. (default handle)

MediaType BACKGROUND

Blizzard Low Health               Interface\FullScreenTextures\LowHealth
Blizzard Out of Control           Interface\FullScreenTextures\OutOfControl
Blizzard Tabard Background        Interface\TabardFrame\TabardFrameBackground
Blizzard Tooltip                  Interface\Tooltips\UI-Tooltip-Background
Solid                             Interface\Buttons\WHITE8X8

MediaType BORDER

None                              Interface\None
Blizzard Dialog                   Interface\DialogFrame\UI-DialogBox-Border
Blizzard Tooltip                  Interface\Tooltips\UI-Tooltip-Border

MediaType FONT

Arial Narrow                      Fonts\\ARIALN.TTF
Friz Quadrata TT                  Fonts\\FRIZQT__.TTF
Morpheus                          Fonts\\MORPHEUS.TTF
Skurri                            Fonts\\SKURRI.TTF

MediaType STATUSBAR

Blizzard                          Interface\\TargetingFrame\\UI-StatusBar

MediaType SOUND

None                              Interface\Quiet.mp3

Naming Conventions

General

  • Don't create subnamespaces by prefixing names.
  • Try to give descriptive handle names. Example: "Alert" wouldn't be a good name for a sound even if you intend it for alerting the user.

MediaType FONT

Fonts should be added with the exact name defined in the ttf as handle.

AceGUI-3.0 widgets

AceGUI-3.0-SharedMediaWidgets provides AceGUI-3.0 widgets for the 5 basic types in LibSharedMedia-3.0