API ChatFrame AddMessageEventFilter

Main Menu
WoW API Lua API FrameXML util Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

→ FrameXML Funcs

→ FrameXML Docs

This function is implemented in :AddMessageEventFilter FrameXML/ChatFrame.lua.

Manipulates FrameXML's list of chat event filters. Added to in 2.4.

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(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 (including the arg1 global) is replaced with your return.

Example filter implementation

Writing a filter is fairly straightforward:

local myChatFilter(msg)
  if strfind(msg, "buy gold") then
    return true
  end
  if arg2=="Knownspammer" then
    return true
  end
  if strfind(msg, "lol") then
    return false, gsub(msg, "lol", "")
  end
end

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

You should use the passed-in "msg" parameter rather than accessing the global arg1. As for the other values, there really is no other way than to access the globals, unfortunately.

Example Chatframe addon use

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

local myChatEventHandler(event)

  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

Note that you should use the global arg1 here as in the example; otherwise filters may misbehave. There is no telling if they will look at the global arg1 or the passed-in parameter.