WoW API: ChatFrame:AddMessageEventFilter

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ WoW API

← WoW API < ChatFrame:AddMessageEventFilter

This function is implemented in Lua here FrameXML/ChatFrame.lua.

Manipulates FrameXML's list of chat event filters.

ChatFrame_AddMessageEventFilter("event", filterFunc)

ChatFrame_RemoveMessageEventFilter("event", filterFunc)

filterFuncList = ChatFrame_GetMessageEventFilters("event")

Arguments

("event", filterFunc)

"event"

String - name of the event to filter for

filterFunc

Function - your filtering function; see below for details

Returns

filterFuncList

Table - a (currently integer-indexed) list of filter functions

filterFunc

filter[, "optionalNewMsg"] = myFilterFunc(self, event, msg, ...)

The passed-in message is the same as arg1. Other parameters of the event are available through the standard globals "event", "arg2", "arg3", etc.

If your function returns true, the message is discarded.

If your function returns the second parameter as non-false/nil, the current message text is replaced with your return. In 2.4, the global arg1 was replaced with the changed message text. In 3.0, it is not.

Note that your function might be called more than once per message. It's possible to get two calls for whisper, say, and yell messages, and seven for channel messages. Due to this non-deterministic calling, your filter function should not have side-effects.

Example filter implementation

Writing a filter is fairly straightforward:

local function myChatFilter(self, event, ...)
  local msg, author = ...
  if msg:find("buy gold") then
    return true
  end
  if author == "Knownspammer" then
    return true
  end
  if msg:find("lol") then
    return false, gsub(msg, "lol", "")
  end
end

ChatFrame_AddMessageEventFilter("CHAT_MSG_CHANNEL", myChatFilter)
ChatFrame_AddMessageEventFilter("CHAT_MSG_SAY", myChatFilter)
ChatFrame_AddMessageEventFilter("CHAT_MSG_YELL", myChatFilter)
ChatFrame_AddMessageEventFilter("CHAT_MSG_WHISPER", myChatFilter)

You should use the variables passed in ... rather than the global arg1, arg2 etc

3.1 Update: The filter function is no longer passed (msg). It is now passed the chat frame, the event and arg1, arg2 ... arg11. You must also return arg1, arg2 ... arg11.

local function myChatFilter(ChatFrameSelf, event, ...)  -- ... = arg1, arg2, arg3...arg11
  local msg, author = ... -- author only applies if its a message in guild chat or whisper, not if it's a system message
  if msg:find("buy gold") then
    return true --ignore the message
  end
  if author=="Knownspammer" then
    return true --ignore the message
  end
  if msg:find("lol") then
    local newMsg = gsub(msg, "lol", "")
    return false, newMsg, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11 --substitute newMsg for msg when returning
  end
end

Example Chatframe addon use

Chatframe addons / whisper managers etc should of course make use of these filters.

local function myChatEventHandler(self,event,arg1,...)
  local filterFuncList = ChatFrame_GetMessageEventFilters(event)
  if filterFuncList then
    for _, filterFunc in pairs(filterFuncList) do
      local filter, newarg1 = filterFunc(arg1)
      if filter then 
        return
      end
      arg1 = (newarg1 or arg1);
    end
  end

  -- whoop de do, not filtered, go about our business and display etc
end

Details

This set of functions was added in patch 2.4.

Re-adding an already-existing filter is harmless - the second addition is ignored.

Removing a filter that has not been added is harmless - there is no error.

You first have to define your filter function - local filterfunc(self,event,arg1,...) - and after that use ChatFrame_AddMessageEventFilter("event", filterfunc) in your lua code.

All possible chat events, that can be used are listed here.