Manipulates FrameXML's list of chat event filters.
ChatFrame_AddMessageEventFilter("event", filterFunc) ChatFrame_RemoveMessageEventFilter("event", filterFunc) filterFuncList = ChatFrame_GetMessageEventFilters("event")
- String - name of the event to filter for
- Function - your filtering function; see below for details
- table - an array of filter functions. This is the same table as is used by the filtering system.
filter, arg1, arg2, arg3, ..., arg11 = myFilterFunc(chatFrame, event, arg1, arg2, arg3, ..., arg11);
For most chat events, arg1 is the message text.
- Boolean: if true, the message is discarded.
- arg1, arg2, ... arg11
- Mixed: if filter is non-true, and arg1 is non-nil/false, the 11 returned values after filter replace the 11 arguments provided to the function for subsequent filtering purposes. Note that the environment arg1-arg11 aren't replaced: only the filter function arguments (and subsequent ChatFrame code) are affected.
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.
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
- 3.1 change: The filter function is no longer passed "(msg)".
- It is now passed the chat frame, the event and arg1, arg2 ... arg11.
- If you return a non-nil arg1, you must also return all of arg2 ... arg11
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
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.