ChatFrame :AddMessageEventFilter()
- This function is implemented in
.:AddMessageEventFilter FrameXML/ChatFrame.lua
- This function is implemented in
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, ..., arg11 = myFilterFunc(chatFrame, event, arg1, arg2, arg3, ..., arg11);
For most chat events, arg1 is the message text.
Return values
- filter
- 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
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.