LibMapPins-1.0 is a library for custom map pins.
Two important Notes to mod authors
[1] No LibStub support!
Do not use LibStub to reference this library.
Code:
local LMP = LibStub("LibMapPins-1.0")
Change code to the following
Code:
local LMP = LibMapPins
[2] AUI support was removed in 2017 for Revision 17 by Sensi. Please remove all LibMapPin calls to AUI functions.
Previous LibMapPins code as of r17
Code:
function lib.AUI.DoesMinimapExist() end
function lib.AUI.IsMinimapEnabled() end
function lib.AUI.IsMinimapLoaded() end
function lib.AUI.AddCustomPinType() end
function lib.AUI.UpdateQueuedCustomPinTypes() end
function lib.AUI.SetQueuedCustomPinType() end
Typical example code from mods
Code:
if LMP.AUI.IsMinimapEnabled() then
zo_callLater(CreatePins, 50)
else
CreatePins()
end
Change code to the following
How to install:
You may either embed the library in your addon and load the files from your
addon manifest, or have the library installed like any other normal addon.
If you are depending on the library being installed separately and are not embedding it, then you must include this line in your
addon manifest:
Code:
## DependsOn: LibMapPins-1.0
How to use:
Add a reference to the library using:
Alternativly you may add a reference to the library from LibStub: (Not Recomended)
Lua Code:
local LMP = LibStub("LibMapPins-1.0")
Arguments used by most of the functions:
Code:
pinType: either pinTypeId or pinTypeString, you can use both
pinTypeString: unique string name of your choice (it will be used as a name
for global variable)
pinTypeId: unique number code for your pin type, return value from lib:AddPinType
( local pinTypeId = _G[pinTypeString] )
pinLayoutData: table which can contain the following keys:
level = number > 2, pins with higher level are drawn on the top of pins
with lower level.
Examples: Points of interest 50, quests 110, group members 130,
wayshrine 140, player 160.
texture = string or function(pin). Function can return just one texture
or overlay, pulse and glow textures.
size = texture will be resized to size*size, if not specified size is 20.
tint = ZO_ColorDef object or function(pin) which returns this object.
If defined, color of background texture is set to this color.
grayscale = true/false, could be function(pin). If defined and not false,
background texure will be converted to grayscale (http://en.wikipedia.org/wiki/Colorfulness)
insetX = size of transparent texture border, used to handle mouse clicks
insetY = dtto
minSize = if not specified, default value is 18
minAreaSize = used for area pins
showsPinAndArea = true/false
isAnimated = true/false
Add custom pin type (group of pins):
Lua Code:
lib:AddPinType(pinTypeString, pinTypeAddCallback, pinTypeOnResizeCallback, pinLayoutData, pinTooltipCreator)
-- returns: pinTypeId
--
-- pinTypeString: string
-- pinTypeAddCallback: function(pinManager), will be called every time when map
-- is changed. It should create pins on the current map using the
-- lib:CreatePin(...) function.
-- pinTypeOnResizeCallback: (nilable) function(pinManager, mapWidth, mapHeight),
-- is called when map is resized (zoomed).
-- pinLayoutData: (nilable) table, details above
-- pinTooltipCreator: (nilable) etiher string to display or table with the
-- following keys:
-- creator = function(pin) that creates tooltip - or I should say function
-- that will be called when mouse is over the pin, it does not
-- need to create tooltip.
-- tooltip = (nilable) tooltip mode, number between 1 and 4. It is
-- defined in WorldMap.lua as follows:
-- local TOOLTIP_MODE = {
-- INFORMATION = 1,
-- KEEP = 2,
-- MAP_LOCATION = 3,
-- IMPERIAL_CITY = 4,
-- }
-- hasTooltip = (optional), function(pin) which returns true/false to
-- enable/disable tooltip.
-- gamepadCategory = (nilable) string
-- gamepadCategoryId = (nilable) number, right now it uses one of:
-- local GAMEPAD_PIN_ORDERS = {
-- DESTINATIONS = 10,
-- AVA_KEEP = 20,
-- AVA_OUTPOST = 21,
-- AVA_RESOURCE = 22,
-- AVA_GATE = 23,
-- AVA_ARTIFACT = 24,
-- AVA_IMPERIAL_CITY = 25,
-- AVA_FORWARD_CAMP = 26,
-- CRAFTING = 30,
-- QUESTS = 40,
-- PLAYERS = 50,
-- }
-- gamepadCategoryIcon = (nilable) texture path
-- gamepadEntryName = (nilable) string
-- gamepadSpacing = (nilable) boolean
Create single pin on the current map, primary use is from pinTypeAddCallback:
Lua Code:
lib:CreatePin(pinType, pinTag, locX, locY, areaRadius)
-- pinType: pinTypeId or pinTypeString
-- pinTag: can be anything, but I recommend using table or string with
-- additional pin details. You can use it later in code.
-- ( local pinTypeId, pinTag = pin:GetPinTypeAndTag() )
-- Argument pinTag is used as an id for functions
-- lib:RemoveCustomPin(...) and lib:FindCustomPin(...).
-- locX, locY: normalized position on the current map
-- areaRadius: (nilable)
Add filter checkboxes to the world map:
Lua Code:
lib:AddPinFilter(pinType, pinCheckboxText, separate, savedVars, savedVarsPveKey, savedVarsPvpKey, savedVarsImperialPvpKey)
-- Returns: pveCheckbox, pvpCheckbox
-- (newly created checkbox controls for PvE and PvP context of the world map)
--
-- pinType: pinTypeId or pinTypeString
-- pinCheckboxText: (nilable), description displayed next to the checkbox, if nil
-- pinCheckboxText = pinTypeString
-- separate: (nilable), if false or nil, checkboxes for PvE and PvP context
-- will be linked together. If savedVars argument is nil, separate
-- is ignored and checkboxes will be linked together.
-- savedVars: (nilable), table where you store filter settings
-- savedVarsPveKey: (nilable), key in the savedVars table where you store filter
-- state for PvE context. If savedVars table exists but this key
-- is nil, state will be stored in savedVars[pinTypeString].
-- savedVarsPvpKey: (nilable), key in the savedVars table where you store filter
-- state for PvP context, used only if separate is true. If separate
-- is true, savedVars exists but this argument is nil, state will
-- be stored in savedVars[pinTypeString .. "_pvp"].
-- savedVarsImperialPvpKey: (nilable), key in the savedVars table where you store
-- filter state for Imperial City PvP context, used only if separate
-- is true. If separate is true, savedVars exists but this argument
-- is nil, state will be stored in savedVars[pinTypeString .. "_imperialPvP"].
Add click handlers for pins, if handler is nil, any existing handler will be removed.
Lua Code:
lib:SetClickHandlers(pinType, LMB_handler, RMB_handler)
-- pinType: pinTypeId or pinTypeString
-- LMB_handler: hadler for left mouse button
-- RMB_handler: handler for right mouse button
--
-- handler = {
-- {
-- name = string or function(pin) end --required
-- callback = function(pin) end --required
-- show = function(pin) end, (optional) default is true. Callback function
-- is called only when show returns true.
-- duplicates = function(pin1, pin2) end, (optional) default is true.
-- What happens when mouse lick hits more than one pin. If true,
-- pins are considered to be duplicates and just one callback
-- function is called.
-- gamepadName = the same as name, but for gamepad
-- },
-- }
-- One handler can have defined more actions, with different conditions in show
-- function. First action with true result from show function will be used.
-- handler = {
-- {name = "name1", callback = callback1, show = show1},
-- {name = "name2", callback = callback2, show = show2},
-- ...
-- }
Refresh pins. If pinType is nil, refreshes all custom pins:
Lua Code:
lib:RefreshPins(pinType)
-- pinType: pinTypeId or pinTypeString
Check if pins are enabled:
Lua Code:
lib:IsEnabled(pinType)
-- returns: true/false
--
-- pinType: pinTypeId or pinTypeString
Set enabled/disabled state of the given pinType and if exists, update filter checkbox on the world map:
Lua Code:
lib:SetEnabled(pinType, state)
-- pinType: pinTypeId or pinTypeString
-- state: true/false, as false is considered nil, false or 0. All other
-- values are true.
Enable pins of the given pinType:
Lua Code:
lib:Enable(pinType)
-- pinType: pinTypeId or pinTypeString
Disable pins of the given pinType:
Lua Code:
lib:Disable(pinType)
-- pinType: pinTypeId or pinTypeString
Find custom pin:
Lua Code:
lib:FindCustomPin(pinType, pinTag)
-- returns pin
--
-- pinType: pinTypeId or pinTypeString
-- pinTag: id assigned to the pin by function lib:CreatePin(...)
Remove custom pin. If pinTag is nil, all pins of the given pinType are removed.
Lua Code:
lib:RemoveCustomPin(pinType, pinTag)
-- pinType: pinTypeId or pinTypeString
-- pinTag: id assigned to the pin by function lib:CreatePin(...)
Change a single key in the pinLayoutData table:
Lua Code:
lib:SetLayoutKey(pinType, key, data)
-- pinType: pinTypeId or pinTypeString
-- key: key name in pinLayoutData table
-- data: data to be stored in pinLayoutData[key]
Replace whole pinLayoutData table:
Lua Code:
lib:SetLayoutData(pinType, pinLayoutData)
-- pinType: pinTypeId or pinTypeString
-- pinLayoutData: table
Get a single key from the pinLayoutData table:
Lua Code:
lib:GetLayoutKey(pinType, key)
-- returns: pinLayoutData[key]
--
-- pinType: pinTypeId or pinTypeString
-- key: key name in pinLayoutData table
Get a reference to the pinLayoutData table:
Lua Code:
lib:GetLayoutData(pinType)
-- returns: pinLayoutData
--
-- pinType: pinTypeId or pinTypeString
Set new add callback:
Lua Code:
lib:SetAddCallback(pinType, pinTypeAddCallback)
-- pinType: pinTypeId or pinTypeString
-- pinTypeAddCallback: function(pinManager)
Set new OnResize callback:
Lua Code:
lib:SetResizeCallback(pinType, pinTypeOnResizeCallback)
-- pinType: pinTypeId or pinTypeString
-- pinTypeOnResizeCallback: function(pinManager, mapWidth, mapHeight)
Get zone and subzone derived from map texture:
Lua Code:
lib:GetZoneAndSubzone(alternative, bStripUIMap, bKeepMapNum)
-- You can select from 3 formats:
-- 1: "zone", "subzone" (that's what I use in my addons)
-- 2: "zone/subzone" (used by HarvestMap)
-- If 2nd argument is nil or false, function returns first format
-- Additionally if the third argument bKeepMapNBum is true you will preserve
-- the ending of the map texture.
-- 3: "zone/subzone_0" or "zone", "subzone_0" (used by Destinations)
Example:
Lua Code:
-- "Art/maps/skyrim/blackreach_base_0.dds",
zone, subzone = LMP:GetZoneAndSubzone()
-- returns skyrim, blackreach_base
-- "Art/maps/skyrim/blackreach_base_0.dds",
zone, subzone = LMP:GetZoneAndSubzone(false, false, true)
-- returns skyrim, blackreach_base_0
--"Art/maps/skyrim/blackreach_base_0.dds",
texturename = LMP:GetZoneAndSubzone(true)
-- returns skyrim/blackreach_base
-- "art/maps/murkmire/ui_map_tsofeercavern01_0.dds",
texturename = LMP:GetZoneAndSubzone(true, true)
-- returns murkmire/tsofeercavern01
-- "Art/maps/skyrim/blackreach_base_0.dds",
texturename = LMP:GetZoneAndSubzone(true, false, true)
-- returns skyrim/blackreach_base_0
Example of code is attached to the end of LibMapPins-1.0.lua or check code of
SkyShards or
LoreBooks.