Krowi's Menu

A lightweight menu library for World of Warcraft addon development that simplifies creating dropdown menus with support for titles, separators, nested items, and custom styling.

Features

Menu System (Krowi_Menu)

• Simple API: Easy-to-use methods for building menus programmatically
• Flexible Menu Items: Support for titles, separators, checkable items, and disabled states
• Nested Menus: Create hierarchical menu structures with children
• Smart Positioning: Automatic submenu repositioning to keep menus on-screen (Classic)
• Custom Styling: Control menu positioning, frame strata, and frame levels
• Selection State: Track and refresh selected menu items
• Krowi_LibMan Integration: Modern library management with Krowi_LibMan

Menu Item Builder (Krowi_MenuItem)

• Item Creation: Build menu items with custom properties
• External Links: Integration with popup dialogs for displaying external links
• Child Items: Support for nested menu structures
• Flexible Options: Checkable, disabled, and title items

Menu Utilities (Krowi_MenuUtil)

• Cross-Version Compatibility: Unified API for both modern (Mainline) and Classic WoW versions
• Automatic Detection: Detects game version and uses appropriate menu system
• Simplified Interface: Consistent methods across all WoW versions

Menu Builder (Krowi_MenuBuilder)

• High-Level Abstraction: Simplified API for building complex menus with checkboxes, radio buttons, and filters
• Callback-Based Architecture: Flexible callback system for handling menu interactions and state management
• Smart Defaults: Automatic integration with Krowi_Util_2 for common operations (KeyIsTrue, KeyEqualsText)
• Callback Helper: BindCallbacks utility eliminates boilerplate when binding object methods to callbacks
• Build Version Filters: Built-in support for creating hierarchical version filter menus with Select/Deselect All
• Cross-Version Support: Unified API that works seamlessly on both Modern (Mainline) and Classic WoW
• Instance-Based: Create multiple independent menu builders with isolated state and configurations
• Type Safety: Full parameter validation with helpful error messages

Usage Examples

Basic Menu Setup

local menu = KROWI_LIBMAN:GetLibrary('Krowi_Menu_2')
local pages = {} -- Table with data

menu:Clear() -- Reset menu

menu:AddFull({Text = "View Pages", IsTitle = true})
for i, _ in next, pages do
  menu:AddFull({
    Text = (pages[i].IsViewed and "" or "|T132049:0|t") .. pages[i].SubTitle,
    Func = function()
      -- Some function here
    end
  })
end

menu:Open()

Advanced Example with Nested Menus

local menu = KROWI_LIBMAN:GetLibrary('Krowi_Menu_2')
local menuItem = KROWI_LIBMAN:GetLibrary('Krowi_MenuItem_2')

menu:Clear()

-- Create a parent item with children
local parent = menuItem:New({Text = "Settings"})
parent:AddFull({
  Text = "Enable Feature",
  Checked = true,
  Func = function() print("Feature toggled") end
})
parent:AddSeparator()
parent:AddFull({
  Text = "Reset to Defaults",
  Func = function() print("Reset") end
})

menu:Add(parent)
menu:Open("cursor")

MenuBuilder Example

local MenuBuilder = KROWI_LIBMAN:GetLibrary('Krowi_MenuBuilder_2')

-- Configure MenuBuilder with callbacks using BindCallbacks helper
local config = {
    callbacks = MenuBuilder.BindCallbacks(self, {
        GetCheckBoxStateText = "GetCheckBoxStateText",
        KeyIsTrue = "KeyIsTrue",
        OnCheckboxSelect = "OnCheckboxSelect",
        KeyEqualsText = "KeyEqualsText",
        OnRadioSelect = "OnRadioSelect"
    }),
    translations = {
        ["Select All"] = "Select All",
        ["Deselect All"] = "Deselect All",
        ["Version"] = "Version"
    }
}

local builder = MenuBuilder:New(config)

-- Modern WoW: Setup menu on a dropdown button
if WOW_PROJECT_ID == WOW_PROJECT_MAINLINE then
    builder:SetupMenuForModern(myDropdownButton)

    -- Define the menu structure
    function builder:CreateMenu()
        local menu = self:GetMenu()
        self:CreateTitle(menu, "Filter Options")
        self:CreateCheckbox(menu, "Show Completed", filters, {"Completed"})
        self:CreateCheckbox(menu, "Show In Progress", filters, {"InProgress"})
        self:CreateDivider(menu)

        local sortMenu = self:CreateSubmenuButton(menu, "Sort By")
        self:CreateRadio(sortMenu, "Name", filters, {"SortBy"}, "name")
        self:CreateRadio(sortMenu, "Date", filters, {"SortBy"}, "date")
    end
else
    -- Classic WoW: Show menu manually
    function builder:CreateMenu()
        local menu = self:GetMenu()
        self:CreateTitle(menu, "Filter Options")
        self:CreateCheckbox(menu, "Show Completed", filters, {"Completed"})
        self:CreateCheckbox(menu, "Show In Progress", filters, {"InProgress"})
        self:CreateDivider(menu)

        local sortMenu = self:CreateSubmenuButton(menu, "Sort By")
        self:CreateRadio(sortMenu, "Name", filters, {"SortBy"}, "name")
        self:CreateRadio(sortMenu, "Date", filters, {"SortBy"}, "date")
        self:AddChildMenu(menu, sortMenu)
    end

    -- Show the menu when needed
    builder:Show(frameAnchor, 0, 0)
end

Callback Implementation Example

-- Example object that implements menu callbacks
local MyAddon = {}

