Krowi's World Map Buttons

A library for World of Warcraft addon development that simplifies adding custom buttons to the world map interface with automatic positioning and dynamic layout management
1. Default WoW buttons
2. Two additional buttons added but 1 is hidden
3. Two additional buttons but hidden one is now also shown

1. Default WoW buttons 2. Two additional buttons added but 1 is hidden 3. Two additional buttons but hidden one is now also shown

Description

A library for World of Warcraft addon development that simplifies adding custom buttons to the world map interface with automatic positioning and dynamic layout management.

Features

World Map Button Library (Krowi_WorldMapButtons-1.4)

  • Easy Button Integration: Add custom buttons to the world map with a single function call
  • Automatic Positioning: Buttons line up in one row with Blizzard's own map buttons, in a top corner of the map
  • Dynamic Layout: Hidden buttons leave no gap in the row
  • Multi-Version Support: Works on Retail, Mists of Pandaria Classic, WoW Forever and the 1.x to 3.x Classic clients (Classic Era, Anniversary, Titan Reforged)
  • Default Button Integration: Blizzard's map buttons (on Retail the tracking options and map pin buttons) take the first places in the row
  • Independent: No dependency on other addons for world map modifications
  • LibStub Support: Standard LibStub library structure for dependency management

Usage Examples

Basic Button Setup

local WorldMapButtons = LibStub("Krowi_WorldMapButtons-1.4")

-- Your template's mixin must have a Refresh method, see below
local button = WorldMapButtons:Add("YourAddon_WorldMapButton_Template", "BUTTON")

Button Mixin Example

Only Refresh is required by the library. The other methods are the scripts of the sample template.

YourAddon_WorldMapButtonMixin = {}

function YourAddon_WorldMapButtonMixin:OnLoad()
    -- Initialize your button
end

function YourAddon_WorldMapButtonMixin:OnMouseDown(button)
    -- Handle mouse down event
end

function YourAddon_WorldMapButtonMixin:OnMouseUp()
    -- Handle mouse up event
end

function YourAddon_WorldMapButtonMixin:OnClick()
    -- Handle click event
end

function YourAddon_WorldMapButtonMixin:OnEnter()
    -- Show tooltip or highlight
end

function YourAddon_WorldMapButtonMixin:OnHide()
    -- Clean up when hidden
end

function YourAddon_WorldMapButtonMixin:Refresh()
    -- Required: called after every map change, before the row is laid out again
    -- Use this to update button state:
    -- self:Enable(), self:Disable(), self:Show(), self:Hide()
end

Button Template Example (XML)

See ButtonTemplate.xml for a complete example template.

Button Without a Template

local button = WorldMapButtons:Add(nil, "BUTTON")
button:SetSize(32, 32)
function button:Refresh()
end

Showing or Hiding Your Button

-- Outside a map change, lay the row out again yourself so no gap is left
button:SetShown(showButton)
WorldMapButtons.SetPoints()

Custom Offset Configuration

local WorldMapButtons = LibStub("Krowi_WorldMapButtons-1.4")

-- Moves the start of the whole row, so every addon's buttons move with it
WorldMapButtons:SetOffsets(8, -4)  -- xOffset, yOffset

Loading a newer copy of the library resets the offsets, so set them once all addons have loaded (PLAYER_LOGIN or later). They apply from the next map change or SetPoints() call.

API Reference

Library Functions

Function Parameters Returns Description
Add(templateName, templateType) templateName (string or nil), templateType (string) frame Creates a button from the template, places it at the end of the row and returns it
SetOffsets(xOffset, yOffset) xOffset (number, optional), yOffset (number, optional) - Moves the start of the row. Defaults: xOffset=4, yOffset=-2 (WoW Forever: 3, 0)
SetPoints() - - Lays the row out again. Call it as WorldMapButtons.SetPoints() after showing or hiding your button outside a map change

Add() Parameters

Parameter Type Required Description
templateName string No The name of your button template defined in XML. With nil the button is created bare and you build it in code
templateType string Yes The frame type, typically "BUTTON"; "DropdownButton" works on clients that have it

Returns: The created button, named Krowi_WorldMapButtons<n>. Its parent is WorldMapFrame, or on Classic Era, Anniversary and Titan Reforged WorldMapFrame.ScrollContainer with TOOLTIP strata.

Button Methods

The library calls one method on your button:

Method Parameters Description
Refresh() - Required. Called after every map change, before the row is laid out again. Update button state here

Refresh runs inside Blizzard's map update, so keep it free of errors.

Library Properties

Property Type Description
IsMainline boolean True on Retail (11.x and later) and WoW Forever; buttons stack downwards
IsForever boolean True on WoW Forever
HasNoOverlay boolean True on Classic Era, Anniversary and Titan Reforged; buttons are parented to WorldMapFrame.ScrollContainer
AnchorPoint string The corner the row starts in: "TOPRIGHT", or "TOPLEFT" on WoW Forever
XOffset number Horizontal offset for the start of the row (default: 4; WoW Forever: 3)
YOffset number Vertical offset for the start of the row (default: -2; WoW Forever: 0)
Buttons table Array of all buttons in the row, in order, Blizzard's first

Positioning Behavior

Retail

  • Buttons are stacked vertically from top to bottom
  • Position: Top-right corner of the map, below Blizzard's tracking options and map pin buttons
  • Each button is 32 pixels below the previous one

WoW Forever

  • Buttons are stacked vertically from top to bottom
  • Position: Top-left corner of the map, below Blizzard's map pin button
  • Each button is 32 pixels below the previous one
  • The tracking options button stays where Blizzard puts it, next to the nav bar

Mists of Pandaria Classic, Classic Era, Anniversary and Titan Reforged

  • Buttons are arranged horizontally from right to left
  • Position: Top-right corner of the map
  • Each button is 32 pixels to the left of the previous one

Dynamic Layout

  • After every map change, and whenever SetPoints() is called, the shown buttons close up so a hidden button leaves no gap
  • Buttons keep the order in which they were added, after Blizzard's buttons

Technical Details

Version Detection

The library reads the major version from GetBuildInfo():

  • 11 and later: Retail
  • 5: Mists of Pandaria Classic
  • 1 to 3, with WorldMapTrackingPinButtonMixin: WoW Forever, which runs Retail's world map
  • 1 to 3, without it: Classic Era, Anniversary and Titan Reforged

Refresh Hook

Each button hooks WorldMapFrame.OnMapChanged on every client. The hook calls the button's Refresh() and then SetPoints().

Blizzard calls OnMapChanged only when the map shows a different map than before:

  • Opening the world map for the first time, or on another map than it was closed on
  • Switching between different maps
  • Changing continents or zones

Zooming does not call it, and neither does reopening the map on the map it was closed on.

Use Cases

  • Quick access to addon features from the world map
  • Toggle visibility of custom map overlays or pins
  • Open addon configuration panels
  • Display addon-specific information
  • Navigate to addon-related content
  • Filter or search map data
  • Any functionality requiring map-context interaction

Requirements

  • LibStub

License

BSD 3-clause, see LICENSE. It covers every 1.4 release, including those before 1.4.12.

Krowi's World Map Buttons Team

profile avatar
Owner
High Crafter tier icon
  • 15
    Followers
  • 15
    Projects
  • 3.0M
    Downloads
Donate

More from KrowiView all