Editing WoW:API ChatFrame AddMessageEventFilter

{{framexmlfunc|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

:{{icon-exclamation}}'''3.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]].

__NOTOC__