This library is an abstraction for the different types of player set pings on the map. Not to be confused with LibMapPins which handles creation of custom map markers.
The main features include:
- a unified way to manipulate pings and to react to the ensuing map ping events,
- suppression of pings so that their information can only be accessed via the library,
- silent placement of pings,
- watch dog that fires the callbacks if an event does not get fired by the API due to a bug.
Dependencies
Make sure to install the following required libraries in order to use LibMapPing.
API Reference
MapPingState
MapPingState is an enumeration of the possible states of a map ping.
lib.MAP_PING_NOT_SET: There is no ping.
lib.MAP_PING_NOT_SET_PENDING: The ping has been removed, but EVENT_MAP_PING has not been processed.
lib.MAP_PING_SET_PENDING: A ping was added, but EVENT_MAP_PING has not been processed.
lib.MAP_PING_SET: There is a ping.
SetMapPing
Wrapper for PingMap and SetPlayerWaypointByWorldLocation.
pingType is one of the three possible MapDisplayPinType for map pings (MAP_PIN_TYPE_PLAYER_WAYPOINT, MAP_PIN_TYPE_PING or MAP_PIN_TYPE_RALLY_POINT) or false.
when pingType is set to false, the function calls SetPlayerWaypointByWorldLocation and the arguments will be the worldX, worldY and worldZ and the return a boolean success
for all other pingTypes nothing is returned and the arguments are as follows:
mapType is usually MAP_TYPE_LOCATION_CENTERED.
x and y are the normalized coordinates on the current map.
Code:
lib:SetMapPing(MapDisplayPinType pingType, MapDisplayType|number mapTypeOrWorldX, number xOrWorldY, number yOrWorldZ)
RemoveMapPing
Wrapper for the different ping removal functions.
For waypoints and rally points it calls their respective removal function.
For group pings it just sets the position to 0, 0 as there is no function to clear them.
Code:
lib:RemoveMapPing(MapDisplayPinType pingType)
GetMapPing
Wrapper for the different get ping functions. Returns coordinates regardless of their suppression state.
The game API functions return 0, 0 when the ping type is suppressed.
pingType is the same as for SetMapPing.
pingTag is optionally used if another group member's MAP_PIN_TYPE_PING should be returned (possible values: group1 .. group24).
Code:
number x, number y = lib:GetMapPing(MapDisplayPinType pingType[, string pingTag])
GetMapPingState
Returns the MapPingState for the pingType and pingTag.
Code:
MapPingState state = lib:GetMapPingState(MapDisplayPinType pingType[, string pingTag])
HasMapPing
Returns true if ping state is lib.MAP_PING_SET_PENDING or lib.MAP_PING_SET.
Code:
boolean hasPing = lib:HasMapPing(MapDisplayPinType pingType[, string pingTag])
RefreshMapPin
Refreshes the pin icon for the pingType on the worldmap.
Returns true if the pin has been refreshed.
Code:
boolean wasRefreshed = lib:RefreshMapPin(MapDisplayPinType pingType[, string pingTag])
IsPositionOnMap
Returns true if the normalized position is within 0 and 1.
Code:
boolean isInside = lib:IsPositionOnMap(number x, number y)
MutePing
Mutes the map ping of the specified type, so it does not make a sound when it is set.
Do not forget to call UnmutePing later, otherwise the sound will be permanently muted!
Code:
lib:MutePing(MapDisplayPinType pingType[, string pingTag])
UnmutePing
Unmutes the map ping of the specified type.
Do not call this more often than you called MutePing, or you might interfere with other addons.
The sounds are played between the BeforePing* and AfterPing* callbacks are fired.
Code:
lib:UnmutePing(MapDisplayPinType pingType[, string pingTag])
IsPingMuted
Returns true if the map ping has been muted.
Code:
boolean isMuted = lib:IsPingMuted(MapDisplayPinType pingType[, string pingTag])
SuppressPing
Suppresses the map ping of the specified type, so that it neither makes a sound nor shows up on the map.
This also makes the API functions return 0, 0 for that ping.
In order to access the actual coordinates lib:GetMapPing has to be used.
Do not forget to call UnsuppressPing later, otherwise map pings won't work anymore for the user and other addons!
Code:
lib:SuppressPing(MapDisplayPinType pingType[, string pingTag])
UnsuppressPing
Unsuppresses the map ping so it shows up again.
Do not call this more often than you called SuppressPing, or you might interfere with other addons.
Code:
lib:UnsuppressPing(MapDisplayPinType pingType[, string pingTag])
IsPingSuppressed
Returns true if the map ping has been suppressed.
Code:
boolean isSuppressed = lib:IsPingSuppressed(MapDisplayPinType pingType[, string pingTag])
RegisterCallback
Register to callbacks from the library.
Valid events are BeforePingAdded, AfterPingAdded, BeforePingRemoved and AfterPingRemoved.
These are fired at certain points during handling EVENT_MAP_PING.
Code:
lib:RegisterCallback(string eventName, function callback)
UnregisterCallback
Unregister from callbacks. See lib:RegisterCallback.
Code:
lib:UnregisterCallback(string eventName, function callback)
BeforePingAdded
This callback is fired in EVENT_MAP_PING before the map ping is processed.
Code:
BeforePingAdded(MapDisplayPinType pingType, string pingTag, number x, number y, boolean isPingOwner)
AfterPingAdded
This callback is fired in EVENT_MAP_PING after the map ping has been processed.
Code:
AfterPingAdded(MapDisplayPinType pingType, string pingTag, number x, number y, boolean isPingOwner)
BeforePingRemoved
This callback is fired in EVENT_MAP_PING before the map ping is processed.
Code:
BeforePingRemoved(MapDisplayPinType pingType, string pingTag, number x, number y, boolean isPingOwner)
AfterPingRemoved
This callback is fired in EVENT_MAP_PING after the map ping has been processed.
Code:
AfterPingRemoved(MapDisplayPinType pingType, string pingTag, number x, number y, boolean isPingOwner)