AddOn Studio Wiki
Advertisement

WoW API < ChatFrame:AddMessageEventFilter

"I" iconThis 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"
String - name of the event to filter for
filterFunc
Function - your filtering function; see below for details

Returns[]

filterFuncList
table - an array of filter functions. This is the same table as is used by the filtering system.

filterFunc[]

filter, arg1, arg2, arg3, ..., arg15 = myFilterFunc(chatFrame, event, arg1, arg2, arg3, ..., arg15);

For most chat events, arg1 is the message text.

Return values[]

filter
Boolean: if true, the message is discarded.
arg1, arg2, ... arg15
Mixed: if filter is non-true, and arg1 is non-nil/false, the 15 returned values after filter replace the 15 arguments provided to the function for subsequent filtering purposes. Note that the environment arg1-arg15 aren't replaced: only the filter function arguments (and subsequent ChatFrame code) are affected.

Note that your function will be called once for every frame the message-event is registered for. 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, 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", ""), author, ...
  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 into the function rather than the global arg1, arg2 etc

Red exclamation mark icon3.1 change: The filter function is no longer passed "(msg)".
It is now passed the chat frame, the event and arg1, arg2 ... arg15.
If you return a non-nil arg1, you must also return all of arg2 ... arg15

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(self,event,arg1,...)
      if filter then 
        return
      end
      if newarg1 then
        arg1 = newarg
        -- you should actually probably do this for all of arg2..arg11 since that's what framexml does
      end
    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. The arguments of the filter function were incompatibly changed in patch 3.1.

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 Events/Communication.


Advertisement