Adds a function to filter or alter messages to the chat display system. The filter function will be called each time a message is sent to one of the default chat frames (ChatFrame1, ChatFrame2, ..., ChatFrame7). The function will be passed the chat frame object that the message is being added to, along with the event that caused the messages to be added, and the arguments to that event.

A filter function may return true if the message should be filtered , or false if the message should be displayed. Following this boolean flag, the message can return a list of (possibly) altered arguments to be passed to the next filter function.

Note that your function will be called at least once for every ChatFrame the message-event is registered for. Currently (due to what appears to be a bug) the filter is actually called twice for each frame. Due to this non-deterministic calling, your filter function should not have side-effects.

See examples for details.


See also Chat functions.

Signature:

ChatFrame_AddMessageEventFilter("event", filter)

Arguments:

  • event - A CHAT_MSG_ Event for which the filter should be used (string)
  • filter - A function to filter incoming messages (function)

Examples:

-- a filter to hide all yelled messaged containing certain text
function noGoldSpam(self,event,msg)
  local badWords = {"gold","%$","www","%.com","%.net","%.org"}
  local matchCount = 0;
  for _, word in ipairs(badWords) do
    if (string.match(msg, word)) then
      matchCount = matchCount + 1;
    end
  end
  if (matchCount > 1) then
    return true;
  else
    return false;
  end
end
ChatFrame_AddMessageEventFilter("CHAT_MSG_YELL",noGoldSpam)

-- a filter to display icons next to item links in loot messages
function addLootIcons(self, event, msg, ...)
  local _, fontSize = GetChatWindowInfo(self:GetID())
  local function iconForLink(link)
    local texture = GetItemIcon(link)
    return "\124T"..texture..":"..fontSize.."\124t"..link
  end
  msg = string.gsub(msg,"(\124c%x+\124Hitem:.-\124h\124r)",iconForLink)
  return false, msg, ...
end
ChatFrame_AddMessageEventFilter("CHAT_MSG_LOOT", addLootIcons)
This function is not a C API but a Lua function declared in Blizzard's default user interface. Its implementation can be viewed by extracting the addon data using the Addon Kit provided by Blizzard.
This function is defined by the default user interface in Lua. You can find the definition by examining the FrameXML code for the default UI,