function MyAddon:GetCheckBoxStateText(text, filters, keys)
    -- Add visual indicators to checkbox text
    local isChecked = self:KeyIsTrue(filters, keys)
    return (isChecked and "|cFF00FF00✓ |r" or "|cFF808080○ |r") .. text
end

function MyAddon:KeyIsTrue(filters, keys)
    -- Read nested keys from filters table (auto-provided if Krowi_Util-1.0 is available)
    local value = filters
    for _, key in ipairs(keys) do
        value = value[key]
        if value == nil then return false end
    end
    return value == true
end

function MyAddon:OnCheckboxSelect(filters, keys)
    -- Toggle the filter value
    local value = filters
    for i = 1, #keys - 1 do
        value = value[keys[i]]
    end
    local finalKey = keys[#keys]
    value[finalKey] = not value[finalKey]

    -- Refresh UI
    self:UpdateDisplay()
end

function MyAddon:KeyEqualsText(filters, keys, text)
    -- Check if filter equals specific value
    local value = filters
    for _, key in ipairs(keys) do
        value = value[key]
        if value == nil then return false end
    end
    return value == text
end

function MyAddon:OnRadioSelect(filters, keys, value)
    -- Set the filter to selected value
    local filterTable = filters
    for i = 1, #keys - 1 do
        filterTable = filterTable[keys[i]]
    end
    filterTable[keys[#keys]] = value

    -- Refresh UI
    self:UpdateDisplay()
end

API Reference

Krowi_Menu

Creating a Menu

local menu = KROWI_LIBMAN:GetLibrary('Krowi_Menu_2')

Menu Functions

Open() Parameters

Menu Item Info Table

Krowi_MenuItem

Creating Menu Items

local menuItem = KROWI_LIBMAN:GetLibrary('Krowi_MenuItem_2')

MenuItem Functions

Krowi_MenuUtil

Creating Utilities Instance

local menuUtil = KROWI_LIBMAN:GetLibrary('Krowi_MenuUtil_2')

MenuUtil Functions

Note: MenuUtil automatically detects whether the game is running Mainline or Classic and uses the appropriate menu system. On Mainline, it uses the modern menu API. On Classic versions, it uses the Krowi_MenuItem library.

Krowi_MenuBuilder

Creating a MenuBuilder Instance

local MenuBuilder = KROWI_LIBMAN:GetLibrary('Krowi_MenuBuilder_2')
local builder = MenuBuilder:New(config)

Configuration Object

The configuration object passed to MenuBuilder:New(config) supports the following fields:

Example Configuration:

local config = {
    callbacks = {
        GetCheckBoxStateText = function(text, filters, keys) return text end,
        KeyIsTrue = function(filters, keys) return false end,
        OnCheckboxSelect = function(filters, keys, ...) end,
        KeyEqualsText = function(filters, keys, value) return false end,
        OnRadioSelect = function(filters, keys, value, ...) end,
        -- Optional version filter callbacks
        IsMinorVersionChecked = function(filters, minor) return false end,
        OnMinorVersionSelect = function(filters, minor) end,
        IsMajorVersionChecked = function(filters, major) return false end,
        OnMajorVersionSelect = function(filters, major) end,
        OnAllVersionsSelect = function(filters, value) end,
        CreateBuildVersionFilterGroups = function(version, filters, menuBuilder) end
    },
    translations = {
        ["Select All"] = "Select All",
        ["Deselect All"] = "Deselect All",
        ["Version"] = "Version"
    },
    uniqueTag = "MyAddonMenu"
}

Callback Reference

MenuBuilder uses callbacks to interact with your addon's data and respond to user interactions. Callbacks are optional unless specified as required.

Checkbox Callbacks:

Radio Button Callbacks:

Build Version Filter Callbacks (Optional - only needed if using CreateBuildVersionFilter):

General Callbacks:

Notes:

• *KeyIsTrue and KeyEqualsText have smart defaults if Krowi_Util_2 library is available
• keys parameter is always an array representing nested path, e.g., {"Filters", "ShowCompleted"}
• filters is your addon's filter data structure
• Varargs (...) allow passing custom context to callbacks

MenuBuilder Utility Functions

Example:

-- Instead of manually creating callbacks like this:
local config = {
    callbacks = {
        OnCheckboxSelect = function(filters, keys, ...)
            return MyAddon:OnCheckboxSelect(filters, keys, ...)
        end,
        OnRadioSelect = function(filters, keys, value, ...)
            return MyAddon:OnRadioSelect(filters, keys, value, ...)
        end
    }
}

-- Use BindCallbacks to eliminate boilerplate:
local config = {
    callbacks = MenuBuilder.BindCallbacks(MyAddon, {
        OnCheckboxSelect = "OnCheckboxSelect",
        OnRadioSelect = "OnRadioSelect"
    })
}

MenuBuilder Methods

MenuBuilder Methods

Menu Management:

Menu Building:

All methods support optional menu parameter. If omitted, uses GetMenu().

Specialized Menu Builders:

Important Notes:

• Modern vs Classic: Some methods behave differently or are no-ops depending on WOW_PROJECT_ID
• Menu Parameter: When menu is nil, methods automatically use GetMenu()
• Varargs: Extra parameters passed to CreateCheckbox and CreateRadio are forwarded to callbacks for custom context

Use Cases

• Right-click context menus
• Dropdown selection menus
• Settings and options menus
• Action selection menus
• Navigation menus
• Custom frame menus
• Any scenario requiring dropdown menu functionality

Requirements

• Krowi_LibMan
• Krowi_Util_2 (optional, for default MenuBuilder callbacks)